@kubun/plugin-p2p 0.10.1 → 0.11.0

package/lib/schema.d.ts

@@ -1,3 +1,4 @@
 import type { SchemaExtension } from '@kubun/engine';
+import { type Logger } from '@kubun/logger';
 import { type P2PEventEmitter } from './groups/events.js';
-export declare function createP2PSchemaExtension(emitter: P2PEventEmitter): SchemaExtension;
+export declare function createP2PSchemaExtension(emitter: P2PEventEmitter, logger?: Logger): SchemaExtension;

package/lib/schema.js

@@ -1,4 +1,55 @@
-import{createFilteredGenerator as e}from"./groups/events.js";function r(e){if(null==e.p2p)throw Error("p2p plugin is not wired into this context");return e.p2p}let t={healthy:"HEALTHY",degraded:"DEGRADED",recovering:"RECOVERING",recovered:"RECOVERED","recovery-failed":"RECOVERY_FAILED"},o={"epoch-stale":"EPOCH_STALE"};async function*a(){}let i=`
+import { TransactionFatalError } from '@kubun/engine';
+import { getKubunLogger } from '@kubun/logger';
+import { createFilteredGenerator } from './groups/events.js';
+function requireP2P(ctx) {
+    if (ctx.p2p == null) {
+        throw new Error('p2p plugin is not wired into this context');
+    }
+    return ctx.p2p;
+}
+/**
+ * Re-raise any failure from a membership/circle operation as the engine's
+ * transaction-rollback marker so `mutateGraph` rolls back the whole transaction.
+ * These ops do multi-step writes (an MLS ratchet advance plus a roster write, or
+ * a ledger append plus a reprojection); graphql-js would otherwise swallow a
+ * follow-on throw into `result.errors` and commit a partial result, leaving e.g.
+ * a removed member untombstoned and still writable. The original error's message
+ * is forwarded unchanged so an expected validation error (e.g. access-denied)
+ * still reaches the client as before; the cause carries the full original error.
+ *
+ * Only multi-write ops whose partial commit would fail OPEN (toward more
+ * privilege — leaving a removed/demoted DID authoritative) are wrapped:
+ * `inviteToGroup`, `removeGroupMember`, `leaveGroup`, `setMemberRole`,
+ * `removeCircleMember`. Ops that fail toward less privilege / benign metadata
+ * (circle create/update, capability writes) self-heal on the next idempotent
+ * reprojection and are intentionally left unwrapped — a new remove/demote op
+ * should add a wrap here.
+ *
+ * Caveat: a thrown `GraphQLError`'s `extensions` (e.g. a `code`) are not carried
+ * onto the re-raised top-level error (they remain on `.cause`); none of the
+ * wrapped resolvers currently throw coded GraphQLErrors, so no client-visible
+ * code is lost today.
+ */ function failTransactionFatal(operation, error) {
+    const message = error instanceof Error ? error.message : `${operation} failed`;
+    throw new TransactionFatalError(message, {
+        cause: error
+    });
+}
+// Internal lowercase-kebab health values -> SDL enum names.
+const HEALTH_STATE_TO_SDL = {
+    healthy: 'HEALTHY',
+    degraded: 'DEGRADED',
+    recovering: 'RECOVERING',
+    recovered: 'RECOVERED',
+    'recovery-failed': 'RECOVERY_FAILED'
+};
+const HEALTH_CONDITION_TO_SDL = {
+    'epoch-stale': 'EPOCH_STALE'
+};
+async function* emptyAsyncGenerator() {
+// no-op: closes immediately so subscribers without a viewer get no events
+}
+const sdl = `
 type PeerGroup {
   id: ID!
   name: String!
@@ -88,6 +139,21 @@ type RemoveGroupMemberPayload {
   groupID: ID!
 }
 
+enum GroupMemberRole {
+  admin
+  member
+}
+
+input SetMemberRoleInput {
+  groupID: ID!
+  memberDID: DID!
+  role: GroupMemberRole!
+}
+
+type SetMemberRolePayload {
+  member: PeerGroupMember!
+}
+
 input UpdateCatalogInput {
   catalogID: ID!
   name: String
@@ -266,6 +332,7 @@ extend type Mutation {
   completeJoin(invitePayload: String!): CompleteJoinPayload!
   leaveGroup(groupID: ID!): LeaveGroupPayload!
   removeGroupMember(groupID: ID!, memberDID: DID!): RemoveGroupMemberPayload!
+  setMemberRole(input: SetMemberRoleInput!): SetMemberRolePayload!
   updateCatalog(input: UpdateCatalogInput!): PeerCatalog!
   updateGroup(input: UpdateGroupInput!): UpdateGroupPayload!
   updateCircle(input: UpdateCircleInput!): UpdateCirclePayload!
@@ -308,4 +375,374 @@ extend type Subscription {
   ownDelegationTokenRevoked: RevokedDelegationToken!
   groupHealthChanged(groupID: ID): GroupHealthEvent!
 }
-`;export function createP2PSchemaExtension(n){return{sdl:i,resolvers:{queryFields:{groups:async(e,t,o)=>await r(o).group.list(),group:async(e,t,o)=>await r(o).group.get(t.id),groupMembers:async(e,t,o)=>await r(o).group.listMembers(t.groupID),circles:async(e,t,o)=>await r(o).group.listCircles(t.groupID),hubs:async(e,t,o)=>await r(o).hub.list(),hub:async(e,t,o)=>await r(o).hub.get(t.id),syncPeers:async(e,t,o)=>await r(o).sync.listPeers(),syncStatus:(e,t,o)=>{let a=r(o).sync.getStatus();return{...a,lastSyncByPeer:JSON.stringify(a.lastSyncByPeer)}},groupHealth:(e,o,a)=>{let i=o.groupID,{state:n,lastTransitionAt:u}=r(a).hub.getGroupHealth(i);return{groupID:i,state:t[n],lastTransitionAt:null==u?null:new Date(u).toISOString()}},ownDelegationTokens:async(e,r,t)=>{let o=t.getViewer();if(null==o||null==t.p2p)return[];let a=r.grantor??null,i=r.covers??null;return await t.p2p.delegation.listOwnTokens({viewerDID:o,grantor:a,covers:i})},ownRevokedDelegationTokens:async(e,r,t)=>{let o=t.getViewer();if(null==o||null==t.p2p)return[];let a=r.grantor??null;return await t.p2p.delegation.listOwnRevokedTokens({viewerDID:o,grantor:a})}},mutationFields:{createGroup:async(e,t,o)=>{let a=t.input;return{group:await r(o).group.create(a)}},addGroupMember:async(e,t,o)=>await r(o).group.addMember(t.groupID,t.memberDID,t.role),createCircle:async(e,t,o)=>await r(o).group.createCircle({groupID:t.groupID,name:t.name,description:t.description}),addCircleMember:async(e,t,o)=>await r(o).group.addCircleMember(t.circleID,t.memberDID,t.role),createCatalog:async(e,t,o)=>await r(o).group.createCatalog({name:t.name,description:t.description,filterCriteria:t.filterCriteria}),inviteToGroup:async(e,t,o)=>await r(o).group.invite(t.groupID,t.joinRequest,t.grants,t.revocations),joinGroup:async(e,t,o)=>await r(o).group.join(t.invitePayload,t.joinRequestPayload),prepareJoinRequest:async(e,t,o)=>await r(o).join.prepareRequest(),completeJoin:async(e,t,o)=>await r(o).join.complete(t.invitePayload),leaveGroup:async(e,t,o)=>await r(o).group.leave(t.groupID),removeGroupMember:async(e,t,o)=>await r(o).group.removeMember(t.groupID,t.memberDID),updateCatalog:async(e,t,o)=>{let a=t.input;return await r(o).group.updateCatalog(a)},updateGroup:async(e,t,o)=>{let a=t.input;return{group:await r(o).group.update(a)}},updateCircle:async(e,t,o)=>{let a=t.input;return{circle:await r(o).group.updateCircle(a)}},deleteCatalog:async(e,t,o)=>await r(o).group.deleteCatalog(t.catalogID),deleteCircle:async(e,t,o)=>await r(o).group.deleteCircle(t.circleID),removeCircleMember:async(e,t,o)=>await r(o).group.removeCircleMember(t.circleID,t.memberDID),grantWriteCapability:async(e,t,o)=>await r(o).group.grantWriteCapability({to:t.to,res:t.res,groupID:t.groupID,expiresIn:t.expiresIn}),revokeCapability:async(e,t,o)=>await r(o).group.revokeCapability({jti:t.jti}),addSyncPeer:async(e,t,o)=>(await r(o).sync.addPeer({peerDID:t.peerDID,endpoint:t.endpoint,mode:t.mode??"on-demand",allowedUsers:{all:!0},priority:t.priority??"0",trustLevel:t.trustLevel??"trusted"}),!0),removeSyncPeer:async(e,t,o)=>(await r(o).sync.removePeer(t.peerDID),{success:!0}),createHub:async(e,t,o)=>{let a=t.input;return await r(o).hub.create(a)},updateHub:async(e,t,o)=>{let a=t.input;return await r(o).hub.update(a)},deleteHub:async(e,t,o)=>await r(o).hub.delete(t.id,t.force??!1),bindHubToGroup:async(e,t,o)=>await r(o).hub.bind({hubID:t.hubID,groupID:t.groupID}),unbindHubFromGroup:async(e,t,o)=>await r(o).hub.unbind({hubID:t.hubID,groupID:t.groupID}),rejoinGroup:(e,t,o)=>{let a=t.groupID,i=r(o).hub,{state:n}=i.getGroupHealth(a);return"healthy"!==n&&"recovering"!==n&&i.rejoinGroup(a),{groupID:a,state:"healthy"===n?"HEALTHY":"RECOVERING"}}},typeFields:{PeerGroup:{hubs:async(e,t,o)=>await r(o).hub.listByGroup(e.id)},PeerHub:{groups:async(e,t,o)=>await r(o).hub.listGroups(e.id)}},subscriptionFields:{groupJoined:{resolve:e=>e,subscribe:()=>e(n,"groupJoined")},groupLeft:{resolve:e=>e,subscribe:()=>e(n,"groupLeft")},groupDataChanged:{resolve:e=>e,subscribe:(r,t)=>e(n,"groupDataChanged",e=>e.groupID===t.groupID)},groupMemberJoined:{resolve:e=>e,subscribe:(r,t)=>e(n,"groupMemberJoined",e=>e.groupID===t.groupID)},groupMemberLeft:{resolve:e=>e,subscribe:(r,t)=>e(n,"groupMemberLeft",e=>e.groupID===t.groupID)},circleCreated:{resolve:e=>e,subscribe:(r,t)=>e(n,"circleCreated",e=>e.groupID===t.groupID)},circleDeleted:{resolve:e=>e,subscribe:(r,t)=>e(n,"circleDeleted",e=>e.groupID===t.groupID)},circleDataChanged:{resolve:e=>e,subscribe:(r,t)=>e(n,"circleDataChanged",e=>e.circleID===t.circleID)},circleMemberAdded:{resolve:e=>e,subscribe:(r,t)=>e(n,"circleMemberAdded",e=>e.circleID===t.circleID)},circleMemberRemoved:{resolve:e=>e,subscribe:(r,t)=>e(n,"circleMemberRemoved",e=>e.circleID===t.circleID)},circleCatalogsChanged:{resolve:e=>e,subscribe:(r,t)=>e(n,"circleCatalogsChanged",e=>e.circleID===t.circleID)},ownDelegationTokenAdded:{resolve:e=>e,subscribe:(r,t,o)=>{let i=o.getViewer();return null==i?a():e(n,"delegationTokenAdded",e=>e.audience===i)}},ownDelegationTokenRevoked:{resolve:e=>e,subscribe:(r,t,o)=>{let i=o.getViewer();return null==i?a():e(n,"delegationTokenRevoked",e=>e.audience===i)}},groupHealthChanged:{resolve:e=>({groupID:e.groupID,condition:o[e.condition],state:t[e.state]}),subscribe:(r,t)=>{let o=t.groupID;return e(n,"groupHealthChanged",null==o?void 0:e=>e.groupID===o)}}}}}}
+`;
+export function createP2PSchemaExtension(emitter, logger = getKubunLogger('p2p-schema')) {
+    return {
+        sdl,
+        resolvers: {
+            queryFields: {
+                groups: async (_source, _args, context)=>{
+                    return await requireP2P(context).group.list();
+                },
+                group: async (_source, args, context)=>{
+                    return await requireP2P(context).group.get(args.id);
+                },
+                groupMembers: async (_source, args, context)=>{
+                    return await requireP2P(context).group.listMembers(args.groupID);
+                },
+                circles: async (_source, args, context)=>{
+                    return await requireP2P(context).group.listCircles(args.groupID);
+                },
+                hubs: async (_source, _args, context)=>{
+                    return await requireP2P(context).hub.list();
+                },
+                hub: async (_source, args, context)=>{
+                    return await requireP2P(context).hub.get(args.id);
+                },
+                syncPeers: async (_source, _args, context)=>{
+                    return await requireP2P(context).sync.listPeers();
+                },
+                syncStatus: (_source, _args, context)=>{
+                    const status = requireP2P(context).sync.getStatus();
+                    return {
+                        ...status,
+                        lastSyncByPeer: JSON.stringify(status.lastSyncByPeer)
+                    };
+                },
+                // INERT: always reports `healthy` — nothing signals the monitor. Live
+                // scaffolding for epoch-stale recovery; see
+                // docs/agents/plans/backlog/welcome-based-deep-recovery.md.
+                groupHealth: (_source, args, context)=>{
+                    const groupID = args.groupID;
+                    const { state, lastTransitionAt } = requireP2P(context).hub.getGroupHealth(groupID);
+                    return {
+                        groupID,
+                        state: HEALTH_STATE_TO_SDL[state],
+                        lastTransitionAt: lastTransitionAt == null ? null : new Date(lastTransitionAt).toISOString()
+                    };
+                },
+                ownDelegationTokens: async (_source, args, context)=>{
+                    const viewerDID = context.getViewer();
+                    if (viewerDID == null || context.p2p == null) {
+                        return [];
+                    }
+                    const grantor = args.grantor ?? null;
+                    const covers = args.covers ?? null;
+                    return await context.p2p.delegation.listOwnTokens({
+                        viewerDID,
+                        grantor,
+                        covers
+                    });
+                },
+                ownRevokedDelegationTokens: async (_source, args, context)=>{
+                    const viewerDID = context.getViewer();
+                    if (viewerDID == null || context.p2p == null) {
+                        return [];
+                    }
+                    const grantor = args.grantor ?? null;
+                    return await context.p2p.delegation.listOwnRevokedTokens({
+                        viewerDID,
+                        grantor
+                    });
+                }
+            },
+            mutationFields: {
+                createGroup: async (_source, args, context)=>{
+                    const input = args.input;
+                    const group = await requireP2P(context).group.create(input);
+                    return {
+                        group
+                    };
+                },
+                addGroupMember: async (_source, args, context)=>{
+                    return await requireP2P(context).group.addMember(args.groupID, args.memberDID, args.role);
+                },
+                createCircle: async (_source, args, context)=>{
+                    return await requireP2P(context).group.createCircle({
+                        groupID: args.groupID,
+                        name: args.name,
+                        description: args.description
+                    });
+                },
+                addCircleMember: async (_source, args, context)=>{
+                    return await requireP2P(context).group.addCircleMember(args.circleID, args.memberDID, args.role);
+                },
+                createCatalog: async (_source, args, context)=>{
+                    return await requireP2P(context).group.createCatalog({
+                        name: args.name,
+                        description: args.description,
+                        filterCriteria: args.filterCriteria
+                    });
+                },
+                inviteToGroup: async (_source, args, context)=>{
+                    // invite advances the MLS ratchet and writes the local roster: any
+                    // throw must roll back the whole transaction so the eagerly-swapped
+                    // MLS epoch can never outlive a failed roster write.
+                    try {
+                        return await requireP2P(context).group.invite(args.groupID, args.joinRequest, args.grants, args.revocations);
+                    } catch (error) {
+                        failTransactionFatal('inviteToGroup', error);
+                    }
+                },
+                joinGroup: async (_source, args, context)=>{
+                    return await requireP2P(context).group.join(args.invitePayload, args.joinRequestPayload);
+                },
+                prepareJoinRequest: async (_source, _args, context)=>{
+                    return await requireP2P(context).join.prepareRequest();
+                },
+                completeJoin: async (_source, args, context)=>{
+                    return await requireP2P(context).join.complete(args.invitePayload);
+                },
+                leaveGroup: async (_source, args, context)=>{
+                    // leave tears down the MLS handle and emits a leave event: any throw
+                    // must roll back so a partial teardown is never committed.
+                    try {
+                        return await requireP2P(context).group.leave(args.groupID);
+                    } catch (error) {
+                        failTransactionFatal('leaveGroup', error);
+                    }
+                },
+                removeGroupMember: async (_source, args, context)=>{
+                    // removeMember advances the MLS ratchet and tombstones the removed
+                    // member: any throw must roll back so a removed member can never be
+                    // left untombstoned (and still writable) after a partial commit.
+                    try {
+                        return await requireP2P(context).group.removeMember(args.groupID, args.memberDID);
+                    } catch (error) {
+                        failTransactionFatal('removeGroupMember', error);
+                    }
+                },
+                setMemberRole: async (_source, args, context)=>{
+                    const input = args.input;
+                    // setMemberRole appends a ledger entry and reprojects the admin
+                    // overlay: any throw must roll back so the durable ledger and the
+                    // projected role column can never diverge across a partial commit.
+                    try {
+                        const member = await requireP2P(context).group.setMemberRole(input);
+                        return {
+                            member
+                        };
+                    } catch (error) {
+                        failTransactionFatal('setMemberRole', error);
+                    }
+                },
+                updateCatalog: async (_source, args, context)=>{
+                    const input = args.input;
+                    return await requireP2P(context).group.updateCatalog(input);
+                },
+                updateGroup: async (_source, args, context)=>{
+                    const input = args.input;
+                    const group = await requireP2P(context).group.update(input);
+                    return {
+                        group
+                    };
+                },
+                updateCircle: async (_source, args, context)=>{
+                    const input = args.input;
+                    const circle = await requireP2P(context).group.updateCircle(input);
+                    return {
+                        circle
+                    };
+                },
+                deleteCatalog: async (_source, args, context)=>{
+                    return await requireP2P(context).group.deleteCatalog(args.catalogID);
+                },
+                deleteCircle: async (_source, args, context)=>{
+                    return await requireP2P(context).group.deleteCircle(args.circleID);
+                },
+                removeCircleMember: async (_source, args, context)=>{
+                    // removeCircleMember appends a tombstone ledger entry and reprojects
+                    // the circle-member overlay: any throw must roll back so the durable
+                    // ledger and the projected row can never diverge across a partial
+                    // commit.
+                    try {
+                        return await requireP2P(context).group.removeCircleMember(args.circleID, args.memberDID);
+                    } catch (error) {
+                        failTransactionFatal('removeCircleMember', error);
+                    }
+                },
+                grantWriteCapability: async (_source, args, context)=>{
+                    return await requireP2P(context).group.grantWriteCapability({
+                        to: args.to,
+                        res: args.res,
+                        groupID: args.groupID,
+                        expiresIn: args.expiresIn
+                    });
+                },
+                revokeCapability: async (_source, args, context)=>{
+                    return await requireP2P(context).group.revokeCapability({
+                        jti: args.jti
+                    });
+                },
+                addSyncPeer: async (_source, args, context)=>{
+                    await requireP2P(context).sync.addPeer({
+                        peerDID: args.peerDID,
+                        endpoint: args.endpoint,
+                        mode: args.mode ?? 'on-demand',
+                        allowedUsers: {
+                            all: true
+                        },
+                        priority: args.priority ?? '0',
+                        trustLevel: args.trustLevel ?? 'trusted'
+                    });
+                    return true;
+                },
+                removeSyncPeer: async (_source, args, context)=>{
+                    await requireP2P(context).sync.removePeer(args.peerDID);
+                    return {
+                        success: true
+                    };
+                },
+                createHub: async (_source, args, context)=>{
+                    const input = args.input;
+                    return await requireP2P(context).hub.create(input);
+                },
+                updateHub: async (_source, args, context)=>{
+                    const input = args.input;
+                    return await requireP2P(context).hub.update(input);
+                },
+                deleteHub: async (_source, args, context)=>{
+                    return await requireP2P(context).hub.delete(args.id, args.force ?? false);
+                },
+                bindHubToGroup: async (_source, args, context)=>{
+                    return await requireP2P(context).hub.bind({
+                        hubID: args.hubID,
+                        groupID: args.groupID
+                    });
+                },
+                unbindHubFromGroup: async (_source, args, context)=>{
+                    return await requireP2P(context).hub.unbind({
+                        hubID: args.hubID,
+                        groupID: args.groupID
+                    });
+                },
+                // INERT: `getGroupHealth` always returns `healthy` (nothing signals the
+                // monitor), so the kickoff branch below is currently unreachable and
+                // `hub.rejoinGroup` terminates in the deferred `recovery-failed` stub.
+                // Reserved for epoch-stale recovery; see
+                // docs/agents/plans/backlog/welcome-based-deep-recovery.md.
+                rejoinGroup: (_source, args, context)=>{
+                    const groupID = args.groupID;
+                    const hub = requireP2P(context).hub;
+                    const { state } = hub.getGroupHealth(groupID);
+                    // Async kickoff (when wired): already-current is a no-op; an in-flight
+                    // rejoin is not restarted. The terminal outcome would arrive via the
+                    // groupHealthChanged stream.
+                    if (state !== 'healthy' && state !== 'recovering') {
+                        // Log-only: catch so a throw (e.g. no active channel) can't leak.
+                        hub.rejoinGroup(groupID).catch((error)=>{
+                            logger.error('rejoinGroup kickoff failed', {
+                                groupID,
+                                error
+                            });
+                        });
+                    }
+                    const reported = state === 'healthy' ? 'HEALTHY' : 'RECOVERING';
+                    return {
+                        groupID,
+                        state: reported
+                    };
+                }
+            },
+            typeFields: {
+                PeerGroup: {
+                    hubs: async (source, _args, context)=>{
+                        const group = source;
+                        return await requireP2P(context).hub.listByGroup(group.id);
+                    }
+                },
+                PeerHub: {
+                    groups: async (source, _args, context)=>{
+                        const hub = source;
+                        return await requireP2P(context).hub.listGroups(hub.id);
+                    }
+                }
+            },
+            subscriptionFields: {
+                groupJoined: {
+                    resolve: (group)=>group,
+                    subscribe: ()=>createFilteredGenerator(emitter, 'groupJoined')
+                },
+                groupLeft: {
+                    resolve: (group)=>group,
+                    subscribe: ()=>createFilteredGenerator(emitter, 'groupLeft')
+                },
+                groupDataChanged: {
+                    resolve: (group)=>group,
+                    subscribe: (_src, args)=>createFilteredGenerator(emitter, 'groupDataChanged', (d)=>d.groupID === args.groupID)
+                },
+                groupMemberJoined: {
+                    resolve: (member)=>member,
+                    subscribe: (_src, args)=>createFilteredGenerator(emitter, 'groupMemberJoined', (d)=>d.groupID === args.groupID)
+                },
+                groupMemberLeft: {
+                    resolve: (member)=>member,
+                    subscribe: (_src, args)=>createFilteredGenerator(emitter, 'groupMemberLeft', (d)=>d.groupID === args.groupID)
+                },
+                circleCreated: {
+                    resolve: (circle)=>circle,
+                    subscribe: (_src, args)=>createFilteredGenerator(emitter, 'circleCreated', (d)=>d.groupID === args.groupID)
+                },
+                circleDeleted: {
+                    resolve: (circle)=>circle,
+                    subscribe: (_src, args)=>createFilteredGenerator(emitter, 'circleDeleted', (d)=>d.groupID === args.groupID)
+                },
+                circleDataChanged: {
+                    resolve: (circle)=>circle,
+                    subscribe: (_src, args)=>createFilteredGenerator(emitter, 'circleDataChanged', (d)=>d.circleID === args.circleID)
+                },
+                circleMemberAdded: {
+                    resolve: (member)=>member,
+                    subscribe: (_src, args)=>createFilteredGenerator(emitter, 'circleMemberAdded', (d)=>d.circleID === args.circleID)
+                },
+                circleMemberRemoved: {
+                    resolve: (member)=>member,
+                    subscribe: (_src, args)=>createFilteredGenerator(emitter, 'circleMemberRemoved', (d)=>d.circleID === args.circleID)
+                },
+                circleCatalogsChanged: {
+                    resolve: (circle)=>circle,
+                    subscribe: (_src, args)=>createFilteredGenerator(emitter, 'circleCatalogsChanged', (d)=>d.circleID === args.circleID)
+                },
+                ownDelegationTokenAdded: {
+                    resolve: (data)=>data,
+                    subscribe: (_src, _args, context)=>{
+                        const viewerDID = context.getViewer();
+                        if (viewerDID == null) {
+                            return emptyAsyncGenerator();
+                        }
+                        return createFilteredGenerator(emitter, 'delegationTokenAdded', (data)=>data.audience === viewerDID);
+                    }
+                },
+                ownDelegationTokenRevoked: {
+                    resolve: (data)=>data,
+                    subscribe: (_src, _args, context)=>{
+                        const viewerDID = context.getViewer();
+                        if (viewerDID == null) {
+                            return emptyAsyncGenerator();
+                        }
+                        // Audience-side filter mirrors `ownDelegationTokenAdded` — the
+                        // viewer subscribes to revocations of caps they hold (or held).
+                        return createFilteredGenerator(emitter, 'delegationTokenRevoked', (data)=>data.audience === viewerDID);
+                    }
+                },
+                // INERT: this subscription can never fire — `groupHealthChanged` has no
+                // live producer. Reserved for epoch-stale recovery; see
+                // docs/agents/plans/backlog/welcome-based-deep-recovery.md.
+                groupHealthChanged: {
+                    resolve: (data)=>{
+                        const event = data;
+                        return {
+                            groupID: event.groupID,
+                            condition: HEALTH_CONDITION_TO_SDL[event.condition],
+                            state: HEALTH_STATE_TO_SDL[event.state]
+                        };
+                    },
+                    subscribe: (_src, args)=>{
+                        const groupID = args.groupID;
+                        return createFilteredGenerator(emitter, 'groupHealthChanged', groupID == null ? undefined : (d)=>d.groupID === groupID);
+                    }
+                }
+            }
+        }
+    };
+}

package/lib/sync/authorize.d.ts

@@ -1,4 +1,4 @@
-import { type VerifyTokenHook } from '@enkaku/capability';
+import { type VerifyTokenHook } from '@kokuin/capability';
 /**
  * Check if delegation tokens grant the viewer read access to a user's documents.
  *

package/lib/sync/authorize.js

@@ -1 +1,73 @@
-import{checkCapability as e}from"@enkaku/capability";export async function checkSyncDelegation(r,t,n,o){if(!n||0===n.length)return!1;let c=["*","urn:kubun:user:*",`urn:kubun:user:${t}`],a="document/read";for(let u of c)try{return await e({act:a,res:u},{iss:r,sub:t,cap:n},{verifyToken:o}),!0}catch{}for(let u of n)for(let n of c)try{return await e({act:a,res:n},{iss:r,sub:t,cap:u},{verifyToken:o}),!0}catch{}return!1}export async function authorizeScope(e){return e.viewerDID===e.ownerDID||checkSyncDelegation(e.viewerDID,e.ownerDID,e.delegationTokens,e.revocationChecker)}
+import { checkCapability } from '@kokuin/capability';
+/**
+ * Check if delegation tokens grant the viewer read access to a user's documents.
+ *
+ * @param viewerDID - The DID of the requesting viewer
+ * @param ownerDID - The DID of the document owner
+ * @param delegationTokens - Array of delegation JWT tokens
+ * @param revocationChecker - Optional per-leaf-capability verification hook.
+ *   When set, capabilities whose `jti` has been revoked cause the check to
+ *   fail closed.
+ * @returns true if any token grants read access
+ */ export async function checkSyncDelegation(viewerDID, ownerDID, delegationTokens, revocationChecker) {
+    if (!delegationTokens || delegationTokens.length === 0) {
+        return false;
+    }
+    // Resource patterns to check (from most general to specific)
+    // We need at least read access to the user's documents
+    const resources = [
+        '*',
+        'urn:kubun:user:*',
+        `urn:kubun:user:${ownerDID}`
+    ];
+    const action = 'document/read';
+    // Try delegation chain first (tokens are a chain: A->B->C)
+    for (const res of resources){
+        try {
+            await checkCapability({
+                act: action,
+                res
+            }, {
+                iss: viewerDID,
+                sub: ownerDID,
+                cap: delegationTokens
+            }, {
+                verifyToken: revocationChecker
+            });
+            return true;
+        } catch  {
+        // Continue checking other resources
+        }
+    }
+    // Try each token independently (multiple independent grants)
+    for (const token of delegationTokens){
+        for (const res of resources){
+            try {
+                await checkCapability({
+                    act: action,
+                    res
+                }, {
+                    iss: viewerDID,
+                    sub: ownerDID,
+                    cap: token
+                }, {
+                    verifyToken: revocationChecker
+                });
+                return true;
+            } catch  {
+            // Continue checking
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Authorize a single sync scope: the viewer must be the owner, or hold a
+ * delegation token granting read access to the owner's documents. Shared by
+ * negotiate and merkle-sync so the two access gates cannot drift apart.
+ */ export async function authorizeScope(params) {
+    if (params.viewerDID === params.ownerDID) {
+        return true;
+    }
+    return checkSyncDelegation(params.viewerDID, params.ownerDID, params.delegationTokens, params.revocationChecker);
+}