@kubun/plugin-p2p 0.12.0 → 0.13.0

package/lib/groups/peer-selection.js

@@ -4,6 +4,16 @@ import { normalizeDID } from '@kokuin/token';
  * 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;
+/**
+ * "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 const CREDENTIAL_SYNC_PROTOCOL = 'credential-sync';
+export const CREDENTIAL_SYNC_VERSION = 1;
+export function answersCredentialSync(row) {
+    return row.capabilities.some((capability)=>capability.protocol === CREDENTIAL_SYNC_PROTOCOL && capability.version === CREDENTIAL_SYNC_VERSION);
+}
 /**
  * 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

package/lib/hub/wiring.d.ts

@@ -6,7 +6,7 @@ import type { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
 import type { LaneResult, PendingCommit } from '@kumiai/rpc';
 import type { Runtime } from '@sozai/runtime';
-import type { GroupBroadcastMessage } from '../groups/broadcast.js';
+import type { GroupBroadcastMessage } from '../groups/broadcast-message.js';
 import type { P2PEventEmitter } from '../groups/events.js';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
 import type { BuildLedgerRedrive } from '../groups/group-peer-manager.js';
@@ -108,6 +108,11 @@ export type SetupHubRelayParams = {
      * engine's single instance so roster writes share the device's one clock.
      */
     hlc: HLC;
+    /**
+     * The engine's future-drift bound, forwarded to the apply path so a peer's
+     * stamp is bounded there the same way the graph lane bounds a mutation's.
+     */
+    maxDriftMS: number;
     /**
      * Reconnect-backoff overrides forwarded to every hub adapter. Test-only; when
      * omitted the adapter runs on its production defaults.

package/lib/hub/wiring.js

@@ -10,7 +10,7 @@ import { HubTunnelSyncProvider } from '../sync/hub-tunnel-sync-provider.js';
  * once per candidate before reporting `no-route`.
  */ const DEFAULT_TUNNEL_IDLE_TIMEOUT_MS = 30_000;
 export function setupHubRelay(params) {
-    const { identity, runtime, db, graph, emitter, createHubClient, registry, buildLedgerRedrive, logger, storeUnreadable, defaultAccessLevel, forwarding, hlc, hubReconnectBackoff, tunnelIdleTimeoutMs } = params;
+    const { identity, runtime, db, graph, emitter, createHubClient, registry, buildLedgerRedrive, logger, storeUnreadable, defaultAccessLevel, forwarding, hlc, maxDriftMS, hubReconnectBackoff, tunnelIdleTimeoutMs } = params;
     const unsubscribes = [];
     // Late-bound `ready` resolving to the live manager. The fire-and-forget
     // schedulers chain off it so a caller can enqueue work before boot completes;
@@ -81,6 +81,7 @@ export function setupHubRelay(params) {
             graphStore,
             graph,
             hlc,
+            maxDriftMS,
             localDID: identity.id,
             identity,
             emitter,

package/lib/index.d.ts

@@ -7,8 +7,12 @@ import type { StoreUnreadableMode } from './types.js';
 export { GROUP_CONTROL_DENIED, LAST_GROUP_ADMIN, NOT_GROUP_ADMIN, type RequireGroupAdminParams, requireGroupAdmin, } from './context/require-admin.js';
 export type { ContextDeps } from './context/types.js';
 export { ADMIN_ROLE_ENTRY_TYPE, type AdminRoleValue, type AdminRosterState, foldAdminRoster, } from './groups/admin-roster.js';
-export { type AffectedRow, type GroupBroadcastMessage, type MutationApplyEntry, type ProcessBroadcastParams, type ProcessBroadcastResult, processBroadcast, } from './groups/broadcast.js';
+export { type AffectedRow, type ProcessBroadcastParams, type ProcessBroadcastResult, processBroadcast, } from './groups/broadcast.js';
 export { deserializeBroadcast, serializeBroadcast } from './groups/broadcast-codec.js';
+export type { CredentialKeyBundle, CredentialKeyGrantEntry, CredentialKeyGrantWrapping, GroupBroadcastMessage, MutationApplyEntry, } from './groups/broadcast-message.js';
+export { type ApplyCredentialKeyGrantFrameParams, type ApplyCredentialReconcileParams, type ApplyCredentialReconcileResult, applyCredentialKeyGrantFrame, applyCredentialReconcile, type CredentialReconcileTombstone, } from './groups/credential-apply.js';
+export { CredentialGrantNotReadable, CredentialRecipientNotInGroup, type GrantCredentialKeyParams, type GrantCredentialKeyResult, grantCredentialKeyToMember, } from './groups/credential-grant.js';
+export { type CredentialKeyGrantClaim, credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappingDigest, signCredentialKeyGrant, type VerifiedCredentialKeyGrant, verifyCredentialKeyGrant, } from './groups/credential-grant-token.js';
 export { createFilteredGenerator, createP2PEventEmitter, type P2PEventEmitter, type P2PEventMap, } from './groups/events.js';
 export { buildKubunGroupAnchorExtension, type GroupAnchorApp, readRecoverySecret, } from './groups/group-anchor.js';
 export { GroupHandleRegistry, type GroupHandleRegistryParams, type SeedParams, } from './groups/group-handle-registry.js';

package/lib/index.js

@@ -2,6 +2,7 @@ import { ServerTransport } from '@enkaku/http-serve';
 import { Server } from '@enkaku/server';
 import { DirectTransports } from '@enkaku/transport';
 import { isFullIdentity } from '@kokuin/token';
+import { createDeviceAuthority } from '@kubun/credential';
 import { resolveAllowedOrigin } from '@kubun/http-util';
 import { getGraphStore } from '@kubun/store-graph';
 import { p2pStoreDefinition } from '@kubun/store-p2p';
@@ -17,7 +18,11 @@ import { GroupHealthMonitor } from './groups/group-health-monitor.js';
 import { GroupManager } from './groups/manager.js';
 import { createHTTPHubClient } from './hub/http-client.js';
 import { setupHubRelay } from './hub/wiring.js';
+import { fetchAttachment } from './peer/blob-fetch.js';
+import { createBlobHandlers } from './peer/blob-handlers.js';
 import { PeerConnectionRegistry } from './peer/connection-registry.js';
+import { fetchControllerLog } from './peer/controller-fetch.js';
+import { createControllerHandlers } from './peer/controller-handlers.js';
 import { createPeerHandlers } from './peer/handlers.js';
 import { createP2PSchemaExtension } from './schema.js';
 import { wireAccessDefaultSender } from './sync/access-default-sender.js';
@@ -29,6 +34,9 @@ export { GROUP_CONTROL_DENIED, LAST_GROUP_ADMIN, NOT_GROUP_ADMIN, requireGroupAd
 export { ADMIN_ROLE_ENTRY_TYPE, foldAdminRoster } from './groups/admin-roster.js';
 export { processBroadcast } from './groups/broadcast.js';
 export { deserializeBroadcast, serializeBroadcast } from './groups/broadcast-codec.js';
+export { applyCredentialKeyGrantFrame, applyCredentialReconcile } from './groups/credential-apply.js';
+export { CredentialGrantNotReadable, CredentialRecipientNotInGroup, grantCredentialKeyToMember } from './groups/credential-grant.js';
+export { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappingDigest, signCredentialKeyGrant, verifyCredentialKeyGrant } from './groups/credential-grant-token.js';
 export { createFilteredGenerator, createP2PEventEmitter } from './groups/events.js';
 export { buildKubunGroupAnchorExtension, readRecoverySecret } from './groups/group-anchor.js';
 export { GroupHandleRegistry } from './groups/group-handle-registry.js';
@@ -114,6 +122,7 @@ export function createP2PPlugin(options) {
             runtime: params.runtime,
             registry,
             hlc,
+            maxDriftMS: params.maxDriftMS,
             stores: params.db,
             emitter,
             logger: params.getLogger('group-manager')
@@ -218,6 +227,7 @@ export function createP2PPlugin(options) {
             runtime: params.runtime,
             db: params.db,
             hlc,
+            maxDriftMS: params.maxDriftMS,
             graph: params.graph,
             emitter,
             createHubClient,
@@ -318,6 +328,7 @@ export function createP2PPlugin(options) {
                 deviceStores: params.db,
                 adapter,
                 hlc,
+                maxDriftMS: params.maxDriftMS,
                 emitter,
                 runtime: params.runtime,
                 autoAcceptPeers: options?.autoAcceptPeers,
@@ -342,11 +353,15 @@ export function createP2PPlugin(options) {
             identity,
             logger: params.getLogger('peer-handlers'),
             autoAcceptPeers: options?.autoAcceptPeers,
-            runPrepareJoin: (callerDID)=>createJoinContext({
-                    viewerDID: callerDID
+            runPrepareJoin: (callerDID)=>createJoinContext(// Out-of-band peer-handler context for the verified caller; the join ops
+                // never consult the authority, so a self-scoped device authority fits.
+                {
+                    viewerDID: callerDID,
+                    credentialAuthority: createDeviceAuthority(callerDID)
                 }, buildContextDeps(params.db)).prepareRequest(),
             runCompleteJoin: (callerDID, invitePayload)=>createJoinContext({
-                    viewerDID: callerDID
+                    viewerDID: callerDID,
+                    credentialAuthority: createDeviceAuthority(callerDID)
                 }, buildContextDeps(params.db)).complete(invitePayload),
             runInvite: (callerDID, groupID, joinRequest)=>serveGroupInvite(buildContextDeps(params.db), {
                     callerDID,
@@ -358,6 +373,23 @@ export function createP2PPlugin(options) {
                     ...param
                 })
         });
+        // Blob transfer control-lane handlers, mounted on the same peer server.
+        const blobHandlers = createBlobHandlers({
+            db: params.db,
+            identity,
+            logger: params.getLogger('blob-handlers'),
+            autoAcceptPeers: options?.autoAcceptPeers,
+            getRandomID: ()=>params.runtime.getRandomID()
+        });
+        // Controller log-sharing handlers, mounted on the same peer server. Serves a
+        // did:kokuin: controller's stored log to a peer we share a group with; the
+        // recipient folds + verifies it independently.
+        const controllerHandlers = createControllerHandlers({
+            db: params.db,
+            identity,
+            logger: params.getLogger('controller-handlers'),
+            autoAcceptPeers: options?.autoAcceptPeers
+        });
         const pluginAPI = {
             hubReady: hub.ready,
             addPeer: (config)=>syncManager.addPeer({
@@ -395,7 +427,15 @@ export function createP2PPlugin(options) {
             gatherPeers: async (groupID, options)=>await (await hub.presence()).gather(groupID, options),
             refreshPeerPresence: async (groupID, options)=>await (await hub.presence()).refresh(groupID, options),
             retryHubConnection: async ()=>await hub.retryHubs(),
-            getPeerConnection: (peerDID)=>peerConnections.get(peerDID)
+            getPeerConnection: (peerDID)=>peerConnections.get(peerDID),
+            fetchAttachment: (attachmentID, options)=>fetchAttachment({
+                    peerConnections,
+                    getBlobAPI: ()=>params.engine.getAPI('blob'),
+                    fetch: params.runtime.fetch
+                }, attachmentID, options),
+            fetchControllerLog: (did)=>fetchControllerLog({
+                    peerConnections
+                }, did)
         };
         let httpSyncTransport;
         let httpSyncServer;
@@ -453,17 +493,29 @@ export function createP2PPlugin(options) {
                 });
                 httpPeerServer = new Server({
                     runtime: params.runtime,
-                    handlers: peerHandlers,
+                    handlers: {
+                        ...peerHandlers,
+                        ...blobHandlers,
+                        ...controllerHandlers
+                    },
                     identity,
                     // Open at the procedure layer, like the sync server: each peer handler
                     // gates the verified caller itself (forged-`sub` rejection +
-                    // `checkPeerAccess`). Covers `peer/*` and the dance `group/*`.
+                    // `checkPeerAccess`). Covers `peer/*`, the dance `group/*`, the blob
+                    // control lane (`blob/*`, which additionally scope-authorizes), and
+                    // the controller log-sharing lane (`controller/*`).
                     accessRules: {
                         'peer/*': {
                             allow: true
                         },
                         'group/*': {
                             allow: true
+                        },
+                        'blob/*': {
+                            allow: true
+                        },
+                        'controller/*': {
+                            allow: true
                         }
                     },
                     logger: params.getLogger('peer-http-server'),

package/lib/peer/blob-fetch.d.ts

@@ -0,0 +1,45 @@
+import type { Fetch } from '@sozai/runtime';
+import type { BlobManifestResult } from '../protocol.js';
+import type { PeerConnection, PeerConnectionRegistry } from './connection-registry.js';
+export type BlobFetchAPI = {
+    getAttachment(attachmentID: string): Promise<{
+        state: string;
+    } | null>;
+    beginFetch(params: {
+        attachmentID: string;
+        chunkSize: number;
+        chunkDigests: Array<Uint8Array>;
+    }): Promise<void>;
+    getPresentChunks(attachmentID: string): Promise<Array<number>>;
+    stageChunk(params: {
+        attachmentID: string;
+        index: number;
+        offset: number;
+        bytes: Uint8Array;
+    }): Promise<void>;
+    completeFetch(attachmentID: string): Promise<void>;
+};
+export type PeerConnectionLister = {
+    list(): Array<PeerConnection>;
+};
+export type FetchAttachmentDeps = {
+    peerConnections: PeerConnectionRegistry;
+    getBlobAPI: () => Promise<BlobFetchAPI>;
+    fetch: Fetch;
+};
+export type FetchAttachmentOptions = {
+    delegationTokens?: Array<string>;
+};
+export declare function discoverHolder(peerConnections: PeerConnectionLister, attachmentID: string): Promise<PeerConnection | null>;
+export declare function requestManifest(holder: PeerConnection, attachmentID: string, delegationTokens: Array<string>): Promise<BlobManifestResult>;
+export declare function fetchChunkBytes(params: {
+    holder: PeerConnection;
+    attachmentID: string;
+    manifest: Pick<BlobManifestResult, 'chunkSize' | 'contentLength' | 'capability'>;
+    index: number;
+    fetch: Fetch;
+}): Promise<{
+    offset: number;
+    bytes: Uint8Array;
+}>;
+export declare function fetchAttachment(deps: FetchAttachmentDeps, attachmentID: string, options?: FetchAttachmentOptions): Promise<void>;

package/lib/peer/blob-fetch.js

@@ -0,0 +1,89 @@
+import { BLOB_BYTE_ROUTE_PREFIX } from '@kubun/store-blob';
+import { fromB64 } from '@sozai/codec';
+// Ask each live peer whether it holds the blob; the first that does is the
+// holder. Null when none of the connected peers has the bytes.
+export async function discoverHolder(peerConnections, attachmentID) {
+    for (const connection of peerConnections.list()){
+        const haves = await connection.client.request('blob/query-haves', {
+            param: {
+                attachmentIDs: [
+                    attachmentID
+                ]
+            }
+        });
+        if (haves.have.includes(attachmentID)) return connection;
+    }
+    return null;
+}
+// Fetch the holder's manifest + a signed, short-TTL read capability for this
+// blob over the Enkaku control plane.
+export function requestManifest(holder, attachmentID, delegationTokens) {
+    return holder.client.request('blob/manifest', {
+        param: {
+            attachmentID,
+            delegationTokens
+        }
+    });
+}
+// Range-GET a single chunk's bytes from the holder's raw-HTTP data plane.
+// Returns the byte offset (so the caller can stage at the right position) and
+// the bytes. Throws on a non-OK response — a per-chunk failure the caller
+// surfaces.
+export async function fetchChunkBytes(params) {
+    const { holder, attachmentID, manifest, index } = params;
+    const start = index * manifest.chunkSize;
+    const end = Math.min(start + manifest.chunkSize, manifest.contentLength) - 1;
+    const byteURL = new URL(`${BLOB_BYTE_ROUTE_PREFIX}/${attachmentID}`, holder.endpoint).toString();
+    const response = await params.fetch(byteURL, {
+        headers: {
+            Authorization: `Bearer ${manifest.capability}`,
+            Range: `bytes=${start}-${end}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(`Blob range fetch failed for chunk ${index}: HTTP ${response.status}`);
+    }
+    return {
+        offset: start,
+        bytes: new Uint8Array(await response.arrayBuffer())
+    };
+}
+// Pull a remote blob's bytes from a connected peer that holds them: discover a
+// holder, fetch its manifest + a signed capability, range-download every missing
+// chunk over the raw-HTTP data plane, and persist through plugin-blob (which
+// verifies each chunk and the whole blob). A no-op if the bytes are already
+// local; resumable — only missing chunks are re-requested.
+export async function fetchAttachment(deps, attachmentID, options) {
+    const blob = await deps.getBlobAPI();
+    const existing = await blob.getAttachment(attachmentID);
+    if (existing?.state === 'local') return;
+    const delegationTokens = options?.delegationTokens ?? [];
+    const holder = await discoverHolder(deps.peerConnections, attachmentID);
+    if (holder == null) {
+        throw new Error(`No connected peer holds blob ${attachmentID}`);
+    }
+    const manifest = await requestManifest(holder, attachmentID, delegationTokens);
+    await blob.beginFetch({
+        attachmentID,
+        chunkSize: manifest.chunkSize,
+        chunkDigests: manifest.chunkDigests.map((digest)=>fromB64(digest))
+    });
+    const present = new Set(await blob.getPresentChunks(attachmentID));
+    for(let index = 0; index < manifest.chunkCount; index++){
+        if (present.has(index)) continue;
+        const { offset, bytes } = await fetchChunkBytes({
+            holder,
+            attachmentID,
+            manifest,
+            index,
+            fetch: deps.fetch
+        });
+        await blob.stageChunk({
+            attachmentID,
+            index,
+            offset,
+            bytes
+        });
+    }
+    await blob.completeFetch(attachmentID);
+}

package/lib/peer/blob-handlers.d.ts

@@ -0,0 +1,11 @@
+import type { OwnIdentity } from '@kokuin/token';
+import type { KubunDB } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+export type CreateBlobHandlersParams = {
+    db: KubunDB;
+    identity: OwnIdentity;
+    logger: Logger;
+    autoAcceptPeers?: Array<string>;
+    getRandomID: () => string;
+};
+export declare function createBlobHandlers(params: CreateBlobHandlersParams): Record<string, unknown>;

package/lib/peer/blob-handlers.js

@@ -0,0 +1,123 @@
+import { createCapability } from '@kokuin/capability';
+import { stringifyToken } from '@kokuin/token';
+import { getBlobStore } from '@kubun/store-blob';
+import { createDelegationRevocationChecker, getDelegationStore } from '@kubun/store-delegation';
+import { getGraphStore } from '@kubun/store-graph';
+import { getP2PStore } from '@kubun/store-p2p';
+import { toB64 } from '@sozai/codec';
+import { checkPeerAccess, verifiedCaller } from '../context/types.js';
+import { authorizeScope } from '../sync/authorize.js';
+import { wrapHandlers } from '../util/handler-error.js';
+// A fetch capability only has to survive one download's handshake + transfer.
+// Short-lived so a leaked token is quickly useless; the byte route re-checks it.
+const FETCH_CAP_TTL_SECONDS = 300;
+export function createBlobHandlers(params) {
+    const { db, identity, logger, autoAcceptPeers, getRandomID } = params;
+    // Same scope resolvers the sync lane uses, so a blob authorizes against
+    // identical (owner, model, circle) scope as the documents that reference it.
+    let cachedRevocationChecker = null;
+    async function getRevocationChecker() {
+        if (cachedRevocationChecker == null) {
+            cachedRevocationChecker = createDelegationRevocationChecker(await getDelegationStore(db));
+        }
+        return cachedRevocationChecker;
+    }
+    let cachedCircleReadGrant = null;
+    async function getCircleReadGrant() {
+        if (cachedCircleReadGrant == null) {
+            const [graphStore, p2pStore] = await Promise.all([
+                getGraphStore(db),
+                getP2PStore(db)
+            ]);
+            cachedCircleReadGrant = {
+                getUserModelReadDefault: (ownerDID, modelID)=>graphStore.getUserModelAccessDefault(ownerDID, modelID, 'read'),
+                listAccessibleCircles: (viewerDID, circleIDs)=>p2pStore.listAccessibleCircles(viewerDID, circleIDs),
+                listMemberGroupIDs: (viewerDID, groupIDs)=>p2pStore.listMemberGroupIDs(viewerDID, groupIDs)
+            };
+        }
+        return cachedCircleReadGrant;
+    }
+    // D19: a blob is in a peer's scope iff some document that references it is.
+    // Authorize against the referencing documents' (owner, model) scopes; any one
+    // in scope grants the fetch.
+    async function authorizeBlobFetch(viewerDID, attachmentID, delegationTokens) {
+        const [blobStore, graphStore] = await Promise.all([
+            getBlobStore(db),
+            getGraphStore(db)
+        ]);
+        const refs = await blobStore.getRefsForAttachment(attachmentID);
+        if (refs.length === 0) return false;
+        const revocationChecker = await getRevocationChecker();
+        const circleReadGrant = await getCircleReadGrant();
+        for (const ref of refs){
+            const document = await graphStore.getDocument(ref.document_id);
+            if (document == null) continue;
+            const ok = await authorizeScope({
+                viewerDID,
+                ownerDID: document.owner,
+                modelID: ref.model_id,
+                delegationTokens,
+                revocationChecker,
+                circleReadGrant
+            });
+            if (ok) return true;
+        }
+        return false;
+    }
+    return wrapHandlers({
+        'blob/query-haves': async (ctx)=>{
+            const callerDID = verifiedCaller(ctx.message.payload);
+            checkPeerAccess(callerDID, identity.id, autoAcceptPeers);
+            const store = await getBlobStore(db);
+            const have = [];
+            for (const attachmentID of ctx.param.attachmentIDs){
+                const entry = await store.getEntry(attachmentID);
+                if (entry != null && entry.state === 'local') have.push(attachmentID);
+            }
+            logger.debug('blob/query-haves served', {
+                callerDID,
+                have: have.length
+            });
+            return {
+                have
+            };
+        },
+        'blob/manifest': async (ctx)=>{
+            const callerDID = verifiedCaller(ctx.message.payload);
+            checkPeerAccess(callerDID, identity.id, autoAcceptPeers);
+            const { attachmentID, delegationTokens } = ctx.param;
+            const store = await getBlobStore(db);
+            const entry = await store.getEntry(attachmentID);
+            if (entry == null || entry.state !== 'local') {
+                throw new Error(`Blob ${attachmentID} not held locally`);
+            }
+            const authorized = await authorizeBlobFetch(callerDID, attachmentID, delegationTokens);
+            if (!authorized) {
+                throw new Error(`Blob ${attachmentID} not in caller scope`);
+            }
+            const digests = await store.getChunkDigests(attachmentID);
+            const iat = Math.floor(Date.now() / 1000);
+            const capability = await createCapability(identity, {
+                sub: identity.id,
+                aud: callerDID,
+                act: 'blob/read',
+                res: `urn:kubun:blob:${attachmentID}`,
+                iat,
+                exp: iat + FETCH_CAP_TTL_SECONDS,
+                jti: getRandomID()
+            });
+            logger.debug('blob/manifest served', {
+                callerDID,
+                attachmentID,
+                chunks: digests.length
+            });
+            return {
+                chunkSize: entry.chunk_size,
+                chunkCount: digests.length,
+                contentLength: entry.content_length,
+                chunkDigests: digests.map((digest)=>toB64(digest)),
+                capability: stringifyToken(capability)
+            };
+        }
+    });
+}

package/lib/peer/controller-fetch.d.ts

@@ -0,0 +1,6 @@
+import { type SignedEvent } from '@kokuin/controller';
+import type { PeerConnectionLister } from './blob-fetch.js';
+export type ControllerLogFetchDeps = {
+    peerConnections: PeerConnectionLister;
+};
+export declare function fetchControllerLog(deps: ControllerLogFetchDeps, did: string): Promise<Array<SignedEvent> | undefined>;

package/lib/peer/controller-fetch.js

@@ -0,0 +1,59 @@
+import { LOG_FORKED, resolveBranchesAsync } from '@kokuin/controller';
+// Reduce the logs gathered from peers to the single authoritative one, reusing
+// kokuin's own arbitration (never reimplementing the fold). Trusting the first
+// non-empty answer would let a stale/hostile peer that responds first suppress a
+// revocation another peer already holds — the resolver never sees the competing
+// branch, so its `history` guard cannot catch it. Arbitrating every candidate
+// closes that: the branch carrying the latest `rev` (or a superseding recovery)
+// wins here before the caller ever compares against its cache.
+//
+// `resolveBranchesAsync` resolves all candidates AT ONCE and is the primitive
+// built for this. A sequential pairwise reduction would be order-dependent: it
+// can report duplicity between two losing branches before reaching the one that
+// supersedes both — e.g. a recovery rotate presented after two conflicting
+// revokes — which kokuin's `resolveContenders` documents as unsound. It also
+// folds each branch itself and drops the unfoldable, so a garbage answer is
+// ignored rather than poisoning the result.
+async function selectAuthoritativeLog(did, candidates) {
+    if (candidates.length === 0) return undefined;
+    const resolved = await resolveBranchesAsync(did, candidates, {});
+    if (resolved.ok) {
+        // A branch left out for want of a capability verifier (the engine configures
+        // none) means the winner among the rest may not be the true authority; be
+        // conservative and decline so the caller keeps its cached log.
+        return resolved.unverified > 0 ? undefined : resolved.winner;
+    }
+    // A genuine fork must surface — the caller's resolver re-throws it and emits
+    // `engine:controller:forked`. Any other failure (no valid branch, all
+    // unverifiable) leaves nothing to hand back.
+    if (resolved.failure === 'duplicity') throw new Error(`${LOG_FORKED}: ${did}`);
+    return undefined;
+}
+// Pull a `did:kokuin:` controller's key-event log from connected group peers.
+// Every reachable peer is asked (not just the first responder), and a peer that
+// errors or denies us is skipped rather than aborting the sweep — so one
+// hostile/offline peer can neither suppress a revocation another peer holds nor
+// deny controller verification entirely. The gathered logs are arbitrated by
+// `selectAuthoritativeLog`; a genuine fork among them throws `LOG_FORKED` for
+// the caller's resolver to surface. No connected peer holds it -> undefined.
+//
+// The events are self-authenticating (inception digest == DID, every event
+// signed), so nothing here trusts a peer's answer for integrity: the arbitration
+// folds every candidate, and the caller's resolver folds the winner again
+// against its own history.
+export async function fetchControllerLog(deps, did) {
+    const candidates = [];
+    for (const connection of deps.peerConnections.list()){
+        try {
+            const { events } = await connection.client.request('controller/get-log', {
+                param: {
+                    did
+                }
+            });
+            if (events.length > 0) candidates.push(events);
+        } catch  {
+        // Skip an erroring/denying peer; the remaining peers still answer.
+        }
+    }
+    return selectAuthoritativeLog(did, candidates);
+}

package/lib/peer/controller-handlers.d.ts

@@ -0,0 +1,10 @@
+import type { OwnIdentity } from '@kokuin/token';
+import type { KubunDB } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+export type CreateControllerHandlersParams = {
+    db: KubunDB;
+    identity: OwnIdentity;
+    logger: Logger;
+    autoAcceptPeers?: Array<string>;
+};
+export declare function createControllerHandlers(params: CreateControllerHandlersParams): Record<string, unknown>;

package/lib/peer/controller-handlers.js

@@ -0,0 +1,28 @@
+import { getControllerStore } from '@kubun/store-controller';
+import { checkPeerAccess, verifiedCaller } from '../context/types.js';
+import { wrapHandlers } from '../util/handler-error.js';
+export function createControllerHandlers(params) {
+    const { db, identity, logger, autoAcceptPeers } = params;
+    return wrapHandlers({
+        'controller/get-log': async (ctx)=>{
+            const callerDID = verifiedCaller(ctx.message.payload);
+            checkPeerAccess(callerDID, identity.id, autoAcceptPeers);
+            const store = await getControllerStore(db);
+            // A miss is an empty log, not a throw: the log is self-authenticating, so
+            // there is nothing to refuse, and the requester decides what an empty
+            // answer means (whether to retry another peer).
+            const events = await store.get(ctx.param.did) ?? [];
+            logger.debug('controller/get-log served', {
+                callerDID,
+                did: ctx.param.did,
+                events: events.length
+            });
+            // The stored log is Array<SignedEvent>; the wire schema types it as an
+            // opaque object array and the recipient re-verifies, so the shape is safe
+            // to hand back as-is.
+            return {
+                events: events
+            };
+        }
+    });
+}