@kubun/plugin-p2p 0.12.0 → 0.13.0

package/lib/context/group.js

@@ -815,6 +815,9 @@ export function createGroupContext(ctx, deps) {
                 accessDefaults: invite.accessDefaults,
                 catalogs: invite.catalogs,
                 hlc: deps.hlc,
+                ...deps.maxDriftMS != null ? {
+                    maxDriftMS: deps.maxDriftMS
+                } : {},
                 getGroupAnchor: (gid)=>deps.registry.readHandle(gid, (handle)=>readGroupAnchor(handle), {
                         stores: deps.stores
                     }),

package/lib/context/join.js

@@ -94,6 +94,9 @@ export function createJoinContext(ctx, deps) {
                 accessDefaults: invite.accessDefaults,
                 catalogs: invite.catalogs,
                 hlc: deps.hlc,
+                ...deps.maxDriftMS != null ? {
+                    maxDriftMS: deps.maxDriftMS
+                } : {},
                 getGroupAnchor: (gid)=>deps.registry.readHandle(gid, (handle)=>readGroupAnchor(handle), {
                         stores: deps.stores
                     }),

package/lib/context/peer.js

@@ -1,13 +1,14 @@
 import { Client } from '@enkaku/client';
 import { ClientTransport } from '@enkaku/http-fetch';
 import { normalizeDID } from '@kokuin/token';
+import { createDeviceAuthority } from '@kubun/credential';
 import { getGraphStore } from '@kubun/store-graph';
 import { getP2PStore } from '@kubun/store-p2p';
 import { readGroupAnchor } from '@kumiai/mls';
 import { blake3 } from '@noble/hashes/blake3.js';
 import { GraphQLError } from 'graphql';
+import { applyAccessDefaultSetFrame } from '../groups/access-default-apply.js';
 import { signAccessDefaultSet } from '../groups/access-default-token.js';
-import { applyAccessDefaultSetFrame } from '../groups/broadcast.js';
 import { foldGroupSettings } from '../groups/circle-projection.js';
 import { awaitControlRequestSettled } from '../groups/control-request.js';
 import { resolveJoinRequestDID } from '../groups/join-request-identity.js';
@@ -238,8 +239,12 @@ function isPeerInfoResponse(value) {
     if (normalizeDID(credentialDID) !== normalizeDID(callerDID)) {
         throw new Error('group/invite: join request DID does not match the authenticated caller');
     }
+    // Out-of-band peer-handler context: it acts as the local device, so a
+    // self-scoped device authority is the correct credential authority (the group
+    // ops here never consult it).
     const groupCtx = createGroupContext({
-        viewerDID: deps.identity.id
+        viewerDID: deps.identity.id,
+        credentialAuthority: createDeviceAuthority(deps.identity.id)
     }, deps);
     // A caller already in the MLS roster is a joiner that lost its local group
     // state — re-adding it directly would fail (MLS rejects an Add for a current

package/lib/context/sync.js

@@ -1,6 +1,8 @@
+import { CREDENTIAL_STORE, getCredentialStore } from '@kubun/store-credential';
 import { getGraphStore } from '@kubun/store-graph';
 import { getP2PStore } from '@kubun/store-p2p';
-import { rankSyncPeers } from '../groups/peer-selection.js';
+import { applyCredentialReconcile } from '../groups/credential-apply.js';
+import { answersCredentialSync, rankSyncPeers } from '../groups/peer-selection.js';
 import { resolveCatalogSyncScopes } from '../sync/catalog-scope.js';
 const NO_OP = {
     messagesReceived: 0,
@@ -75,13 +77,56 @@ export function createSyncContext(_ctx, deps) {
    * Route only. Which documents a session serves is decided per document at the
    * far end, so preferring a tunnel changes who can be dialled and nothing about
    * what comes back.
-   */ const resolveRoute = async (groupID, peerDID)=>{
+   */ const resolveAnnouncement = async (groupID, peerDID)=>{
         const p2pStore = await getP2PStore(deps.stores);
-        const announcement = await p2pStore.getPeerAnnouncement({
+        return await p2pStore.getPeerAnnouncement({
             groupID,
             peerDID
         });
-        return announcement == null ? undefined : `tunnel://${groupID}/${peerDID}`;
+    };
+    /**
+   * The credential subject ids this device holds, to ride a doc sync as the
+   * catch-up's `held` — or `undefined` to skip the lane entirely. Gated twice: the
+   * peer must advertise `credential-sync` (its opt-out is the absence of the
+   * capability), and this device must have a credential store to apply into.
+   */ const credentialHeld = async (announcement)=>{
+        if (announcement == null || !answersCredentialSync(announcement) || !deps.stores.hasStore(CREDENTIAL_STORE)) {
+            return undefined;
+        }
+        return await (await getCredentialStore(deps.stores)).listHeldSubjects();
+    };
+    /**
+   * Materialise the credential catch-up the doc session pulled back. Independent
+   * of the doc lane: a failure here never fails the catch-up, so it is logged and
+   * swallowed. The server's scoping is not trusted — `applyCredentialReconcile`
+   * re-verifies every row.
+   */ const applyReconcile = async (peerDID, reconcile)=>{
+        if (reconcile == null) {
+            return;
+        }
+        try {
+            const store = await getCredentialStore(deps.stores);
+            const result = await applyCredentialReconcile({
+                store,
+                selfDID: deps.identity.id,
+                bundles: reconcile.bundles,
+                tombstones: reconcile.tombstones,
+                hlc: deps.hlc,
+                ...deps.maxDriftMS == null ? {} : {
+                    maxDriftMS: deps.maxDriftMS
+                },
+                logger: deps.logger
+            });
+            deps.logger.debug('credential reconcile piggybacked on catch-up', {
+                peerDID,
+                ...result
+            });
+        } catch (error) {
+            deps.logger.warn('credential reconcile apply failed; doc catch-up unaffected', {
+                peerDID,
+                error
+            });
+        }
     };
     // Bidirectional: each device pushes the docs it owns (its own owner-scope
     // authorizes) and pulls what it may. Reaching the peer needs no prior
@@ -95,7 +140,12 @@ export function createSyncContext(_ctx, deps) {
         if (scopes.length === 0) {
             return NO_OP;
         }
-        const endpoint = await resolveRoute(groupID, peerDID);
+        const announcement = await resolveAnnouncement(groupID, peerDID);
+        const endpoint = announcement == null ? undefined : `tunnel://${groupID}/${peerDID}`;
+        // Decided before the sync so it can ride the same session: the credential
+        // lane must reuse the doc session, since a second dial to the same peer hangs
+        // on a responder still locked to the first.
+        const held = await credentialHeld(announcement);
         const result = await deps.syncManager.merkleSyncWithPeer({
             peerDID,
             scopes,
@@ -104,8 +154,16 @@ export function createSyncContext(_ctx, deps) {
             direction: 'both',
             ...endpoint == null ? {} : {
                 endpoint
+            },
+            ...held == null ? {} : {
+                reconcileCredentialsHeld: held
             }
         });
+        // Materialise whatever the session pulled back. Independent of the doc lane:
+        // its failure is swallowed inside `applyReconcile`.
+        if (held != null) {
+            await applyReconcile(peerDID, result.credentialReconcile);
+        }
         return {
             messagesReceived: result.messagesReceived,
             messagesSent: result.messagesSent,

package/lib/context/types.d.ts

@@ -6,7 +6,7 @@ import type { Logger } from '@kubun/logger';
 import type { Circle } from '@kubun/store-p2p';
 import type { LaneResult, PendingCommit } from '@kumiai/rpc';
 import type { Runtime } from '@sozai/runtime';
-import type { GroupBroadcastMessage } from '../groups/broadcast.js';
+import type { GroupBroadcastMessage } from '../groups/broadcast-message.js';
 import type { P2PEventEmitter } from '../groups/events.js';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
 import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
@@ -34,6 +34,12 @@ export type ContextDeps = {
     deviceStores: StoreProvider;
     adapter: Adapter;
     hlc: HLC;
+    /**
+     * How far into the future a peer's stamp may sit before this device refuses to
+     * merge it into {@link hlc}. The engine's bound, carried so the control-ledger
+     * adoption a join performs uses the configured value rather than the default.
+     */
+    maxDriftMS?: number;
     emitter: P2PEventEmitter;
     runtime: Runtime;
     autoAcceptPeers?: Array<string>;
@@ -102,4 +108,11 @@ export declare function toCircleData(row: Circle): CircleData;
  * into an object. SerializedMLSGroupState expects a JSON string.
  */
 export declare function normalizeCredential(value: unknown): string;
+/**
+ * The DID a signed peer-procedure payload was issued by, having checked the
+ * caller is not forging one: a subject must equal its issuer, or the caller is
+ * claiming an identity it did not sign as. Shared by every direct-request serve
+ * handler (blob, controller) that gates on the caller.
+ */
+export declare function verifiedCaller(payload: unknown): string;
 export declare function checkPeerAccess(viewerDID: string, identityID: string, autoAcceptPeers?: Array<string>): void;

package/lib/context/types.js

@@ -29,6 +29,18 @@ export function toISO(timestamp) {
     if (typeof value === 'string') return value;
     return JSON.stringify(value);
 }
+/**
+ * The DID a signed peer-procedure payload was issued by, having checked the
+ * caller is not forging one: a subject must equal its issuer, or the caller is
+ * claiming an identity it did not sign as. Shared by every direct-request serve
+ * handler (blob, controller) that gates on the caller.
+ */ export function verifiedCaller(payload) {
+    const signed = payload;
+    if (signed.sub != null && signed.sub !== signed.iss) {
+        throw new Error('Peer access denied: signed payload subject does not match issuer');
+    }
+    return signed.iss;
+}
 export function checkPeerAccess(viewerDID, identityID, autoAcceptPeers) {
     // The device operator is always allowed to run its own peer ops. The
     // allow-list gates OTHER DIDs (remote callers of the dance handlers); it must

package/lib/groups/access-default-apply.d.ts

@@ -0,0 +1,42 @@
+import type { Logger } from '@kubun/logger';
+import type { GraphStoreAPI } from '@kubun/store-graph';
+import { type AccessDefaultRule } from './access-default-token.js';
+/**
+ * Sender-bound, LWW apply of a signed `access-default:set` frame. Shared by the
+ * live broadcast path and the invite-seeding path so both authenticate through
+ * the same token verification. The authoritative fields come from the verified
+ * token; the plaintext `ownerDID` is used only for the sender-bound equality
+ * check. Returns whether a row was written.
+ */
+export type AccessDefaultSetFrame = {
+    ownerDID: string;
+    modelID: string;
+    permissionType: 'read' | 'write';
+    rule: AccessDefaultRule;
+    hlc: string;
+    auth: string;
+};
+export type ApplyAccessDefaultSetFrameParams = {
+    graphStore: GraphStoreAPI;
+    frame: AccessDefaultSetFrame;
+    logger?: Logger;
+    /** Scopes the log lines to the group the frame arrived on, when it arrived on one. */
+    groupID?: string;
+};
+export declare function applyAccessDefaultSetFrame(params: ApplyAccessDefaultSetFrameParams): Promise<boolean>;
+/**
+ * Apply one signed access-default set token, with no surrounding frame.
+ *
+ * What a catch-up reply carries: a token and nothing else, so there is no
+ * plaintext mirror to cross-check and none is needed — the frame's mirror
+ * fields exist for a receiver rebuilding what was signed, and the authoritative
+ * values were always the claim's. Every other rule is the live path's: the owner
+ * is the authenticated issuer, and the write happens only if strictly newer than
+ * what is stored.
+ */
+export declare function applyAccessDefaultSetToken(params: {
+    graphStore: GraphStoreAPI;
+    token: string;
+    logger?: Logger;
+    groupID: string;
+}): Promise<boolean>;

package/lib/groups/access-default-apply.js

@@ -0,0 +1,75 @@
+import { normalizeDID } from '@kokuin/token';
+import { verifyAccessDefault } from './access-default-token.js';
+export async function applyAccessDefaultSetFrame(params) {
+    const { graphStore, frame, logger, groupID } = params;
+    // Authenticate via the signed token: a forged or unsigned token verifies to
+    // null and is dropped. Every authoritative field comes from the verified
+    // payload, never the surrounding plaintext frame.
+    const verified = await verifyAccessDefault(frame.auth);
+    if (verified == null || !isSetClaim(verified)) {
+        logger?.warn('access-default:set dropped: token verification failed', {
+            groupID
+        });
+        return false;
+    }
+    // Sender-bound: a member states only its OWN sharing policy. The row owner is
+    // the authenticated issuer; a frame claiming a foreign owner is dropped. The
+    // issuer is already normalized, so the plaintext owner must be too — an
+    // equivalent DID in another form is the same principal.
+    if (normalizeDID(frame.ownerDID) !== verified.issuer) {
+        logger?.warn('access-default:set dropped: owner is not the authenticated author', {
+            groupID
+        });
+        return false;
+    }
+    return await applyVerifiedAccessDefaultSet(graphStore, verified);
+}
+/**
+ * Apply one signed access-default set token, with no surrounding frame.
+ *
+ * What a catch-up reply carries: a token and nothing else, so there is no
+ * plaintext mirror to cross-check and none is needed — the frame's mirror
+ * fields exist for a receiver rebuilding what was signed, and the authoritative
+ * values were always the claim's. Every other rule is the live path's: the owner
+ * is the authenticated issuer, and the write happens only if strictly newer than
+ * what is stored.
+ */ export async function applyAccessDefaultSetToken(params) {
+    const verified = await verifyAccessDefault(params.token);
+    if (verified == null || !isSetClaim(verified)) {
+        params.logger?.warn('access-default catch-up entry dropped: verification failed', {
+            groupID: params.groupID
+        });
+        return false;
+    }
+    return await applyVerifiedAccessDefaultSet(params.graphStore, verified);
+}
+/**
+ * A verified access-default that states a rule rather than withdrawing one.
+ * Written as a guard because the union discriminates on a NESTED field, which a
+ * `verified.claim.op !== 'set'` check does not narrow the parent by.
+ */ function isSetClaim(verified) {
+    return verified.claim.op === 'set';
+}
+async function applyVerifiedAccessDefaultSet(graphStore, verified) {
+    const claim = verified.claim;
+    // LWW: apply only when strictly newer than the stored rule's anchor. An
+    // unstamped stored rule (null hlc) is treated as oldest, so any stamped
+    // incoming rule wins.
+    const storedHLC = await graphStore.getUserModelAccessDefaultHLC(verified.issuer, claim.modelID, claim.permissionType);
+    if (storedHLC != null && claim.hlc <= storedHLC) {
+        return false;
+    }
+    await graphStore.setUserModelAccessDefault({
+        ownerDID: verified.issuer,
+        modelID: claim.modelID,
+        permissionType: claim.permissionType,
+        // Narrowed by `isRule` at verification, which refuses any level outside the
+        // three the read predicate is written for.
+        accessLevel: claim.rule.level,
+        allowedDIDs: claim.rule.allowedDIDs,
+        allowedCircles: claim.rule.allowedCircles,
+        allowedGroups: claim.rule.allowedGroups,
+        hlc: claim.hlc
+    });
+    return true;
+}

package/lib/groups/broadcast-codec.d.ts

@@ -1,3 +1,3 @@
-import type { GroupBroadcastMessage } from './broadcast.js';
+import type { GroupBroadcastMessage } from './broadcast-message.js';
 export declare function serializeBroadcast(message: GroupBroadcastMessage): Uint8Array;
 export declare function deserializeBroadcast(bytes: Uint8Array): GroupBroadcastMessage;

package/lib/groups/broadcast-message.d.ts

@@ -0,0 +1,240 @@
+import type { CatalogRecord } from '@kubun/protocol';
+import type { CredentialFactorDescriptor } from '@kubun/store-credential';
+import type { PeerAvailability, PeerCapability } from './group-protocols.js';
+export type MutationApplyEntry = {
+    mutationJWT: string;
+    docID: string;
+    /** HLC string identifying this mutation's version. */
+    version: string;
+    modelID: string;
+};
+/**
+ * Optional signed token over a control operation. Its issuer (`iss`) is the
+ * authenticated author; receivers verify it and authorize that author as a
+ * group admin, dropping the operation when the token is absent or invalid. The
+ * signed payload is the whole message minus this field, so the signature covers
+ * every operation field, not just the author.
+ */
+export type ControlAuth = string;
+/**
+ * The one wrapping a grant addresses, as it rides the wire.
+ *
+ * Binary fields are base64url rather than `Uint8Array`: every lane payload is
+ * JSON-schema'd and JSON-encoded, so bytes not encoded here would not survive
+ * the trip. `factors` is already JSON-safe — a descriptor holds base64 public
+ * material, never raw bytes and never a secret.
+ */
+export type CredentialKeyGrantWrapping = {
+    wrappingID: string;
+    /** ORDERED, and covered by the wrapping's AAD — a reordered copy will not open. */
+    factors: Array<CredentialFactorDescriptor>;
+    iv: string;
+    wrappedKey: string;
+    /**
+     * Un-normalized, as the stored column is: this is a key-resolution input, and
+     * a `did:peer:4` short form carries no document. Compare it only through
+     * `normalizeDID`.
+     */
+    recipientDID: string;
+    /**
+     * The granter's signed op for this row, verbatim. The receiver stores these
+     * bytes rather than signing its own: the merkle leaf hashes the op, so a
+     * receiver that minted one would compute a different leaf for the same
+     * logical row and the two devices would never converge.
+     */
+    op: string;
+};
+/** One entry ciphertext, copied verbatim into a grant. */
+export type CredentialKeyGrantEntry = {
+    entryID: string;
+    iv: string;
+    ciphertext: string;
+    hlc: string;
+    /** The granter's signed op — see {@link CredentialKeyGrantWrapping.op}. */
+    op: string;
+};
+/**
+ * The row bytes of one credential key addressed to one recipient, minus the
+ * grant's single-frame `auth` envelope.
+ *
+ * The shape a `credential:key-grant` carries under `type`/`auth`, reused as the
+ * catch-up unit of the credential reconcile lane: the serving device already
+ * holds the recipient's row bytes, so a missed grant is pulled as this same
+ * bundle. One shape, one apply, for push and pull. Each row still
+ * self-authenticates through its own `op`, so no frame-level signature is needed
+ * — the reconcile response is not one signed frame.
+ */
+export type CredentialKeyBundle = {
+    keyID: string;
+    keyVersion: number;
+    suite: number;
+    /** A mirror the receiver ignores in favour of each op's verified issuer. */
+    ownerDID: string;
+    keyOp: string;
+    keyBranches: Array<string>;
+    wrapping: CredentialKeyGrantWrapping;
+    entries: Array<CredentialKeyGrantEntry>;
+};
+export type GroupBroadcastMessage = {
+    type: 'catalog:create';
+    catalog: CatalogRecord;
+    auth?: ControlAuth;
+} | {
+    type: 'catalog:update';
+    catalogID: string;
+    update: {
+        name?: string;
+        description?: string;
+        filterCriteria?: CatalogRecord['filterCriteria'];
+        hlc: string;
+    };
+    auth?: ControlAuth;
+} | {
+    type: 'catalog:delete';
+    catalogID: string;
+    hlc: string;
+    auth?: ControlAuth;
+} | {
+    /**
+     * A member states its own model access-default so co-members can evaluate
+     * the owner's documents. `auth` is a signed token whose issuer is the
+     * owner; the receiver derives every authoritative field from that verified
+     * token and applies the rule ONLY when `ownerDID` equals the issuer (a
+     * member states its own policy, never another's). LWW by `hlc`.
+     */
+    type: 'access-default:set';
+    modelID: string;
+    permissionType: 'read' | 'write';
+    rule: {
+        level: string;
+        allowedDIDs: Array<string> | null;
+        allowedCircles: Array<string> | null;
+        allowedGroups: Array<string> | null;
+    };
+    ownerDID: string;
+    hlc: string;
+    auth: ControlAuth;
+} | {
+    /**
+     * A member removes its own model access-default(s). Same sender-bound and
+     * LWW rules as `access-default:set`: applied only when `ownerDID` equals
+     * the verified `auth` issuer and the removal `hlc` is newer than the
+     * stored rule's.
+     */
+    type: 'access-default:remove';
+    modelID: string;
+    permissionTypes: Array<'read' | 'write'>;
+    ownerDID: string;
+    hlc: string;
+    auth: ControlAuth;
+} | {
+    /**
+     * Distributes a minted `document/write` capability token to group
+     * co-members. The recipient verifies the token's signature and stores a
+     * held row only when the token's audience (`aud`) is the receiving
+     * device, so the engine's auto-attach can reuse it on later mutations.
+     */
+    type: 'delegation:share';
+    /** Stringified capability JWT carrying the `document/write` grant. */
+    token: string;
+    /** Group whose broadcast channel carries this grant. */
+    groupID: string;
+    /** HLC stamped by the grantor; mirrors the grantor-side issued row. */
+    hlc: string;
+} | {
+    /**
+     * Distributes a signed revocation record for a previously minted
+     * `document/write` capability. The recipient verifies the token's
+     * signature and stores the revocation; verification against the
+     * referenced cap's `iss` flips `verified_at` once the cap is known.
+     * Revocation is binary and reactive — once verified locally, any
+     * subsequent mutation under the revoked `jti` is denied regardless
+     * of `mutation.atTime`.
+     */
+    type: 'delegation:revoke';
+    /** Stringified signed revocation JWT carrying `{ jti, iss, rev, iat }`. */
+    token: string;
+    /** Group whose broadcast channel carries this revocation. */
+    groupID: string;
+    /** HLC stamped by the revoker; mirrors the revoker-side stored row. */
+    hlc: string;
+} | {
+    /**
+     * A member announces a voluntary leave. MLS forbids self-removal, so this
+     * is an advisory notification (not an authoritative removal): receivers
+     * surface a `groupLeaveRequested` event for an admin to act on by issuing
+     * a real `removeMember`. Deliberately does NOT tombstone — a forged
+     * leave-request must not be able to evict an arbitrary member.
+     */
+    type: 'group:leaveRequest';
+    groupID: string;
+    memberDID: string;
+    hlc: string;
+} | {
+    type: 'mutation:apply';
+    entries: Array<MutationApplyEntry>;
+    /**
+     * DID of the peer this broadcast arrived FROM — used for loopback drop.
+     * For a forwarded mutation that is the forwarding peer, not the author, so
+     * it is never an authorization input: each entry carries its own signed
+     * `mutationJWT`, verified independently.
+     *
+     * `undefined` when the frame opened at a leaf that could not be named. The
+     * entries still apply — see the loopback guard.
+     */
+    senderPeerDID: string | undefined;
+} | {
+    /**
+     * Hands one co-member what it needs to open a credential key: the key's
+     * public record, the single wrapping addressed to that member, and every
+     * entry ciphertext at that version. No plaintext, and no key material
+     * outside the wrapping.
+     *
+     * Group-wide, because confidentiality is content-level — only the
+     * addressed DID's agreement key opens the wrapping. A co-member that is
+     * not the recipient receives the frame and applies nothing, so what it
+     * retains is the frame, never a row.
+     */
+    type: 'credential:key-grant';
+    keyID: string;
+    keyVersion: number;
+    suite: number;
+    /**
+     * Who administers the key, as the granter's own row records it. A MIRROR,
+     * not an input: the receiver writes `owner_did` from the verified `auth`
+     * issuer, so this field is what the frame claims and never what is stored.
+     */
+    ownerDID: string;
+    /**
+     * The granter's signed op for the key row. Top-level because the key row
+     * itself is inline on this frame and has nowhere else to hang.
+     */
+    keyOp: string;
+    /** The introducing key-op(s) ride inline so every branch label can be authenticated. */
+    keyBranches: Array<string>;
+    wrapping: CredentialKeyGrantWrapping;
+    entries: Array<CredentialKeyGrantEntry>;
+    /**
+     * Signs identifiers and digests, not the ciphertext — see
+     * {@link CredentialKeyGrantClaim}. The receiver recomputes both digests
+     * from the plaintext frame before writing anything.
+     */
+    auth: ControlAuth;
+} | {
+    /**
+     * A device advertises itself to its co-members. Everything here except
+     * `announcerDID` came off the wire; `announcerDID` did NOT — it is the
+     * MLS-authenticated sender the handler read from `message.payload.iss`,
+     * because the announce body carries no DID field at all.
+     *
+     * `undefined` when the frame opened at a leaf that could not be named, and
+     * the apply then writes nothing: a capability claim attributed to nobody is
+     * worse than no row.
+     */
+    type: 'peer:announce';
+    label: string;
+    availability: PeerAvailability;
+    capabilities: Array<PeerCapability>;
+    hlc: string;
+    announcerDID: string | undefined;
+};

package/lib/groups/broadcast-message.js

@@ -0,0 +1 @@
+export { };