@kubun/plugin-p2p 0.14.0 → 0.15.1

package/lib/index.js

@@ -1,7 +1,7 @@
 import { ServerTransport } from '@enkaku/http-serve';
 import { Server } from '@enkaku/server';
 import { DirectTransports } from '@enkaku/transport';
-import { isFullIdentity } from '@kokuin/token';
+import { createInMemoryDIDCache, isFullIdentity } from '@kokuin/token';
 import { createDeviceAuthority } from '@kubun/credential';
 import { resolveAllowedOrigin } from '@kubun/http-util';
 import { getGraphStore } from '@kubun/store-graph';
@@ -30,6 +30,7 @@ import { createBroadcastQueue, DEFAULT_BROADCAST_BATCH_CONFIG } from './sync/bro
 import { DEFAULT_PUSH_SYNC_CONFIG, wireBroadcastSender } from './sync/broadcast-sender.js';
 import { createGroupSyncWorkflow, GROUP_SYNC_CONCURRENCY, GROUP_SYNC_WORKFLOW, wireGroupPeriodicSyncArming } from './sync/group-sync-workflow.js';
 import { createSyncHandlers } from './sync/handlers.js';
+import { ServiceServeNotReadyError, ServiceServeUnavailableError } from './sync/hub-tunnel-service-listener.js';
 import { SyncManager } from './sync/sync-manager.js';
 export { GROUP_CONTROL_DENIED, LAST_GROUP_ADMIN, NOT_GROUP_ADMIN, requireGroupAdmin } from './context/require-admin.js';
 export { ADMIN_ROLE_ENTRY_TYPE, foldAdminRoster } from './groups/admin-roster.js';
@@ -198,6 +199,13 @@ export function createP2PPlugin(options) {
         const peerConnections = new PeerConnectionRegistry({
             logger: params.getLogger('peer-connections')
         });
+        // One plugin-lifetime DID cache, shared by every peer-lane Server. The
+        // tunnel listeners seed it from each group's MLS roster (a co-member's
+        // authenticated leaf long form), so a freshly-spawned per-session Server
+        // resolves a co-member's short-form `did:peer:4` issuer instead of defaulting
+        // its own empty cache. Content-addressed and monotonic — a stale entry is
+        // harmless, and it survives no process restart by design (re-seeded on bind).
+        const didCache = createInMemoryDIDCache();
         // The p2p plugin manages its own Enkaku server for sync handlers,
         // separate from the graph service's server.
         const syncServers = [];
@@ -221,6 +229,7 @@ export function createP2PPlugin(options) {
                 transports: [
                     directTransports.server
                 ],
+                cache: didCache,
                 signal
             });
             syncServers.push(server);
@@ -243,6 +252,47 @@ export function createP2PPlugin(options) {
             fetch: params.runtime.fetch
         });
         const hubReconnectBackoff = typeof options?.hub === 'object' ? options.hub.reconnectBackoff : undefined;
+        // Which services (if any) this device answers on an inbound service-lane
+        // tunnel session; `undefined` means the service lane is not configured.
+        const serviceConfig = options?.serviceTunnel == null || options.serviceTunnel === false ? undefined : options.serviceTunnel === true ? {
+            'controller-log': true
+        } : options.serviceTunnel.services ?? {
+            'controller-log': true
+        };
+        // `getAPI` only resolves once every plugin factory has returned (see
+        // `Registry.closeGate` in `@kubun/engine`), so it can't be awaited here.
+        // `resolvedServe` fills in later, before any service session actually
+        // spawns (spawning waits on `setupHubRelay`'s internal `ready`, which
+        // resolves after every factory returns) — `serviceServe` below is thus a
+        // synchronous `ServeService` even though its target resolves lazily.
+        let resolvedServe;
+        // A permanent resolution failure (service-server not installed) must not
+        // read as transient "not ready" — that would retry a plugin that will
+        // never arrive. Track it so the wrapper throws the terminal error instead.
+        let serveResolutionFailed = false;
+        if (serviceConfig != null) {
+            void params.engine.getAPI('service-server').then((api)=>{
+                resolvedServe = api.serve;
+            }).catch((error)=>{
+                serveResolutionFailed = true;
+                hubRelayLogger.error('serviceTunnel is enabled but the "service-server" plugin API could not be resolved; the service lane will not serve', {
+                    error
+                });
+            });
+        }
+        const serviceServe = serviceConfig == null ? undefined : (serveParams)=>{
+            if (resolvedServe != null) {
+                return resolvedServe(serveParams);
+            }
+            // Terminal: the plugin API rejected and will not resolve. Stops the
+            // listener rather than letting it retry a plugin that never arrives.
+            if (serveResolutionFailed) {
+                throw new ServiceServeUnavailableError('serviceTunnel is enabled but the "service-server" plugin API could not be resolved');
+            }
+            // Transient: the API is still resolving (an early-spawn race). The
+            // listener retries on backoff and the next spawn finds it.
+            throw new ServiceServeNotReadyError('serviceTunnel is enabled but the "service-server" plugin API is not ready yet');
+        };
         const hub = setupHubRelay({
             identity,
             runtime: params.runtime,
@@ -264,6 +314,10 @@ export function createP2PPlugin(options) {
             storeUnreadable: receiveConfig.storeUnreadable,
             defaultAccessLevel,
             forwarding: options?.forwarding,
+            // The engine's controller-resolver seam, so a delegate-signed
+            // `credential:key-grant` wrapping received over the live broadcast lane can
+            // be authorized against the grantor's administer chain.
+            controllerResolverFor: params.controllerResolverFor,
             ...hubReconnectBackoff != null ? {
                 hubReconnectBackoff
             } : {},
@@ -272,7 +326,15 @@ export function createP2PPlugin(options) {
             } : {},
             // The same handlers the direct and HTTP transports serve — a tunnel is a
             // route, so it must not reach a different sync implementation.
-            syncHandlers: syncHandlers
+            syncHandlers: syncHandlers,
+            // The service lane's answering half; absent, `setupHubRelay` stands up
+            // no service listeners, so a device without `serviceTunnel` is unchanged.
+            ...serviceServe != null ? {
+                serviceServe,
+                services: serviceConfig
+            } : {},
+            // The shared roster-seeded cache reaches the tunnel listeners here.
+            cache: didCache
         });
         // Turn a `tunnel://<groupID>/<peerDID>` route into a live session over the
         // group's hub. Until this existed the scheme parsed and then failed at
@@ -350,6 +412,9 @@ export function createP2PPlugin(options) {
                 adapter,
                 hlc,
                 maxDriftMS: params.maxDriftMS,
+                // The engine's controller-resolver seam, so the credential reconcile-apply
+                // lane (catch-up) can authorize a delegate-signed wrapping it pulls back.
+                controllerResolverFor: params.controllerResolverFor,
                 emitter,
                 runtime: params.runtime,
                 autoAcceptPeers: options?.autoAcceptPeers,
@@ -507,6 +572,7 @@ export function createP2PPlugin(options) {
             onHubServerDIDChanged: (listener)=>emitter.on('hubServerDIDChanged', listener),
             createSyncTransport,
             requestLedgerCatchup: (groupID, options)=>hub.requestLedgerCatchup(groupID, options),
+            serviceTransportTo: (groupID, peerDID)=>hub.serviceTransportTo(groupID, peerDID),
             setLocalPeerProfile: async (profile)=>{
                 await (await hub.presence()).setProfile(profile);
             },
@@ -573,7 +639,8 @@ export function createP2PPlugin(options) {
                     logger: params.getLogger('sync-http-server'),
                     transports: [
                         httpSyncTransport
-                    ]
+                    ],
+                    cache: didCache
                 });
                 syncServers.push(httpSyncServer);
                 httpAPI.registerProtocol(protocolName, httpSyncTransport.fetch.bind(httpSyncTransport));
@@ -616,7 +683,8 @@ export function createP2PPlugin(options) {
                     logger: params.getLogger('peer-http-server'),
                     transports: [
                         httpPeerTransport
-                    ]
+                    ],
+                    cache: didCache
                 });
                 httpAPI.registerProtocol('peer', httpPeerTransport.fetch.bind(httpPeerTransport));
             })();

package/lib/protocol.d.ts

@@ -229,6 +229,13 @@ export declare const syncProtocol: {
                     };
                     readonly description: "Signed subject states the caller holds, for updates and revocation GC";
                 };
+                readonly owners: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Owner DIDs to fetch the latest durable manifest for, addressed to the caller — the PULL repair channel independent of LIVE broadcast.";
+                };
             };
             readonly required: readonly ["held"];
             readonly additionalProperties: false;
@@ -327,6 +334,9 @@ export declare const syncProtocol: {
                                     readonly additionalProperties: false;
                                 };
                             };
+                            readonly grantorAuthority: {
+                                readonly type: "string";
+                            };
                         };
                         readonly required: readonly ["keyID", "keyVersion", "suite", "ownerDID", "keyOp", "keyBranches", "wrapping", "entries"];
                         readonly additionalProperties: false;
@@ -362,6 +372,26 @@ export declare const syncProtocol: {
                     };
                     readonly description: "Tombstones for advertised held IDs that are now revoked (GC)";
                 };
+                readonly manifests: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly manifest: {
+                                readonly type: "string";
+                            };
+                            readonly delegationTokens: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                        readonly required: readonly ["manifest", "delegationTokens"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly description: "The latest stored manifest addressed to the caller for each requested owner — the durable repair channel independent of LIVE broadcast.";
+                };
             };
             readonly required: readonly ["bundles", "tombstones"];
             readonly additionalProperties: false;

package/lib/protocol.js

@@ -290,6 +290,13 @@ export const syncProtocol = {
                         additionalProperties: false
                     },
                     description: 'Signed subject states the caller holds, for updates and revocation GC'
+                },
+                owners: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'Owner DIDs to fetch the latest durable manifest for, addressed to the caller — the PULL repair channel independent of LIVE broadcast.'
                 }
             },
             required: [
@@ -406,6 +413,12 @@ export const syncProtocol = {
                                     ],
                                     additionalProperties: false
                                 }
+                            },
+                            // Persisted grantor-authority envelope for a delegate-signed
+                            // wrapping (absent for owner-signed); declared so it isn't an
+                            // `additionalProperties: false` violation if result validation is enabled.
+                            grantorAuthority: {
+                                type: 'string'
                             }
                         },
                         required: [
@@ -457,6 +470,29 @@ export const syncProtocol = {
                         additionalProperties: false
                     },
                     description: 'Tombstones for advertised held IDs that are now revoked (GC)'
+                },
+                manifests: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            manifest: {
+                                type: 'string'
+                            },
+                            delegationTokens: {
+                                type: 'array',
+                                items: {
+                                    type: 'string'
+                                }
+                            }
+                        },
+                        required: [
+                            'manifest',
+                            'delegationTokens'
+                        ],
+                        additionalProperties: false
+                    },
+                    description: 'The latest stored manifest addressed to the caller for each requested owner — the durable repair channel independent of LIVE broadcast.'
                 }
             },
             required: [

package/lib/schema.js

@@ -581,6 +581,12 @@ extend type Query {
   one group. The store is per-device.
   """
   controlRequests(groupID: ID): [ControlRequest!]!
+  """
+  Prove this device holds the complete credential set the owner's manifests
+  promised it: the union of every per-grantor manifest's keys, minus those that
+  actually decrypt-verify here. An empty missing list means the pull is complete.
+  """
+  credentialProvisioningStatus(ownerDID: DID!): CredentialProvisioningStatus!
 }
 
 enum GroupHealthCondition {
@@ -644,6 +650,48 @@ type ControlRequest implements Node {
   settledAt: DateTimeISO
 }
 
+"""
+One key's outcome from a grantDeviceCredentials batch: what happened when this
+device tried to hand one of the owner's active credential keys to the recipient
+device. Never an error thrown out of the batch — every key reports its own fate.
+"""
+type CredentialGrantOutcome {
+  keyID: ID!
+  """
+  The key's version after this call, or null when nothing was granted
+  (not-held / error outcomes carry no version).
+  """
+  version: Int
+  outcome: String!
+  """Present on not-held and error; the caught error's message."""
+  reason: String
+}
+
+type GrantDeviceCredentialsPayload {
+  results: [CredentialGrantOutcome!]!
+  """A grantor-signed manifest claiming exactly the granted/refreshed keys above."""
+  manifest: String!
+  """The provisioning epoch this manifest was allocated under."""
+  epoch: Int!
+}
+
+"""
+Readiness of this device's credential provisioning for one owner. A key counts
+materialized only when its wrapping decrypt-verifies (or, for a zero-entry key,
+merely opens) — presence and a valid signature alone never suffice.
+"""
+type CredentialProvisioningStatus {
+  complete: Boolean!
+  """The expected keyIDs not yet materialized on this device."""
+  missing: [ID!]!
+  """
+  Why complete is false: not-initiated (no expectation on record yet),
+  pending (an attempt is in flight, its floor not yet bound), or incomplete
+  (asked for, not yet fully materialized/proven). Absent when complete.
+  """
+  reason: String
+}
+
 extend type Mutation {
   connectPeer(url: String!): ConnectPeerPayload!
   sharePeerGroup(peerDID: ID!, groupID: ID, name: String, send: ShareInput, receive: ShareReceiveInput): SharePeerGroupPayload!
@@ -654,7 +702,15 @@ extend type Mutation {
   DID comes from the request's KeyPackage credential; a disagreeing did field, or a
   DID already on the roster, is refused.
   """
-  admitJoinRequest(groupID: ID!, joinRequest: String!, send: ShareInput, receive: ShareReceiveInput): AdmitJoinRequestPayload!
+  admitJoinRequest(groupID: ID!, joinRequest: String!, grants: [String!], send: ShareInput, receive: ShareReceiveInput): AdmitJoinRequestPayload!
+  """
+  Grant a device recipientDID this device's active credential keys for ownerDID,
+  resolving the recipient from the group's MLS roster. Returns every key's
+  outcome plus a grantor-signed manifest the recipient checks its store against.
+  minEpoch floors the allocated epoch at the recipient's held epoch, so a
+  reprovision attempt always supersedes a manifest it already holds. Defaults to 0.
+  """
+  grantDeviceCredentials(groupID: ID!, recipientDID: DID!, ownerDID: DID!, minEpoch: Int): GrantDeviceCredentialsPayload!
   joinPeerGroup(peerDID: ID!, groupID: ID!): JoinPeerGroupPayload!
   """
   Apply one circle's desired sync end state. A null argument leaves that dimension
@@ -880,6 +936,11 @@ export function createP2PSchemaExtension(emitter, syncManager, logger = getKubun
                     const requests = await requireP2P(context).group.listControlRequests(args.groupID);
                     return requests.map(toControlRequestSDL);
                 },
+                credentialProvisioningStatus: async (_source, args, context)=>{
+                    return await requireP2P(context).peer.credentialProvisioningStatus({
+                        ownerDID: args.ownerDID
+                    });
+                },
                 ownDelegationTokens: async (_source, args, context)=>{
                     const viewerDID = context.getViewer();
                     if (viewerDID == null || context.p2p == null) {
@@ -948,6 +1009,7 @@ export function createP2PSchemaExtension(emitter, syncManager, logger = getKubun
                     return await requireP2P(context).peer.admitJoinRequest({
                         groupID: args.groupID,
                         joinRequest: args.joinRequest,
+                        grants: args.grants ?? undefined,
                         sendModels: send?.models ?? null,
                         receiveActivate: receive?.activate ?? false,
                         // Same owner-signed executor `sharePeerGroup` binds, so the rows this
@@ -966,6 +1028,21 @@ export function createP2PSchemaExtension(emitter, syncManager, logger = getKubun
                         }
                     });
                 },
+                grantDeviceCredentials: async (_source, args, context)=>{
+                    const { results, manifest, epoch } = await requireP2P(context).peer.grantDeviceCredentials({
+                        groupID: args.groupID,
+                        recipientDID: args.recipientDID,
+                        ownerDID: args.ownerDID,
+                        ...args.minEpoch == null ? {} : {
+                            minEpoch: args.minEpoch
+                        }
+                    });
+                    return {
+                        results,
+                        manifest,
+                        epoch
+                    };
+                },
                 joinPeerGroup: async (_source, args, context)=>{
                     return await requireP2P(context).peer.joinPeerGroup({
                         peerDID: args.peerDID,

package/lib/sync/handlers.js

@@ -283,14 +283,33 @@ export { checkSyncDelegation };
                     ...toWireOp(op),
                     subjectID: op.subject_id
                 }));
+            // Durable PULL repair, independent of live broadcast: manifests addressed
+            // to the authenticated `callerDID`, never an owner-supplied recipient,
+            // so a manifest never leaks to a device other than the one it names.
+            let manifests;
+            if (ctx.param.owners != null && ctx.param.owners.length > 0) {
+                // Independent per-owner lookups — query concurrently, preserve owner order.
+                const perOwner = await Promise.all(ctx.param.owners.map((owner)=>store.listManifests({
+                        ownerDID: owner,
+                        recipientDID: callerDID
+                    })));
+                manifests = perOwner.flatMap((rows)=>rows.map((row)=>({
+                            manifest: row.token,
+                            delegationTokens: row.delegationTokens
+                        })));
+            }
             logger.debug('sync/reconcile-credentials served', {
                 callerDID,
                 bundles: bundles.length,
-                tombstones: tombstones.length
+                tombstones: tombstones.length,
+                manifests: manifests?.length ?? 0
             });
             return {
                 bundles,
-                tombstones
+                tombstones,
+                ...manifests != null && {
+                    manifests
+                }
             };
         }
     });

package/lib/sync/held-delegations.d.ts

@@ -0,0 +1,14 @@
+import type { StoreProvider } from '@kubun/db';
+/**
+ * The device's own held read delegations for a set of scope owners, as the JWT
+ * strings an outbound catch-up rides in `delegationTokens`.
+ *
+ * Each token is a capability the owner (grantor) issued to this device
+ * (audience); presenting it lets the peer's `checkSyncDelegation` arm of
+ * `authorizeScope` authorize a pull of that owner's documents — e.g. a paired
+ * device reading a controller's documents via the pairing-time delegation.
+ *
+ * Keyed `grantor: ownerDID, audience: selfDID` (the direction the gate checks).
+ * Owners equal to `selfDID` are skipped; results are de-duplicated.
+ */
+export declare function resolveHeldDelegationTokens(stores: StoreProvider, selfDID: string, owners: Iterable<string>): Promise<Array<string>>;

package/lib/sync/held-delegations.js

@@ -0,0 +1,34 @@
+import { DELEGATION_STORE, getDelegationStore } from '@kubun/store-delegation';
+/**
+ * The device's own held read delegations for a set of scope owners, as the JWT
+ * strings an outbound catch-up rides in `delegationTokens`.
+ *
+ * Each token is a capability the owner (grantor) issued to this device
+ * (audience); presenting it lets the peer's `checkSyncDelegation` arm of
+ * `authorizeScope` authorize a pull of that owner's documents — e.g. a paired
+ * device reading a controller's documents via the pairing-time delegation.
+ *
+ * Keyed `grantor: ownerDID, audience: selfDID` (the direction the gate checks).
+ * Owners equal to `selfDID` are skipped; results are de-duplicated.
+ */ export async function resolveHeldDelegationTokens(stores, selfDID, owners) {
+    const distinctOwners = new Set();
+    for (const owner of owners){
+        if (owner !== selfDID) {
+            distinctOwners.add(owner);
+        }
+    }
+    if (distinctOwners.size === 0 || !stores.hasStore(DELEGATION_STORE)) {
+        return [];
+    }
+    const delegationStore = await getDelegationStore(stores);
+    // Independent per-owner lookups — query concurrently; the Set dedups regardless of order.
+    const perOwner = await Promise.all([
+        ...distinctOwners
+    ].map((ownerDID)=>delegationStore.getDelegationTokens({
+            grantor: ownerDID,
+            audience: selfDID
+        })));
+    return [
+        ...new Set(perOwner.flat().map((row)=>row.token))
+    ];
+}

package/lib/sync/hub-tunnel-service-listener.d.ts

@@ -0,0 +1,84 @@
+import type { ServerTransportOf } from '@enkaku/protocol';
+import type { Server } from '@enkaku/server';
+import type { DIDCache } from '@kokuin/token';
+import type { Logger } from '@kubun/logger';
+import type { ServiceConfig, ServiceProtocol } from '@kubun/plugin-service-api';
+import { type MailboxHub } from '@kumiai/hub-tunnel';
+import type { Runtime } from '@sozai/runtime';
+import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+/**
+ * Mirrors `ServiceServerPluginAPI['serve']` (`@kubun/plugin-service-server`)
+ * without importing it, so this listener has no direct dependency on that
+ * plugin. `serve()` applies provider discovery, handler/access-rule merge,
+ * handler-authorization wrapping, and controller-DID verification that a bare
+ * `new Server` would not.
+ */
+export type ServeService = (params: {
+    transport: ServerTransportOf<ServiceProtocol>;
+    services: Record<string, ServiceConfig>;
+    requireAuth?: false;
+    /** Shared, roster-seeded DID cache forwarded to the served Server. */
+    cache?: DIDCache;
+}) => Server<ServiceProtocol>;
+/**
+ * The injected {@link ServeService} was called before the `service-server`
+ * plugin API had resolved. Transient — the listener retries on its normal backoff.
+ */
+export declare class ServiceServeNotReadyError extends Error {
+    constructor(message: string);
+}
+/**
+ * The injected {@link ServeService} failed for a reason a retry cannot change
+ * (plugin absent, unknown/colliding service name). Terminal — the listener
+ * stops answering for this peer instead of spinning on backoff.
+ */
+export declare class ServiceServeUnavailableError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export type HubTunnelServiceListenerParams = {
+    /**
+     * Shared multi-subscriber device hub. Every listener on a device receives on
+     * the same topic, so the hub is fronted by a per-peer view that drops other
+     * peers' frames before they reach the cipher.
+     */
+    hub: MailboxHub;
+    registry: GroupHandleRegistry;
+    groupID: string;
+    localDID: string;
+    peerDID: string;
+    /**
+     * Platform primitives, including the per-session id generator. Threaded in
+     * from the caller since this package runs on React Native and browser too,
+     * not just node.
+     */
+    runtime: Runtime;
+    /** Injected `plugin-service-server` `serve()` — see {@link ServeService}. */
+    serve: ServeService;
+    /** Which services to serve, forwarded verbatim to {@link serve} on every spawn. */
+    services: Record<string, ServiceConfig>;
+    /**
+     * Shared, roster-seeded DID cache forwarded to {@link serve} on every spawn,
+     * so a co-member's short-form `did:peer:4` issuer resolves on the served
+     * Server.
+     */
+    cache?: DIDCache;
+    idleTimeoutMs?: number;
+    logger?: Logger;
+};
+/**
+ * Answer side of the service tunnel — the same directed hub-tunnel machinery as
+ * `HubTunnelSyncListener`, on a distinct lane so a service session never
+ * collides with a sync session's topics or ratchet generation.
+ *
+ * Unlike the sync listener, this does not build a bare `Server`: it hands the
+ * spawned transport to the injected {@link ServeService} callback so
+ * provider discovery, handler wrapping, and controller-DID verification apply.
+ */
+export declare class HubTunnelServiceListener {
+    #private;
+    constructor(params: HubTunnelServiceListenerParams);
+    start(): void;
+    stop(): Promise<void>;
+}