@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/sync/access-default-sender.d.ts

@@ -0,0 +1,23 @@
+import type { OwnIdentity } from '@kokuin/token';
+import type { KubunDB } from '@kubun/db';
+import type { EngineEventBus, EngineEvents } from '@kubun/engine';
+import type { Logger } from '@kubun/logger';
+import type { GroupBroadcastMessage } from '../groups/broadcast.js';
+export type AccessDefaultSenderParams = {
+    db: KubunDB;
+    eventBus: EngineEventBus<EngineEvents>;
+    identity: OwnIdentity;
+    /** Fire-and-forget hub broadcast trigger, one call per target group. */
+    scheduleBroadcast: (groupID: string, message: GroupBroadcastMessage) => void | Promise<void>;
+    logger?: Logger;
+};
+/**
+ * Subscribe to the engine's access-default events and replicate each rule to
+ * every MLS group the local peer belongs to. A model default is owner-global,
+ * not group-scoped: any co-member evaluating the owner's documents needs the
+ * rule, and the receiver's sender-bound apply keeps a forged owner out. The
+ * fan-out is a single tiny frame per group, so no scope resolution is needed.
+ *
+ * Returns a combined unsubscribe function for both listeners.
+ */
+export declare function wireAccessDefaultSender(params: AccessDefaultSenderParams): () => void;

package/lib/sync/access-default-sender.js

@@ -0,0 +1,80 @@
+import { getP2PStore } from '@kubun/store-p2p';
+import { signAccessDefaultRemove, signAccessDefaultSet } from '../groups/access-default-token.js';
+/**
+ * Subscribe to the engine's access-default events and replicate each rule to
+ * every MLS group the local peer belongs to. A model default is owner-global,
+ * not group-scoped: any co-member evaluating the owner's documents needs the
+ * rule, and the receiver's sender-bound apply keeps a forged owner out. The
+ * fan-out is a single tiny frame per group, so no scope resolution is needed.
+ *
+ * Returns a combined unsubscribe function for both listeners.
+ */ export function wireAccessDefaultSender(params) {
+    const broadcastToOwnGroups = async (message)=>{
+        const p2pStore = await getP2PStore(params.db);
+        const groups = await p2pStore.getGroupsForMember(params.identity.id);
+        // Distinct groups over distinct hub lanes with nothing shared between them,
+        // so the fan-out runs concurrently: in sequence one slow lane delays every
+        // group behind it.
+        await Promise.all(groups.map((group)=>params.scheduleBroadcast(group.id, message)));
+    };
+    const unsubscribeSet = params.eventBus.on('engine:access-default:set', async (event)=>{
+        try {
+            const auth = await signAccessDefaultSet(params.identity, {
+                modelID: event.modelID,
+                permissionType: event.permissionType,
+                rule: {
+                    level: event.accessLevel,
+                    allowedDIDs: event.allowedDIDs,
+                    allowedCircles: event.allowedCircles,
+                    allowedGroups: event.allowedGroups
+                },
+                hlc: event.hlc
+            });
+            await broadcastToOwnGroups({
+                type: 'access-default:set',
+                modelID: event.modelID,
+                permissionType: event.permissionType,
+                rule: {
+                    level: event.accessLevel,
+                    allowedDIDs: event.allowedDIDs,
+                    allowedCircles: event.allowedCircles,
+                    allowedGroups: event.allowedGroups
+                },
+                ownerDID: event.ownerDID,
+                hlc: event.hlc,
+                auth
+            });
+        } catch (error) {
+            params.logger?.warn('access-default-sender set handler failed', {
+                modelID: event.modelID,
+                error: String(error)
+            });
+        }
+    });
+    const unsubscribeRemove = params.eventBus.on('engine:access-default:removed', async (event)=>{
+        try {
+            const auth = await signAccessDefaultRemove(params.identity, {
+                modelID: event.modelID,
+                permissionTypes: event.permissionTypes,
+                hlc: event.hlc
+            });
+            await broadcastToOwnGroups({
+                type: 'access-default:remove',
+                modelID: event.modelID,
+                permissionTypes: event.permissionTypes,
+                ownerDID: event.ownerDID,
+                hlc: event.hlc,
+                auth
+            });
+        } catch (error) {
+            params.logger?.warn('access-default-sender remove handler failed', {
+                modelID: event.modelID,
+                error: String(error)
+            });
+        }
+    });
+    return ()=>{
+        unsubscribeSet();
+        unsubscribeRemove();
+    };
+}

package/lib/sync/authorize.d.ts

@@ -1,4 +1,5 @@
-import { type VerifyTokenHook } from '@enkaku/capability';
+import { type VerifyTokenHook } from '@kokuin/capability';
+import type { StoredAccessRule } from '@kubun/store-graph';
 /**
  * Check if delegation tokens grant the viewer read access to a user's documents.
  *
@@ -11,15 +12,68 @@ import { type VerifyTokenHook } from '@enkaku/capability';
  * @returns true if any token grants read access
  */
 export declare function checkSyncDelegation(viewerDID: string, ownerDID: string, delegationTokens: Array<string>, revocationChecker?: VerifyTokenHook): Promise<boolean>;
+/**
+ * Resolver for circle-granted sync scopes. All reads run against the SERVING
+ * device's own state: the owner's tier-2 read default, the requester's circle
+ * membership, and the requester's group membership. The methods are dumb store
+ * reads — the authorization rule combining them lives in {@link authorizeScope}
+ * so implementations cannot drift on the security-critical conjunction.
+ */
+export type CircleReadGrantResolver = {
+    /** The owner's tier-2 read default for the model, or `null` if none exists. */
+    getUserModelReadDefault(ownerDID: string, modelID: string): Promise<StoredAccessRule | null>;
+    /**
+     * Which of `circleIDs` the viewer reaches, each with the group it belongs to.
+     * An unknown or tombstoned circle is absent, so the gate fails closed on it.
+     *
+     * Batched rather than per-circle so the rule below costs a fixed number of
+     * reads instead of one per named circle — and the group arrives with the id,
+     * which keeps the tombstone filter that decides "unknown circle" in one place
+     * instead of two reads that could disagree.
+     */
+    listAccessibleCircles(viewerDID: string, circleIDs: Array<string>): Promise<Array<{
+        id: string;
+        groupID: string;
+    }>>;
+    /**
+     * Which of `groupIDs` the viewer is a member of, per the serving device's own
+     * membership view (rows grown only from local ops and verified MLS commits).
+     */
+    listMemberGroupIDs(viewerDID: string, groupIDs: Array<string>): Promise<Array<string>>;
+};
 export type AuthorizeScopeParams = {
     viewerDID: string;
     ownerDID: string;
+    modelID: string;
     delegationTokens: Array<string>;
     revocationChecker?: VerifyTokenHook;
+    /**
+     * Optional resolver enabling owner-granted read. When set, a scope the owner
+     * and delegation arms reject is still accepted if the owner's tier-2 read
+     * default for the model is `anyone`, or is `restricted` and names a circle the
+     * viewer belongs to. Only an explicit owner grant widens: the server default is
+     * never consulted, so a model with no tier-2 read default stays owner/
+     * delegation only. Omitted — owner + delegation only, unchanged.
+     */
+    circleReadGrant?: CircleReadGrantResolver;
 };
 /**
- * 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.
+ * Authorize a single sync scope: the viewer must be the owner, hold a delegation
+ * token granting read access to the owner's documents, or — when a
+ * {@link CircleReadGrantResolver} is supplied — be reached by the owner's tier-2
+ * read default for the model, either because that default is `anyone` or because
+ * the viewer is a member of a circle it names AND a member of that circle's
+ * group per the serving device's own view. Shared by negotiate and merkle-sync
+ * so the two access gates cannot drift apart. Fail-closed: any arm that is not
+ * satisfiable denies.
+ *
+ * The group-membership conjunct is that half of the open-access definition
+ * (`explicitMember OR (open AND groupMember)`): for an open circle
+ * `isMemberOfAnyCircle` already implies it, so the outer check is
+ * redundant-but-consistent; for the explicit arm it is a data-plane backstop.
+ * The circle roster is a projection of admin-signed ledger entries, while the
+ * serving device's group-membership rows grow only from its own ops and verified
+ * MLS commits — so even a polluted circle projection cannot open the data plane
+ * without a matching local row. Unknown circle or unresolvable group → deny.
  */
 export declare function authorizeScope(params: AuthorizeScopeParams): Promise<boolean>;

package/lib/sync/authorize.js

@@ -1 +1,114 @@
-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, hold a delegation
+ * token granting read access to the owner's documents, or — when a
+ * {@link CircleReadGrantResolver} is supplied — be reached by the owner's tier-2
+ * read default for the model, either because that default is `anyone` or because
+ * the viewer is a member of a circle it names AND a member of that circle's
+ * group per the serving device's own view. Shared by negotiate and merkle-sync
+ * so the two access gates cannot drift apart. Fail-closed: any arm that is not
+ * satisfiable denies.
+ *
+ * The group-membership conjunct is that half of the open-access definition
+ * (`explicitMember OR (open AND groupMember)`): for an open circle
+ * `isMemberOfAnyCircle` already implies it, so the outer check is
+ * redundant-but-consistent; for the explicit arm it is a data-plane backstop.
+ * The circle roster is a projection of admin-signed ledger entries, while the
+ * serving device's group-membership rows grow only from its own ops and verified
+ * MLS commits — so even a polluted circle projection cannot open the data plane
+ * without a matching local row. Unknown circle or unresolvable group → deny.
+ */ export async function authorizeScope(params) {
+    if (params.viewerDID === params.ownerDID) {
+        return true;
+    }
+    if (await checkSyncDelegation(params.viewerDID, params.ownerDID, params.delegationTokens, params.revocationChecker)) {
+        return true;
+    }
+    if (params.circleReadGrant != null) {
+        const grant = params.circleReadGrant;
+        const rule = await grant.getUserModelReadDefault(params.ownerDID, params.modelID);
+        // Reached only through a rule the owner actually stored: a `null` rule means
+        // the owner declared nothing, and the server default must never stand in for
+        // a declaration — a device whose default flipped would otherwise open every
+        // model on it.
+        if (rule != null && rule.level === 'anyone') {
+            return true;
+        }
+        if (rule != null && rule.level === 'restricted' && rule.allowedCircles != null && rule.allowedCircles.length > 0) {
+            // Per-circle conjunction: both checks must hold for the SAME circle, so a
+            // membership in one granted circle can never combine with membership in an
+            // unrelated circle's group. The reads are batched but the conjunction is
+            // evaluated here, per circle, so no store implementation decides it.
+            const accessible = await grant.listAccessibleCircles(params.viewerDID, rule.allowedCircles);
+            if (accessible.length > 0) {
+                const memberGroupIDs = new Set(await grant.listMemberGroupIDs(params.viewerDID, Array.from(new Set(accessible.map((circle)=>circle.groupID)))));
+                if (accessible.some((circle)=>memberGroupIDs.has(circle.groupID))) {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+}

package/lib/sync/broadcast-queue.d.ts

@@ -30,7 +30,7 @@ export type BroadcastQueue = {
      * Enqueue a single mutation entry for the given target group, attributed to
      * `senderPeerDID`. May trigger an immediate flush if a threshold is reached.
      */
-    enqueue(targetGroupID: string, entry: MutationApplyEntry, senderPeerDID: string): void;
+    enqueue(targetGroupID: string, entry: MutationApplyEntry, senderPeerDID: string | undefined): void;
     /**
      * Cancel all pending timers and synchronously flush remaining entries
      * via `scheduleBroadcast`. Safe to call multiple times.
@@ -52,8 +52,7 @@ export type BroadcastQueue = {
  * Sender-DID consistency: the queue tracks the `senderPeerDID` of the first
  * entry in each batch. If a later enqueue arrives with a different sender
  * (defensive — in practice senderPeerDID is constant per peer), the prior
- * batch is flushed and a fresh batch starts. This preserves the invariant
- * that every flushed `mutation:apply` message carries a single coherent
- * `senderPeerDID`.
+ * batch is flushed and a fresh batch starts, so every flushed message carries
+ * a single coherent `senderPeerDID`.
  */
 export declare function createBroadcastQueue(params: BroadcastQueueParams): BroadcastQueue;

package/lib/sync/broadcast-queue.js

@@ -1 +1,182 @@
-export const DEFAULT_BROADCAST_BATCH_CONFIG={enabled:!0,windowMs:500,maxCount:20,maxBytes:65536};export function createBroadcastQueue(e){let{config:t,scheduleBroadcast:r,logger:n}=e,l=new Map,o=!1;function u(e){let t=l.get(e);if(null==t||0===t.entries.length)return;null!=t.timer&&(clearTimeout(t.timer),t.timer=null);let o=t.entries,u=t.senderPeerDID;l.delete(e);try{r(e,{type:"mutation:apply",entries:o,senderPeerDID:u})}catch(t){n?.warn("broadcast-queue flush failed",{targetGroupID:e,entryCount:o.length,error:String(t)})}}return{enqueue:function(e,i,a){if(o)return void n?.warn("broadcast-queue enqueue after dispose, dropping entry",{targetGroupID:e,docID:i.docID});if(!t.enabled){try{r(e,{type:"mutation:apply",entries:[i],senderPeerDID:a})}catch(t){n?.warn("broadcast-queue pass-through scheduleBroadcast failed",{targetGroupID:e,docID:i.docID,error:String(t)})}return}let s=JSON.stringify(i).length;if(s>=t.maxBytes){let t=l.get(e);null!=t&&t.entries.length>0&&u(e);try{r(e,{type:"mutation:apply",entries:[i],senderPeerDID:a})}catch(t){n?.warn("broadcast-queue oversize-entry scheduleBroadcast failed",{targetGroupID:e,docID:i.docID,error:String(t)})}return}let d=l.get(e);if(null!=d&&d.senderPeerDID!==a&&(u(e),d=void 0),null!=d&&d.bytes+s>t.maxBytes&&(u(e),d=void 0),null==d){l.set(e,{entries:[i],bytes:s,senderPeerDID:a,timer:null});let r=l.get(e);return null!=r&&r.entries.length>=t.maxCount?void u(e):void!function(e){let r=l.get(e);if(null==r||null!=r.timer)return;let n=setTimeout(()=>{u(e)},t.windowMs),o=n.unref;"function"==typeof o&&o.call(n),r.timer=n}(e)}d.entries.push(i),d.bytes+=s,d.entries.length>=t.maxCount&&u(e)},dispose:function(){if(!o)for(let e of(o=!0,Array.from(l.keys())))u(e)}}}
+export const DEFAULT_BROADCAST_BATCH_CONFIG = {
+    enabled: true,
+    windowMs: 500,
+    maxCount: 20,
+    maxBytes: 64 * 1024
+};
+/**
+ * Build a per-target-group batch queue around a `scheduleBroadcast` hook.
+ *
+ * The `mutation:apply` broadcast variant carries `entries: Array<...>` —
+ * a queue flush emits ONE broadcast with the accumulated entries, not one
+ * broadcast per entry.
+ *
+ * Each enqueued entry's wire size is approximated via `JSON.stringify(entry).length`.
+ * The accumulated byte budget tracks per-batch payload size only — message
+ * envelope (`type`, `senderPeerDID`) overhead is intentionally ignored to keep
+ * accounting cheap and predictable.
+ *
+ * Sender-DID consistency: the queue tracks the `senderPeerDID` of the first
+ * entry in each batch. If a later enqueue arrives with a different sender
+ * (defensive — in practice senderPeerDID is constant per peer), the prior
+ * batch is flushed and a fresh batch starts, so every flushed message carries
+ * a single coherent `senderPeerDID`.
+ */ export function createBroadcastQueue(params) {
+    const { config, scheduleBroadcast, logger } = params;
+    const queues = new Map();
+    let disposed = false;
+    function clearTimer(state) {
+        if (state.timer != null) {
+            clearTimeout(state.timer);
+            state.timer = null;
+        }
+    }
+    function flush(targetGroupID) {
+        const state = queues.get(targetGroupID);
+        if (state == null || state.entries.length === 0) {
+            return;
+        }
+        clearTimer(state);
+        const entries = state.entries;
+        const senderPeerDID = state.senderPeerDID;
+        queues.delete(targetGroupID);
+        try {
+            scheduleBroadcast(targetGroupID, {
+                type: 'mutation:apply',
+                entries,
+                senderPeerDID
+            });
+        } catch (error) {
+            logger?.warn('broadcast-queue flush failed', {
+                targetGroupID,
+                entryCount: entries.length,
+                error: String(error)
+            });
+        }
+    }
+    function startTimer(targetGroupID) {
+        const state = queues.get(targetGroupID);
+        if (state == null || state.timer != null) {
+            return;
+        }
+        const timer = setTimeout(()=>{
+            flush(targetGroupID);
+        }, config.windowMs);
+        // Don't hold the process open just for a pending broadcast batch.
+        // Node returns a Timeout object with `unref()`; browsers return a number.
+        const maybeUnref = timer.unref;
+        if (typeof maybeUnref === 'function') {
+            maybeUnref.call(timer);
+        }
+        state.timer = timer;
+    }
+    function appendToFreshBatch(targetGroupID, entry, entryBytes, senderPeerDID) {
+        const state = {
+            entries: [
+                entry
+            ],
+            bytes: entryBytes,
+            senderPeerDID,
+            timer: null
+        };
+        queues.set(targetGroupID, state);
+    }
+    function enqueue(targetGroupID, entry, senderPeerDID) {
+        if (disposed) {
+            logger?.warn('broadcast-queue enqueue after dispose, dropping entry', {
+                targetGroupID,
+                docID: entry.docID
+            });
+            return;
+        }
+        // Pass-through mode: emit each entry as its own single-entry broadcast.
+        if (!config.enabled) {
+            try {
+                scheduleBroadcast(targetGroupID, {
+                    type: 'mutation:apply',
+                    entries: [
+                        entry
+                    ],
+                    senderPeerDID
+                });
+            } catch (error) {
+                logger?.warn('broadcast-queue pass-through scheduleBroadcast failed', {
+                    targetGroupID,
+                    docID: entry.docID,
+                    error: String(error)
+                });
+            }
+            return;
+        }
+        const entryBytes = JSON.stringify(entry).length;
+        // Oversize lone entry: skip the queue and ship as its own batch immediately.
+        // If a batch is already queued for this group, flush it first to preserve
+        // ordering (older entries ship before this lone giant).
+        if (entryBytes >= config.maxBytes) {
+            const existing = queues.get(targetGroupID);
+            if (existing != null && existing.entries.length > 0) {
+                flush(targetGroupID);
+            }
+            try {
+                scheduleBroadcast(targetGroupID, {
+                    type: 'mutation:apply',
+                    entries: [
+                        entry
+                    ],
+                    senderPeerDID
+                });
+            } catch (error) {
+                logger?.warn('broadcast-queue oversize-entry scheduleBroadcast failed', {
+                    targetGroupID,
+                    docID: entry.docID,
+                    error: String(error)
+                });
+            }
+            return;
+        }
+        let state = queues.get(targetGroupID);
+        // Sender mismatch: flush prior batch, start fresh.
+        if (state != null && state.senderPeerDID !== senderPeerDID) {
+            flush(targetGroupID);
+            state = undefined;
+        }
+        // Byte threshold: would adding this entry overflow? Flush first, start new batch.
+        if (state != null && state.bytes + entryBytes > config.maxBytes) {
+            flush(targetGroupID);
+            state = undefined;
+        }
+        if (state == null) {
+            appendToFreshBatch(targetGroupID, entry, entryBytes, senderPeerDID);
+            // Start the window timer for this new batch — only if we won't flush
+            // synchronously below for count reasons.
+            const fresh = queues.get(targetGroupID);
+            if (fresh != null && fresh.entries.length >= config.maxCount) {
+                flush(targetGroupID);
+                return;
+            }
+            startTimer(targetGroupID);
+            return;
+        }
+        state.entries.push(entry);
+        state.bytes += entryBytes;
+        // Count threshold: flush synchronously without waiting for the timer.
+        if (state.entries.length >= config.maxCount) {
+            flush(targetGroupID);
+        }
+    }
+    function dispose() {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        // Snapshot keys — flush mutates the map.
+        const targets = Array.from(queues.keys());
+        for (const targetGroupID of targets){
+            flush(targetGroupID);
+        }
+    }
+    return {
+        enqueue,
+        dispose
+    };
+}