@kubun/plugin-p2p 0.12.0 → 0.13.0

package/lib/groups/group-protocols.js

@@ -249,6 +249,152 @@ import { defineGroupProtocol } from '@kumiai/rpc';
             additionalProperties: false
         }
     },
+    'control/credentialKeyGrant': {
+        type: 'event',
+        // Retained, and this is the load-bearing half of the design. A grant is an
+        // explicit one-shot push with no background replication and no catch-up
+        // procedure behind it: ephemeral, a recipient that was offline at grant time
+        // silently never gets access, and the only repair is a human granting again.
+        // Retention is what the app lane actually delivers — a device away across a
+        // roster change still reads the epoch's app topic on its way past it — and it
+        // costs one log frame, since the depth bound counts frames and not bytes.
+        retain: 'log',
+        description: "Hand one co-member what it needs to open a credential key: the key's public record, the single wrapping addressed to that member, and every entry ciphertext at that version. Group-wide because confidentiality is content-level; only the addressed DID applies it. `auth` signs identifiers and content digests, and the receiver recomputes both from this frame.",
+        data: {
+            type: 'object',
+            properties: {
+                keyID: {
+                    type: 'string'
+                },
+                keyVersion: {
+                    type: 'number'
+                },
+                suite: {
+                    type: 'number'
+                },
+                ownerDID: {
+                    type: 'string',
+                    description: 'Claimed owner. A mirror — the receiver stores the `auth` issuer instead.'
+                },
+                keyOp: {
+                    type: 'string',
+                    description: "The granter's signed op for the key row, stored verbatim. The key row rides inline on this frame, so its op has nowhere else to hang."
+                },
+                keyBranches: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: "The proven key-op JWTs that introduced this key version's branches."
+                },
+                wrapping: {
+                    type: 'object',
+                    properties: {
+                        wrappingID: {
+                            type: 'string'
+                        },
+                        factors: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    kind: {
+                                        type: 'string'
+                                    },
+                                    params: {
+                                        type: 'object',
+                                        description: 'Per-kind PUBLIC material — a salt or an ephemeral public key.',
+                                        additionalProperties: true
+                                    }
+                                },
+                                required: [
+                                    'kind',
+                                    'params'
+                                ],
+                                additionalProperties: false
+                            },
+                            description: 'ORDERED, and bound into the wrapping AAD: a permuted copy will not open.'
+                        },
+                        iv: {
+                            type: 'string',
+                            description: 'base64url'
+                        },
+                        wrappedKey: {
+                            type: 'string',
+                            description: 'base64url'
+                        },
+                        recipientDID: {
+                            type: 'string',
+                            description: 'Un-normalized: a key-resolution input, not an identity to compare.'
+                        },
+                        op: {
+                            type: 'string',
+                            description: "The granter's signed op for this row, stored verbatim — the receiver never mints its own."
+                        }
+                    },
+                    required: [
+                        'wrappingID',
+                        'factors',
+                        'iv',
+                        'wrappedKey',
+                        'recipientDID',
+                        'op'
+                    ],
+                    additionalProperties: false
+                },
+                entries: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            entryID: {
+                                type: 'string'
+                            },
+                            iv: {
+                                type: 'string',
+                                description: 'base64url'
+                            },
+                            ciphertext: {
+                                type: 'string',
+                                description: 'base64url'
+                            },
+                            hlc: {
+                                type: 'string'
+                            },
+                            op: {
+                                type: 'string',
+                                description: "The granter's signed op for this row, stored verbatim."
+                            }
+                        },
+                        required: [
+                            'entryID',
+                            'iv',
+                            'ciphertext',
+                            'hlc',
+                            'op'
+                        ],
+                        additionalProperties: false
+                    }
+                },
+                auth: {
+                    type: 'string',
+                    description: 'Signed credential key-grant token.'
+                }
+            },
+            required: [
+                'keyID',
+                'keyVersion',
+                'suite',
+                'ownerDID',
+                'keyOp',
+                'keyBranches',
+                'wrapping',
+                'entries',
+                'auth'
+            ],
+            additionalProperties: false
+        }
+    },
     'control/groupLeaveRequest': {
         type: 'event',
         retain: 'ephemeral',

package/lib/groups/join-utils.d.ts

@@ -116,6 +116,11 @@ export type ApplyInviteControlStateParams = {
     catalogs?: Array<InviteCatalogSeed>;
     /** Device-wide clock — the joined ledger's HLCs merge into it. */
     hlc: HLC;
+    /**
+     * How far into the future an adopted entry's `ord` may sit before its clock
+     * merge is refused — see `LedgerIngestParams.maxDriftMS`.
+     */
+    maxDriftMS?: number;
     /** Resolves the group's genesis anchor so ledger entries can project at join. */
     getGroupAnchor?: (groupID: string) => Promise<GroupAnchor | null>;
     /** Resolves the group's control ledger, which every projection folds from. */

package/lib/groups/join-utils.js

@@ -5,9 +5,10 @@ import { getGraphStore } from '@kubun/store-graph';
 import { getP2PStore } from '@kubun/store-p2p';
 import { canonicalStringify } from '@sozai/codec';
 import { toISO } from '../context/types.js';
+import { applyAccessDefaultSetFrame } from './access-default-apply.js';
 import { signAccessDefaultSet } from './access-default-token.js';
-import { adoptHandleLedgerState, applyAccessDefaultSetFrame } from './broadcast.js';
 import { verifyCatalog } from './catalog-token.js';
+import { adoptHandleLedgerState } from './ledger-adopt.js';
 import { storeReceivedGrant } from './store-received-grant.js';
 import { storeReceivedRevocation } from './store-received-revocation.js';
 /**
@@ -261,6 +262,9 @@ export async function finalizeJoinedGroup(params) {
         await adoptHandleLedgerState({
             p2pStore,
             hlc,
+            ...params.maxDriftMS != null ? {
+                maxDriftMS: params.maxDriftMS
+            } : {},
             getGroupAnchor,
             getGroupLedger,
             // Only the projection rebuild is transactional. The adopt reads the

package/lib/groups/ledger-adopt.d.ts

@@ -0,0 +1,84 @@
+import type { P2PStoreAPI } from '@kubun/store-p2p';
+import type { RosterState } from '@kumiai/mls';
+import { type LedgerIngestParams } from './ledger-ingest.js';
+/** Summary of a whole-ledger adoption. */
+type ApplyLedgerCatchupReplyResult = {
+    /** Size of the ledger that was adopted. */
+    applied: number;
+    /**
+     * Always `0` on this path, and structurally so: the install verifies the whole
+     * ledger against the authenticated head before folding a single entry, so a
+     * bad token rejects the batch rather than dropping an entry out of it. Carried
+     * because the catch-up summary reports it beside counts from paths that CAN
+     * drop per entry.
+     */
+    rejected: number;
+};
+/** Inputs the ledger-fold helpers need — a strict subset of the receive params. */
+export type ApplyLedgerEntriesParams = LedgerIngestParams & {
+    /**
+     * Run the projection rebuild atomically, given the store to write it through.
+     *
+     * A rebuild materializes several tables from one fold — circle rows, every
+     * circle's `open` flag, the group row, the commit-hub designation — and a crash
+     * between them leaves them disagreeing. A device with no flagged commit hub
+     * cannot commit at all, which reads as a hang rather than an error.
+     *
+     * A seam rather than a `StoreProvider` because the surrounding operations must
+     * NOT be in the same transaction: an install or a gather waits on the network,
+     * and a transaction spanning one holds kubun's single SQLite connection across
+     * it. So the caller decides what the transaction covers. Omitted, the rebuild
+     * runs on {@link LedgerIngestParams.p2pStore} unwrapped — correct when the
+     * caller already holds a transaction, and self-healing on the bootstrap paths,
+     * where the next reproject rebuilds from the same ledger anyway.
+     *
+     * Declared here rather than on {@link LedgerIngestParams} because only the
+     * batch folds below read it: `ingestVerifiedLedgerEntry` reprojects through
+     * `p2pStore` directly, so a caller passing this to the single-entry path would
+     * be promised an atomicity it does not get.
+     */
+    withProjectionTransaction?: (run: (store: P2PStoreAPI) => Promise<void>) => Promise<void>;
+};
+/**
+ * Adopt the control state a handle already holds: merge the HLCs its entries
+ * carry into this device's clock, then rebuild every projection from them.
+ *
+ * For a peer whose handle was filled by something other than a landed commit —
+ * a joiner, whose Welcome folded the group's whole ledger and checked it against
+ * the authenticated head before this device had any say. Those entries never
+ * passed through the receive path, so nothing else has observed their clocks or
+ * projected them.
+ *
+ * The merge keeps this device's later writes sorting after what the group did
+ * before it arrived. It decides no authority — that reads the enacted position —
+ * but the LWW comparisons that are not ledger folds (removal timestamps,
+ * access-default rules) still depend on a clock that has seen the group's.
+ */
+export declare function adoptHandleLedgerState(params: ApplyLedgerEntriesParams, groupID: string): Promise<void>;
+/** Inputs {@link bootstrapGroupLedger} needs on top of the ingest's. */
+export type BootstrapGroupLedgerParams = ApplyLedgerEntriesParams & {
+    /**
+     * Install a gathered WHOLE ledger into the group's handle, verified against
+     * the authenticated head before a single entry is folded, and answer with the
+     * roster the install left the handle holding. Throws when the list does not
+     * reproduce that head.
+     *
+     * The roster is returned rather than read back afterwards so it is the one the
+     * install itself produced, taken while the handle is still held: a second read
+     * could observe a handle another operation has since advanced.
+     */
+    installGroupLedger: (groupID: string, tokens: Array<string>) => Promise<RosterState>;
+};
+/**
+ * Adopt a whole ledger gathered from one untrusted responder.
+ *
+ * Signatures do NOT cover omission or reordering — a responder can hand back
+ * genuine tokens with a demotion missing — so the list is installed against the
+ * authenticated head FIRST and rejected whole on mismatch, before anything is
+ * projected. Roles are reconciled against the roster the install folded, not the
+ * ledger, because nothing later revisits a stale `admin` row.
+ *
+ * Throws whatever the install throws — a rejected ledger changes nothing.
+ */
+export declare function bootstrapGroupLedger(params: BootstrapGroupLedgerParams, tokens: Array<string>, groupID: string): Promise<ApplyLedgerCatchupReplyResult>;
+export {};

package/lib/groups/ledger-adopt.js

@@ -0,0 +1,142 @@
+import { reprojectCircleDefs, reprojectCircleMembers, reprojectGroupSettings } from './circle-projection.js';
+import { entryOrd } from './ledger.js';
+import { resolveGroupAnchor, usableLedgerOrd } from './ledger-ingest.js';
+import { mirrorRosterRoles } from './roster-projection.js';
+/**
+ * Adopt the control state a handle already holds: merge the HLCs its entries
+ * carry into this device's clock, then rebuild every projection from them.
+ *
+ * For a peer whose handle was filled by something other than a landed commit —
+ * a joiner, whose Welcome folded the group's whole ledger and checked it against
+ * the authenticated head before this device had any say. Those entries never
+ * passed through the receive path, so nothing else has observed their clocks or
+ * projected them.
+ *
+ * The merge keeps this device's later writes sorting after what the group did
+ * before it arrived. It decides no authority — that reads the enacted position —
+ * but the LWW comparisons that are not ledger folds (removal timestamps,
+ * access-default rules) still depend on a clock that has seen the group's.
+ */ export async function adoptHandleLedgerState(params, groupID) {
+    const { hlc, logger } = params;
+    if (hlc != null && params.getGroupLedger != null) {
+        let ledger;
+        try {
+            ledger = await params.getGroupLedger(groupID);
+        } catch (error) {
+            // The reproject below reads the ledger through the same resolver and
+            // defers on its own when it cannot; losing the merge is not worth failing
+            // a join over.
+            logger?.warn('ledger clock merge skipped: ledger unreadable', {
+                groupID,
+                error
+            });
+            ledger = [];
+        }
+        for (const { verified } of ledger){
+            // An entry `@kumiai/mls` minted itself carries no `ord` — it orders by the
+            // epoch chain and never stamps kubun's clock. Nothing to merge.
+            const ord = entryOrd(verified.entry);
+            if (ord == null) {
+                continue;
+            }
+            try {
+                const observed = usableLedgerOrd(ord, params.maxDriftMS);
+                if (observed == null) {
+                    // SKIP THE MERGE, never the entry — do not "fix" this into a
+                    // rejection. A joiner's Welcome already checked this ledger against
+                    // the authenticated head, and `ord` orders and authorizes nothing, so
+                    // dropping the entry would lose group state over a field nobody reads.
+                    logger?.warn('ledger entry carries an unusable HLC', {
+                        groupID,
+                        hlc: ord
+                    });
+                } else {
+                    hlc.receive(observed);
+                }
+            } catch (error) {
+                logger?.warn('ledger entry HLC merge failed', {
+                    groupID,
+                    hlc: ord,
+                    error
+                });
+            }
+        }
+    }
+    await reprojectControlProjections(params, groupID);
+}
+/**
+ * Rebuild every control projection from the group's whole ledger.
+ *
+ * A batch may carry any mix of entry types, so all three rebuild unconditionally
+ * rather than the caller working out which were touched; reprojecting a type the
+ * batch didn't move is a no-op that re-confirms the current rows.
+ */ async function reprojectControlProjections(params, groupID) {
+    const { p2pStore, logger } = params;
+    const resolution = await resolveGroupAnchor(params, groupID);
+    if (resolution.status !== 'anchored') {
+        logger?.debug('ledger batch applied; projection deferred', {
+            groupID,
+            reason: resolution.status === 'unknown' ? 'anchor unavailable' : 'no genesis anchor'
+        });
+        return;
+    }
+    const { anchor, ledger } = resolution;
+    // Sequential, and in this order: the circle rebuilds upsert each row's `open`
+    // from the circle fold, then the settings rebuild overwrites `open` from the
+    // authoritative open set. Running them concurrently, or settings first, lets
+    // the circle upsert win and delists nothing.
+    const rebuild = async (store)=>{
+        await reprojectCircleDefs({
+            store,
+            groupID,
+            anchor,
+            ledger,
+            logger
+        });
+        await reprojectCircleMembers({
+            store,
+            groupID,
+            anchor,
+            ledger,
+            logger
+        });
+        await reprojectGroupSettings({
+            store,
+            groupID,
+            anchor,
+            ledger,
+            logger
+        });
+    };
+    if (params.withProjectionTransaction != null) {
+        await params.withProjectionTransaction(rebuild);
+    } else {
+        await rebuild(p2pStore);
+    }
+}
+/**
+ * Adopt a whole ledger gathered from one untrusted responder.
+ *
+ * Signatures do NOT cover omission or reordering — a responder can hand back
+ * genuine tokens with a demotion missing — so the list is installed against the
+ * authenticated head FIRST and rejected whole on mismatch, before anything is
+ * projected. Roles are reconciled against the roster the install folded, not the
+ * ledger, because nothing later revisits a stale `admin` row.
+ *
+ * Throws whatever the install throws — a rejected ledger changes nothing.
+ */ export async function bootstrapGroupLedger(params, tokens, groupID) {
+    const roster = await params.installGroupLedger(groupID, tokens);
+    await reprojectControlProjections(params, groupID);
+    const members = await params.p2pStore.listGroupMembers(groupID);
+    await mirrorRosterRoles({
+        store: params.p2pStore,
+        groupID,
+        roster,
+        memberDIDs: members.map((member)=>member.member_did),
+        members
+    });
+    return {
+        applied: tokens.length,
+        rejected: 0
+    };
+}

package/lib/groups/ledger-commit-fold.d.ts

@@ -2,7 +2,7 @@ import type { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
 import type { P2PStoreAPI } from '@kubun/store-p2p';
 import { type GroupHandle, type VerifiedLedgerEntry } from '@kumiai/mls';
-import { type LedgerAffected } from './ledger-ingest.js';
+import type { LedgerAffected } from './ledger-ingest.js';
 export type CommitFoldParams = {
     /**
      * The handle that ACCEPTED the commit — post-advance. Two things are read from
@@ -35,6 +35,8 @@ export type CommitFoldParams = {
     p2pStore: P2PStoreAPI;
     groupID: string;
     hlc?: HLC;
+    /** See {@link LedgerIngestParams.maxDriftMS}. */
+    maxDriftMS?: number;
     logger?: Logger;
 };
 /** A signed token plus its notarized entry, as the handle's ledger log holds it. */

package/lib/groups/ledger-commit-fold.js

@@ -141,6 +141,9 @@ import { ingestVerifiedLedgerEntry } from './ledger-ingest.js';
                 ...params.hlc != null ? {
                     hlc: params.hlc
                 } : {},
+                ...params.maxDriftMS != null ? {
+                    maxDriftMS: params.maxDriftMS
+                } : {},
                 ...anchor != null ? {
                     getGroupAnchor: async ()=>anchor
                 } : {},

package/lib/groups/ledger-ingest.d.ts

@@ -1,4 +1,4 @@
-import { HLC } from '@kubun/hlc';
+import { HLC, type HLCTimestamp } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
 import type { Circle, CircleMember, Group, P2PStoreAPI } from '@kubun/store-p2p';
 import type { GroupAnchor, LedgerLogEntry } from '@kumiai/mls';
@@ -83,9 +83,31 @@ export type LedgerIngestParams = {
      * pass a closure over it rather than re-acquiring the lock.
      */
     getGroupLedger?: (groupID: string) => Promise<ReadonlyArray<LedgerLogEntry>>;
+    /**
+     * How far into the future an entry's `ord` may sit before this device refuses
+     * to merge it. The engine's bound, threaded here rather than configured
+     * separately. Optional: absence falls back to {@link DEFAULT_MAX_DRIFT_MS},
+     * the engine's own default, so an unthreaded caller gets the default bound and
+     * never no bound.
+     */
+    maxDriftMS?: number;
     /** Optional logger — warns on per-entry apply failures. */
     logger?: Logger;
 };
+/**
+ * The timestamp an entry's `ord` may be merged into this device's clock, or
+ * `null` when it may not.
+ *
+ * `ord` is signed but never format-checked, so a member may write anything into
+ * it: `HLC.parse` answers a malformed stamp with NaN fields rather than
+ * throwing, and a plausible-looking one may sit years ahead. Either drags the
+ * device's ONE clock — the graph mutation log's clock too — somewhere it can
+ * never catch up to.
+ *
+ * The past direction stays unbounded, as on every other lane: an offline write
+ * legitimately lands late.
+ */
+export declare function usableLedgerOrd(ord: string, maxDriftMS?: number): HLCTimestamp | null;
 /**
  * Resolve a group's anchor without ever throwing into the receive loop. A
  * missing `getGroupAnchor` (callers that never project) is treated as

package/lib/groups/ledger-ingest.js

@@ -1,8 +1,25 @@
 import { HLC } from '@kubun/hlc';
+import { DEFAULT_MAX_DRIFT_MS } from '@kubun/mutation';
 import { ADMIN_ROLE_ENTRY_TYPE } from './admin-roster.js';
 import { reprojectCircleDefs, reprojectCircleMembers, reprojectGroupSettings } from './circle-projection.js';
 import { CIRCLE_DEF_ENTRY_TYPE, CIRCLE_MEMBER_ENTRY_TYPE, decodeCircleMemberSubject, GROUP_SETTINGS_ENTRY_TYPE } from './circle-reducers.js';
 import { entryOrd } from './ledger.js';
+/**
+ * The timestamp an entry's `ord` may be merged into this device's clock, or
+ * `null` when it may not.
+ *
+ * `ord` is signed but never format-checked, so a member may write anything into
+ * it: `HLC.parse` answers a malformed stamp with NaN fields rather than
+ * throwing, and a plausible-looking one may sit years ahead. Either drags the
+ * device's ONE clock — the graph mutation log's clock too — somewhere it can
+ * never catch up to.
+ *
+ * The past direction stays unbounded, as on every other lane: an offline write
+ * legitimately lands late.
+ */ export function usableLedgerOrd(ord, maxDriftMS = DEFAULT_MAX_DRIFT_MS) {
+    const observed = HLC.tryParse(ord);
+    return observed == null || observed.wallTime - Date.now() > maxDriftMS ? null : observed;
+}
 /**
  * Resolve a group's anchor without ever throwing into the receive loop. A
  * missing `getGroupAnchor` (callers that never project) is treated as
@@ -67,7 +84,19 @@ import { entryOrd } from './ledger.js';
     const ord = entryOrd(verified.entry);
     if (params.hlc != null && ord != null) {
         try {
-            params.hlc.receive(HLC.parse(ord));
+            const observed = usableLedgerOrd(ord, params.maxDriftMS);
+            if (observed == null) {
+                // SKIP THE MERGE, never the entry — do not "fix" this into a rejection.
+                // The commit chain enacted this entry before we ran, and `ord` orders
+                // and authorizes nothing, so refusing it would drop authority the group
+                // has already agreed on over a field nobody reads.
+                params.logger?.warn('ledger entry carries an unusable HLC', {
+                    groupID,
+                    hlc: ord
+                });
+            } else {
+                params.hlc.receive(observed);
+            }
         } catch (error) {
             params.logger?.warn('ledger entry HLC merge failed', {
                 groupID,

package/lib/groups/manager.d.ts

@@ -30,6 +30,11 @@ export type GroupManagerParams = {
      * timestamps (the second would silently lose under last-writer-wins).
      */
     hlc: HLC;
+    /**
+     * How far into the future a folded control entry's `ord` may sit before its
+     * clock merge is refused — see `LedgerIngestParams.maxDriftMS`.
+     */
+    maxDriftMS?: number;
     /**
      * Device-wide store coordinator for work that runs DECOUPLED from any request
      * transaction — a commit's `onAccepted` fires on the lane, long after the

package/lib/groups/manager.js

@@ -40,7 +40,7 @@ import { mirrorRosterRoles, roleFromRoster } from './roster-projection.js';
             entryID: ledgerEntryDigest(token)
         });
     }
-    const folded = foldEnvelope(handle.roster, inputs, handle.groupID);
+    const folded = foldEnvelope(handle.roster, handle.registry, inputs, handle.groupID);
     if (!folded.ok) {
         return;
     }
@@ -52,6 +52,7 @@ export class GroupManager {
     #deviceID;
     #runtime;
     #hlc;
+    #maxDriftMS;
     #registry;
     #stores;
     #emitter;
@@ -60,6 +61,7 @@ export class GroupManager {
         this.#deviceID = params.identity.id;
         this.#runtime = params.runtime;
         this.#hlc = params.hlc;
+        this.#maxDriftMS = params.maxDriftMS;
         this.#registry = params.registry;
         this.#stores = params.stores;
         this.#emitter = params.emitter;
@@ -114,6 +116,9 @@ export class GroupManager {
                         p2pStore,
                         groupID,
                         hlc: this.#hlc,
+                        ...this.#maxDriftMS != null ? {
+                            maxDriftMS: this.#maxDriftMS
+                        } : {},
                         ...this.#logger != null ? {
                             logger: this.#logger
                         } : {}

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

@@ -2,8 +2,8 @@ import type { StoreProvider } from '@kubun/db';
 import { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
 import type { GatheredPeer, LocalPeerAnnouncement, PeerGatherOptions, PresenceReason } from '../types.js';
-import type { GroupBroadcastMessage } from './broadcast.js';
-import type { PeerQueryParam } from './group-protocols.js';
+import type { GroupBroadcastMessage } from './broadcast-message.js';
+import type { PeerCapability, PeerQueryParam } from './group-protocols.js';
 /** One `peer/query` reply as the gather surface hands it back. */
 type RawReply = {
     senderDID: string;
@@ -28,6 +28,13 @@ export type PeerPresenceParams = {
     applyAnnouncement: (groupID: string, message: GroupBroadcastMessage) => Promise<void>;
     /** Every group this device currently belongs to, for a device-wide announce. */
     joinedGroupIDs: () => Array<string>;
+    /**
+     * Capabilities the DEVICE answers on regardless of the host-declared profile,
+     * merged into every announce. Read at announce time, so a store registered
+     * after the profile was set still surfaces (e.g. `credential-sync` once a
+     * credential store exists). Empty by default.
+     */
+    deviceCapabilities?: () => Array<PeerCapability>;
     /**
      * Called after this device declares (or redeclares) its profile — the moment
      * it becomes visible, and so the moment a co-member may start dialling it.

package/lib/groups/peer-presence.js

@@ -2,6 +2,13 @@ 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;
+/** Host capabilities plus any device ones whose protocol the host did not already declare. */ function mergeCapabilities(host, device) {
+    const declared = new Set(host.map((capability)=>capability.protocol));
+    return [
+        ...host,
+        ...device.filter((capability)=>!declared.has(capability.protocol))
+    ];
+}
 /**
  * Pull an announcement out of an untyped gather reply. The gather surface hands
  * back `unknown`, so a version-skewed or malicious responder must contribute
@@ -83,6 +90,11 @@ export function createPeerPresence(params) {
         // 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());
+        // Merged at announce time, so a device capability the host never declared
+        // (and one that only became true after `setProfile`) still rides every frame
+        // and is read back by the `peer/query` reply below. Dedup by protocol keeps a
+        // host-declared entry authoritative.
+        const capabilities = mergeCapabilities(profile.capabilities, params.deviceCapabilities?.() ?? []);
         // 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
@@ -93,7 +105,7 @@ export function createPeerPresence(params) {
             peerDID: selfDID,
             label: profile.label,
             availability: profile.availability,
-            capabilities: profile.capabilities,
+            capabilities,
             hlc: announcedHLC,
             epoch: params.getGroupEpoch(groupID) ?? 0
         });
@@ -101,7 +113,7 @@ export function createPeerPresence(params) {
             type: 'peer:announce',
             label: profile.label,
             availability: profile.availability,
-            capabilities: profile.capabilities,
+            capabilities,
             hlc: announcedHLC,
             announcerDID: selfDID
         });

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

@@ -5,6 +5,15 @@ import type { PeerAnnouncement } from '@kubun/store-p2p';
  */
 export declare const MERKLE_SYNC_PROTOCOL = "kubun/sync-merkle";
 export declare const MERKLE_SYNC_VERSION = 1;
+/**
+ * "I serve credential catch-up" — advertised by a device that registered a
+ * credential store, so a co-member knows to reconcile credentials over the same
+ * tunnel after a doc catch-up. Absent it, the credential lane is skipped: a
+ * device without a credential store opts out by construction.
+ */
+export declare const CREDENTIAL_SYNC_PROTOCOL = "credential-sync";
+export declare const CREDENTIAL_SYNC_VERSION = 1;
+export declare function answersCredentialSync(row: Pick<PeerAnnouncement, 'capabilities'>): boolean;
 export type SelectSyncPeerOptions = {
     /**
      * This device's own DID. Required, because the projection holds this device's