@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/protocol.js

@@ -1 +1,519 @@
-export const syncProtocol={"sync/negotiate":{type:"request",param:{type:"object",properties:{scopes:{type:"array",items:{type:"object",properties:{modelID:{type:"string"},ownerDID:{type:"string"}},required:["modelID","ownerDID"],additionalProperties:!1},description:"Requested sync scopes as (model, owner) pairs"},delegationTokens:{type:"array",items:{type:"string"},description:"JWT delegation tokens for authorization"},catalogIDs:{type:"array",items:{type:"string"},description:"Catalog IDs to resolve sync scope from criteria"},knownModelIDs:{type:"array",items:{type:"string"},description:"Model IDs the requester already has — used to identify missing clusters"},direction:{type:"string",enum:["push","pull","both"]}},required:["delegationTokens"],additionalProperties:!1},result:{type:"object",properties:{direction:{type:"string",enum:["push","pull","both"]},acceptedScopes:{type:"array",items:{type:"object",properties:{modelID:{type:"string"},ownerDID:{type:"string"}},required:["modelID","ownerDID"],additionalProperties:!1}},excludedDocumentIDs:{type:"array",items:{type:"string"}},missingClusters:{type:"object",description:"Cluster definitions for models the requester does not have yet",additionalProperties:!0}},required:["acceptedScopes","excludedDocumentIDs"],additionalProperties:!1}},"sync/merkle-sync":{type:"channel",param:{type:"object",properties:{scopes:{type:"array",items:{type:"object",properties:{modelID:{type:"string"},ownerDID:{type:"string"}},required:["modelID","ownerDID"],additionalProperties:!1}},excludedDocumentIDs:{type:"array",items:{type:"string"}},tree:{type:"object",description:"Merkle tree bucket hashes from requester",additionalProperties:{type:"string"}},direction:{type:"string",enum:["push","pull","both"]},delegationTokens:{type:"array",items:{type:"string"},description:"Delegation JWTs authorizing the caller for non-owned scopes"}},required:["scopes","excludedDocumentIDs","tree","direction"],additionalProperties:!1},send:{type:"object",properties:{type:{type:"string",enum:["mutations","complete"]},mutationJWTs:{type:"array",items:{type:"string"},description:"Signed mutation JWTs for divergent time buckets"}},required:["type"],additionalProperties:!1},receive:{type:"object",properties:{type:{type:"string",enum:["tree","mutations","complete"]},tree:{type:"object",description:"Responder merkle tree bucket hashes",additionalProperties:{type:"string"}},mutationJWTs:{type:"array",items:{type:"string"},description:"Signed mutation JWTs for divergent time buckets"}},required:["type"],additionalProperties:!1},result:{type:"object",properties:{success:{type:"boolean"},divergentBuckets:{type:"number"},mutationsSent:{type:"number"},mutationsReceived:{type:"number"}},required:["success","divergentBuckets","mutationsSent","mutationsReceived"],additionalProperties:!1}}};
+export const syncProtocol = {
+    'sync/negotiate': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                scopes: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            modelID: {
+                                type: 'string'
+                            },
+                            ownerDID: {
+                                type: 'string'
+                            }
+                        },
+                        required: [
+                            'modelID',
+                            'ownerDID'
+                        ],
+                        additionalProperties: false
+                    },
+                    description: 'Requested sync scopes as (model, owner) pairs'
+                },
+                delegationTokens: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'JWT delegation tokens for authorization'
+                },
+                catalogIDs: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'Catalog IDs to resolve sync scope from criteria'
+                },
+                knownModelIDs: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'Model IDs the requester already has — used to identify missing clusters'
+                },
+                direction: {
+                    type: 'string',
+                    enum: [
+                        'push',
+                        'pull',
+                        'both'
+                    ]
+                }
+            },
+            required: [
+                'delegationTokens'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                direction: {
+                    type: 'string',
+                    enum: [
+                        'push',
+                        'pull',
+                        'both'
+                    ]
+                },
+                acceptedScopes: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            modelID: {
+                                type: 'string'
+                            },
+                            ownerDID: {
+                                type: 'string'
+                            }
+                        },
+                        required: [
+                            'modelID',
+                            'ownerDID'
+                        ],
+                        additionalProperties: false
+                    }
+                },
+                excludedDocumentIDs: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    }
+                },
+                missingClusters: {
+                    type: 'object',
+                    description: 'Cluster definitions for models the requester does not have yet',
+                    additionalProperties: true
+                }
+            },
+            required: [
+                'acceptedScopes',
+                'excludedDocumentIDs'
+            ],
+            additionalProperties: false
+        }
+    },
+    'sync/merkle-sync': {
+        type: 'channel',
+        param: {
+            type: 'object',
+            properties: {
+                scopes: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            modelID: {
+                                type: 'string'
+                            },
+                            ownerDID: {
+                                type: 'string'
+                            }
+                        },
+                        required: [
+                            'modelID',
+                            'ownerDID'
+                        ],
+                        additionalProperties: false
+                    }
+                },
+                excludedDocumentIDs: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    }
+                },
+                tree: {
+                    type: 'object',
+                    description: 'Merkle tree bucket hashes from requester',
+                    additionalProperties: {
+                        type: 'string'
+                    }
+                },
+                direction: {
+                    type: 'string',
+                    enum: [
+                        'push',
+                        'pull',
+                        'both'
+                    ]
+                },
+                delegationTokens: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'Delegation JWTs authorizing the caller for non-owned scopes'
+                }
+            },
+            required: [
+                'scopes',
+                'excludedDocumentIDs',
+                'tree',
+                'direction'
+            ],
+            additionalProperties: false
+        },
+        send: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    enum: [
+                        'mutations',
+                        'complete'
+                    ]
+                },
+                mutationJWTs: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'Signed mutation JWTs for divergent time buckets'
+                }
+            },
+            required: [
+                'type'
+            ],
+            additionalProperties: false
+        },
+        receive: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    enum: [
+                        'tree',
+                        'mutations',
+                        'complete'
+                    ]
+                },
+                tree: {
+                    type: 'object',
+                    description: 'Responder merkle tree bucket hashes',
+                    additionalProperties: {
+                        type: 'string'
+                    }
+                },
+                mutationJWTs: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'Signed mutation JWTs for divergent time buckets'
+                }
+            },
+            required: [
+                'type'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                success: {
+                    type: 'boolean'
+                },
+                divergentBuckets: {
+                    type: 'number'
+                },
+                mutationsSent: {
+                    type: 'number'
+                },
+                mutationsReceived: {
+                    type: 'number'
+                }
+            },
+            required: [
+                'success',
+                'divergentBuckets',
+                'mutationsSent',
+                'mutationsReceived'
+            ],
+            additionalProperties: false
+        }
+    }
+};
+/**
+ * Peer protocol — the wire leg of the high-level peer ops. Served as a sibling
+ * to {@link syncProtocol} and advertised in `/info` under its own name so a
+ * connecting device can discover it independently of the data-sync protocol.
+ *
+ * The GraphQL mutations remain the app-facing surface; these procedures are the
+ * device-to-device leg the mutations dispatch to. `peer/groups` returns the
+ * serving device's DID and its groups for the `connectPeer` payload. The MLS
+ * dance procedures (`group/prepare-join`, `group/invite`, `group/complete-join`)
+ * extend this same protocol in later work.
+ */ export const peerProtocol = {
+    'peer/groups': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                did: {
+                    type: 'string',
+                    description: 'DID of the serving device'
+                },
+                groups: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string'
+                            },
+                            name: {
+                                type: 'string'
+                            }
+                        },
+                        required: [
+                            'id',
+                            'name'
+                        ],
+                        additionalProperties: false
+                    },
+                    description: "The serving device's groups (id + name)"
+                }
+            },
+            required: [
+                'did',
+                'groups'
+            ],
+            additionalProperties: false
+        }
+    },
+    // The peer leg of the MLS invite dance. `group/prepare-join` and
+    // `group/complete-join` wrap the SAME context ops as the `prepareJoinRequest`
+    // and `completeJoin` GraphQL mutations — the serving (joining) device mints
+    // its KeyPackage bundle, then processes the Welcome the caller returns. Gated
+    // exactly like `peer/groups` (forged-`sub` rejection + `checkPeerAccess`).
+    'group/prepare-join': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                joinRequest: {
+                    type: 'string',
+                    description: "The serving device's encoded join request (its KeyPackage)"
+                }
+            },
+            required: [
+                'joinRequest'
+            ],
+            additionalProperties: false
+        }
+    },
+    'group/complete-join': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                invitePayload: {
+                    type: 'string',
+                    description: 'The invite payload (Welcome + seeds) minted by the caller'
+                }
+            },
+            required: [
+                'invitePayload'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                groupID: {
+                    type: [
+                        'string',
+                        'null'
+                    ],
+                    description: 'The joined group ID, or null when the group row was not found'
+                }
+            },
+            required: [
+                'groupID'
+            ],
+            additionalProperties: false
+        }
+    },
+    // The inviter leg of the inbound dance (`joinPeerGroup`). The caller (joiner)
+    // sends the group it wants to join plus its KeyPackage bundle; the serving
+    // device (inviter) adds the caller to the group's share circles, runs the
+    // invite as ITSELF, and returns the Welcome + invite payload. Gated exactly
+    // like the other peer procedures (forged-`sub` rejection + `checkPeerAccess`
+    // against the inviter's `autoAcceptPeers`), so only a trusted caller can pull
+    // an invite from this device.
+    'group/invite': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                groupID: {
+                    type: 'string',
+                    description: 'The group the caller wants to join'
+                },
+                joinRequest: {
+                    type: 'string',
+                    description: "The caller's encoded join request (its KeyPackage)"
+                }
+            },
+            required: [
+                'groupID',
+                'joinRequest'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                invitePayload: {
+                    type: 'string',
+                    description: 'The invite payload (Welcome + seeds) for the caller to complete the join'
+                }
+            },
+            required: [
+                'invitePayload'
+            ],
+            additionalProperties: false
+        }
+    },
+    // The caller hands the serving device its own access-default rows over the
+    // held connection, so the serving device applies them without waiting on hub
+    // fan-out (which is dropped for a group with no live binding). The source is
+    // UNTRUSTED: access-default rows are sender-bound (owner must equal the
+    // verified token issuer AND the authenticated caller). Gated exactly like
+    // `group/invite` (forged-`sub` rejection + `checkPeerAccess`).
+    'group/push-control': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                groupID: {
+                    type: 'string',
+                    description: 'The group whose control state is being pushed'
+                },
+                accessDefaults: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            ownerDID: {
+                                type: 'string'
+                            },
+                            modelID: {
+                                type: 'string'
+                            },
+                            permissionType: {
+                                type: 'string',
+                                enum: [
+                                    'read',
+                                    'write'
+                                ]
+                            },
+                            rule: {
+                                type: 'object',
+                                properties: {
+                                    level: {
+                                        type: 'string'
+                                    },
+                                    allowedDIDs: {
+                                        type: [
+                                            'array',
+                                            'null'
+                                        ],
+                                        items: {
+                                            type: 'string'
+                                        }
+                                    },
+                                    allowedCircles: {
+                                        type: [
+                                            'array',
+                                            'null'
+                                        ],
+                                        items: {
+                                            type: 'string'
+                                        }
+                                    },
+                                    allowedGroups: {
+                                        type: [
+                                            'array',
+                                            'null'
+                                        ],
+                                        items: {
+                                            type: 'string'
+                                        }
+                                    }
+                                },
+                                required: [
+                                    'level',
+                                    'allowedDIDs',
+                                    'allowedCircles',
+                                    'allowedGroups'
+                                ],
+                                additionalProperties: false
+                            },
+                            hlc: {
+                                type: 'string'
+                            },
+                            auth: {
+                                type: 'string'
+                            }
+                        },
+                        required: [
+                            'ownerDID',
+                            'modelID',
+                            'permissionType',
+                            'rule',
+                            'hlc',
+                            'auth'
+                        ],
+                        additionalProperties: false
+                    },
+                    description: "The caller's own signed access-default rows (sender-bound on apply)"
+                }
+            },
+            required: [
+                'groupID',
+                'accessDefaults'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                accessDefaultsApplied: {
+                    type: 'number',
+                    description: 'Count of pushed access-default rows applied (sender-bound, LWW)'
+                }
+            },
+            required: [
+                'accessDefaultsApplied'
+            ],
+            additionalProperties: false
+        }
+    }
+};

package/lib/schema.d.ts

@@ -1,3 +1,5 @@
 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;
+import type { SyncManager } from './sync/sync-manager.js';
+export declare function createP2PSchemaExtension(emitter: P2PEventEmitter, syncManager: SyncManager, logger?: Logger): SchemaExtension;