@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/context/require-admin.d.ts

@@ -0,0 +1,57 @@
+import type { P2PStoreAPI } from '@kubun/store-p2p';
+/**
+ * `extensions.code` carried by every group-authority refusal, on the local
+ * GraphQL path and on the wire alike. The specific refusal travels beside it as
+ * `extensions.reason`, so one category covers many refusals without a code per
+ * refusal — and only a registered code may leave the device at all.
+ */
+export declare const GROUP_CONTROL_DENIED = "KB14";
+/**
+ * `extensions.reason` carried by every admin-gate refusal, under
+ * `extensions.code = 'KB14'`. An app matches on the pair rather than on the
+ * message, so the wording can change without breaking a caller that hides or
+ * disables an admin-only control.
+ */
+export declare const NOT_GROUP_ADMIN = "NOT_GROUP_ADMIN";
+/**
+ * `extensions.reason` carried when a group's only admin tries to leave it,
+ * under `extensions.code = 'KB14'`.
+ *
+ * Leaving revokes the leaver's own control authority, and that revocation has to
+ * be one the group accepts: the roster fold drops an entry that would leave zero
+ * admins, so the last admin's self-demotion could never take effect. Departing
+ * anyway would strand the group with an admin who holds authority everywhere and
+ * is present nowhere. The app's move is to promote a successor first.
+ */
+export declare const LAST_GROUP_ADMIN = "LAST_GROUP_ADMIN";
+export type RequireGroupAdminParams = {
+    store: P2PStoreAPI;
+    groupID: string;
+    /** The DID whose authority is being checked — the caller, not the target. */
+    did: string;
+    /** Phrase completing "only a group admin can ..." in the refusal message. */
+    action: string;
+};
+/**
+ * Refuse unless `did` is an admin of `groupID` right now.
+ *
+ * The answer comes from the membership row's `role`, written only by the roster
+ * mirror — the roster folded over the authenticated MLS epoch chain, in
+ * enactment order. Authority moves exactly when the commit carrying the change
+ * lands, and no signer can place a role change earlier by choosing its own
+ * timestamp.
+ *
+ * Reading the row rather than the roster is deliberate: a role lives ON a
+ * membership row, so reading it this way implies membership, and the mirror's
+ * update-only write can never conjure a row. The roster is DID-keyed and can
+ * carry a role for a DID holding no MLS leaf, so consulting it directly drops
+ * the membership half of the check silently. `isGroupAdmin` also applies the
+ * membership check's removal-boundary semantics, so a tombstoned member is
+ * never an admin.
+ *
+ * Advisory, as every local check is: the ultimate authority is each peer's own
+ * fold, which drops a non-admin's entry regardless. Refusing here turns a
+ * silently discarded write into a loud, catchable failure — a stale gate is a
+ * stale button, never a hole.
+ */
+export declare function requireGroupAdmin(params: RequireGroupAdminParams): Promise<void>;

package/lib/context/require-admin.js

@@ -0,0 +1,57 @@
+import { GraphQLError } from 'graphql';
+/**
+ * `extensions.code` carried by every group-authority refusal, on the local
+ * GraphQL path and on the wire alike. The specific refusal travels beside it as
+ * `extensions.reason`, so one category covers many refusals without a code per
+ * refusal — and only a registered code may leave the device at all.
+ */ export const GROUP_CONTROL_DENIED = 'KB14';
+/**
+ * `extensions.reason` carried by every admin-gate refusal, under
+ * `extensions.code = 'KB14'`. An app matches on the pair rather than on the
+ * message, so the wording can change without breaking a caller that hides or
+ * disables an admin-only control.
+ */ export const NOT_GROUP_ADMIN = 'NOT_GROUP_ADMIN';
+/**
+ * `extensions.reason` carried when a group's only admin tries to leave it,
+ * under `extensions.code = 'KB14'`.
+ *
+ * Leaving revokes the leaver's own control authority, and that revocation has to
+ * be one the group accepts: the roster fold drops an entry that would leave zero
+ * admins, so the last admin's self-demotion could never take effect. Departing
+ * anyway would strand the group with an admin who holds authority everywhere and
+ * is present nowhere. The app's move is to promote a successor first.
+ */ export const LAST_GROUP_ADMIN = 'LAST_GROUP_ADMIN';
+/**
+ * Refuse unless `did` is an admin of `groupID` right now.
+ *
+ * The answer comes from the membership row's `role`, written only by the roster
+ * mirror — the roster folded over the authenticated MLS epoch chain, in
+ * enactment order. Authority moves exactly when the commit carrying the change
+ * lands, and no signer can place a role change earlier by choosing its own
+ * timestamp.
+ *
+ * Reading the row rather than the roster is deliberate: a role lives ON a
+ * membership row, so reading it this way implies membership, and the mirror's
+ * update-only write can never conjure a row. The roster is DID-keyed and can
+ * carry a role for a DID holding no MLS leaf, so consulting it directly drops
+ * the membership half of the check silently. `isGroupAdmin` also applies the
+ * membership check's removal-boundary semantics, so a tombstoned member is
+ * never an admin.
+ *
+ * Advisory, as every local check is: the ultimate authority is each peer's own
+ * fold, which drops a non-admin's entry regardless. Refusing here turns a
+ * silently discarded write into a loud, catchable failure — a stale gate is a
+ * stale button, never a hole.
+ */ export async function requireGroupAdmin(params) {
+    const { store, groupID, did, action } = params;
+    if (await store.isGroupAdmin(groupID, did)) {
+        return;
+    }
+    throw new GraphQLError(`not authorized: only a group admin can ${action}`, {
+        extensions: {
+            code: GROUP_CONTROL_DENIED,
+            reason: NOT_GROUP_ADMIN,
+            groupID
+        }
+    });
+}

package/lib/context/sync.d.ts

@@ -1,3 +1,15 @@
 import type { SyncRequestContext } from '../types.js';
 import type { ContextDeps } from './types.js';
+/**
+ * Why a candidate failed, for a caller that gets only the outcome.
+ *
+ * The WHOLE cause chain: the outer links are the ones every transport failure
+ * shares (`Transport read failed` → `AbortInterruption` → …), so stopping early
+ * makes an eviction, a hub outage and a phone that is off read identically. A
+ * removal is four links down.
+ *
+ * A link with no message is stepped over, not stopped at — giving up there is
+ * how a deeper unwrap says less than the one-level version.
+ */
+export declare function describeFailure(error: unknown): string | undefined;
 export declare function createSyncContext(_ctx: unknown, deps: ContextDeps): SyncRequestContext;

package/lib/context/sync.js

@@ -1 +1,252 @@
-export function createSyncContext(e,s){return{addPeer:e=>s.syncManager.addPeer({config:e,stores:s.stores}),removePeer:e=>s.syncManager.removePeer({peerDID:e,stores:s.stores}),listPeers:()=>s.syncManager.listPeers({stores:s.stores}),getStatus:e=>s.syncManager.getStatus({peerDID:e,stores:s.stores})}}
+import { getGraphStore } from '@kubun/store-graph';
+import { getP2PStore } from '@kubun/store-p2p';
+import { rankSyncPeers } from '../groups/peer-selection.js';
+import { resolveCatalogSyncScopes } from '../sync/catalog-scope.js';
+const NO_OP = {
+    messagesReceived: 0,
+    messagesSent: 0,
+    divergentBuckets: 0
+};
+/**
+ * Why a candidate failed, for a caller that gets only the outcome.
+ *
+ * The WHOLE cause chain: the outer links are the ones every transport failure
+ * shares (`Transport read failed` → `AbortInterruption` → …), so stopping early
+ * makes an eviction, a hub outage and a phone that is off read identically. A
+ * removal is four links down.
+ *
+ * A link with no message is stepped over, not stopped at — giving up there is
+ * how a deeper unwrap says less than the one-level version.
+ */ export function describeFailure(error) {
+    if (!(error instanceof Error)) {
+        return error == null ? undefined : String(error);
+    }
+    const messages = [];
+    // Bounded by identity: nothing here emits a cycle, but this runs on the
+    // failure path, where the alternative is hanging while reporting a failure.
+    const seen = new Set();
+    let current = error;
+    while(current instanceof Error && !seen.has(current)){
+        seen.add(current);
+        if (current.message !== '') {
+            messages.push(current.message);
+        }
+        current = current.cause;
+    }
+    return messages.join(': ');
+}
+/**
+ * What the local device has opted into pulling: only ACTIVE catalogs contribute
+ * (`resolveCatalogSyncScopes` skips known/unknown ones), so a device that has
+ * activated nothing syncs nothing. The owners come from each active catalog's
+ * circle members — never hand-built pairs.
+ *
+ * Shared by both catch-up entries, so an automatically-chosen peer and a
+ * user-named one cannot be asked for different scopes.
+ */ async function resolveActiveScopes(stores) {
+    const graphStore = await getGraphStore(stores);
+    const activeCatalogs = await graphStore.listStoredCatalogs({
+        active: true
+    });
+    const scope = await resolveCatalogSyncScopes(stores, activeCatalogs.map((catalog)=>catalog.id));
+    const owners = scope.owners ?? [];
+    return {
+        scopes: scope.modelIDs.flatMap((modelID)=>owners.map((ownerDID)=>({
+                    modelID,
+                    ownerDID
+                }))),
+        // What this device HAS, not what its catalogs name. A catalog may name a
+        // model that was never deployed here — that is the case the peer answers by
+        // shipping the model's cluster — so deriving this from the scope would
+        // declare every such model known and suppress the very definition needed.
+        knownModelIDs: await graphStore.listDocumentModelIDs()
+    };
+}
+export function createSyncContext(_ctx, deps) {
+    /**
+   * Where to reach a co-member, preferring the group's hub tunnel.
+   *
+   * A peer with a row in the group's discovery projection is reachable through
+   * that group by construction: the row was written from an MLS-authenticated
+   * announce, and `tunnel://<groupID>/<peerDID>` needs nothing else. `undefined`
+   * hands the question back to the persisted registry, which is what a peer
+   * added by URL — an HTTP server, an in-process test peer — still needs.
+   *
+   * 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 p2pStore = await getP2PStore(deps.stores);
+        const announcement = await p2pStore.getPeerAnnouncement({
+            groupID,
+            peerDID
+        });
+        return announcement == null ? undefined : `tunnel://${groupID}/${peerDID}`;
+    };
+    // Bidirectional: each device pushes the docs it owns (its own owner-scope
+    // authorizes) and pulls what it may. Reaching the peer needs no prior
+    // `connectPeer` either way — the projection and the registry are both
+    // persisted, so this works on the first call after a restart.
+    const runCatchUp = async (groupID, peerDID)=>{
+        const { scopes, knownModelIDs } = await resolveActiveScopes(deps.stores);
+        // No active catalog (or none resolvable to a concrete owner) → the opt-in
+        // resting state. A clean all-zero no-op, never an error and never a peer
+        // round-trip.
+        if (scopes.length === 0) {
+            return NO_OP;
+        }
+        const endpoint = await resolveRoute(groupID, peerDID);
+        const result = await deps.syncManager.merkleSyncWithPeer({
+            peerDID,
+            scopes,
+            stores: deps.stores,
+            knownModelIDs,
+            direction: 'both',
+            ...endpoint == null ? {} : {
+                endpoint
+            }
+        });
+        return {
+            messagesReceived: result.messagesReceived,
+            messagesSent: result.messagesSent,
+            divergentBuckets: result.divergentBuckets
+        };
+    };
+    return {
+        addPeer: (config)=>deps.syncManager.addPeer({
+                config,
+                stores: deps.stores
+            }),
+        removePeer: (peerDID)=>deps.syncManager.removePeer({
+                peerDID,
+                stores: deps.stores
+            }),
+        listPeers: ()=>deps.syncManager.listPeers({
+                stores: deps.stores
+            }),
+        getStatus: (peerDID)=>deps.syncManager.getStatus({
+                peerDID,
+                stores: deps.stores
+            }),
+        // The user named the peer, so the ranking is not consulted: intent beats
+        // policy, and this is what makes phone-to-phone "I just changed this, show me
+        // now" work against a device automatic selection would never pick. A failure
+        // is raised rather than reported, for the same reason: someone is watching.
+        syncPeer: async (groupID, peerDID)=>{
+            // Tunnel topics derive from the MLS epoch, so a roster commit landing
+            // mid-session kills it. A fresh session derives the new topics.
+            //
+            // ARMED BY THE ROTATION, never by the error: matching `TransportDisposed`
+            // would swallow a session torn down for any other reason, and retrying
+            // every failure would double the wait against an unreachable peer.
+            //
+            // A flag from the listener, not a before/after read of `groupEpoch` — the
+            // rotation can land between the failure and the re-read. The listener runs
+            // inside the registry's mutex, so it may only set a boolean.
+            let rotated = false;
+            const stopWatching = deps.registry.onEpochChanged((changed)=>{
+                if (changed === groupID) {
+                    rotated = true;
+                }
+            });
+            try {
+                try {
+                    return await runCatchUp(groupID, peerDID);
+                } catch (error) {
+                    if (!rotated) {
+                        throw error;
+                    }
+                    deps.logger.debug('retrying a sync the group epoch moved under', {
+                        groupID,
+                        peerDID
+                    });
+                    // ONCE: two consecutive broken sessions means "not now".
+                    return await runCatchUp(groupID, peerDID);
+                }
+            } catch (error) {
+                // Named, because the raw message is routinely `Transport read failed` —
+                // useless to a screen that must say which row it could not reach. Only
+                // this layer holds both the peer and the unwrapped cause.
+                throw new Error(`sync with ${peerDID} failed: ${describeFailure(error) ?? 'unknown error'}`, {
+                    cause: error
+                });
+            } finally{
+                stopWatching();
+            }
+        },
+        catchUpWithBestPeer: async (groupID)=>{
+            const { scopes } = await resolveActiveScopes(deps.stores);
+            if (scopes.length === 0) {
+                return {
+                    peerDID: null,
+                    outcome: 'no-scopes',
+                    ...NO_OP
+                };
+            }
+            const p2pStore = await getP2PStore(deps.stores);
+            const rows = await p2pStore.listPeerAnnouncements(groupID);
+            const candidates = rankSyncPeers(rows, {
+                selfDID: deps.identity.id
+            });
+            if (candidates.length === 0) {
+                return {
+                    peerDID: null,
+                    outcome: 'no-candidates',
+                    ...NO_OP
+                };
+            }
+            // Down the ranking until one answers. A row records that a device once
+            // announced, never that it is on now — and no cheaper probe exists, so a
+            // failed session IS the reachability test. Bounded by the transport's own
+            // idle timeout, which is why the tunnel resolver sets one.
+            let lastPeerDID = null;
+            let lastFailure;
+            for (const candidate of candidates){
+                lastPeerDID = candidate.peer_did;
+                try {
+                    return {
+                        peerDID: candidate.peer_did,
+                        outcome: 'synced',
+                        ...await runCatchUp(groupID, candidate.peer_did)
+                    };
+                } catch (error) {
+                    // Nothing was reached, so nothing was learned about this peer beyond
+                    // "not now". The next candidate is the whole remedy — but a run that
+                    // walks every candidate and reports `no-route` looks identical whether
+                    // the devices are off or the local apply is throwing, and only this
+                    // line tells them apart.
+                    //
+                    // At `warn`, not `debug`: the OUTCOME ships at info, so a build that
+                    // drops debug reports that every candidate failed while discarding the
+                    // only record of why. That is the shape a device QA session hit — the
+                    // reason existed and was below the level anyone was reading.
+                    lastFailure = error;
+                    deps.logger.warn('catch-up candidate failed', {
+                        groupID,
+                        peerDID: candidate.peer_did,
+                        error
+                    });
+                }
+            }
+            const failureReason = describeFailure(lastFailure);
+            return {
+                peerDID: lastPeerDID,
+                outcome: 'no-route',
+                ...NO_OP,
+                ...failureReason == null ? {} : {
+                    failureReason
+                }
+            };
+        },
+        listPeerDevices: async (groupID)=>{
+            const p2pStore = await getP2PStore(deps.stores);
+            return (await p2pStore.listPeerAnnouncements(groupID)).map((row)=>({
+                    peerDID: row.peer_did,
+                    label: row.label,
+                    availability: row.availability,
+                    capabilities: row.capabilities,
+                    hlc: row.hlc
+                }));
+        }
+    };
+}

package/lib/context/types.d.ts

@@ -1,65 +1,101 @@
-import type { KeyPackageBundle } from '@enkaku/group';
-import type { Runtime } from '@enkaku/runtime';
-import type { OwnIdentity } from '@enkaku/token';
+import type { OwnIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import type { Adapter } from '@kubun/db-adapter';
 import type { HLC } from '@kubun/hlc';
 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 { P2PEventEmitter } from '../groups/events.js';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
 import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
 import type { GroupManager } from '../groups/manager.js';
+import type { PeerConnectionRegistry } from '../peer/connection-registry.js';
 import type { SyncManager } from '../sync/sync-manager.js';
-import type { RejoinResult } from '../types.js';
-export type PendingJoinRequest = {
-    publicPackage: KeyPackageBundle['publicPackage'];
-    privatePackage: KeyPackageBundle['privatePackage'];
-    did: string;
-};
+import type { CircleData, LedgerCatchupOptions, LedgerCatchupSummary, RejoinResult } from '../types.js';
 export type ContextDeps = {
     identity: OwnIdentity;
     groupManager: GroupManager;
     registry: GroupHandleRegistry;
     syncManager: SyncManager;
+    /**
+     * Plugin-scoped in-memory registry of live peer connections, keyed by
+     * `peerDID`. `connectPeer` writes here; nothing is persisted.
+     */
+    peerConnections: PeerConnectionRegistry;
     stores: StoreProvider;
+    /**
+     * The DEVICE-wide store provider, which `stores` is not: under `mutateGraph`
+     * that one is the request's own transaction, and a write made through it after
+     * the commit hook has fired never lands — it waits on a transaction that is
+     * already over. Work deferred past the mutation must use this instead.
+     */
+    deviceStores: StoreProvider;
     adapter: Adapter;
     hlc: HLC;
     emitter: P2PEventEmitter;
-    pendingJoinRequests: Map<string, PendingJoinRequest>;
     runtime: Runtime;
     autoAcceptPeers?: Array<string>;
     /**
-     * Fire-and-forget hub broadcast trigger. Wired to `HubWiring.scheduleBroadcast`
-     * when the p2p plugin is configured with `hub`; otherwise a no-op from
-     * `DISABLED_HUB`. Handlers invoke this via `stores.onCommit(...)` so the hub
-     * send runs after the mutation transaction commits.
+     * How long `requestInvite` waits for its own Add commit to settle before
+     * returning the truthful pending shape (a parked commit, inviter offline).
+     * Test-only escape hatch — production omits it and runs on the 30s default;
+     * lets a headless test drive the park-then-pending path without waiting out
+     * the full production timeout.
+     */
+    inviteCommitTimeoutMs?: number;
+    /**
+     * Fire-and-forget hub broadcast trigger. Wired to `HubWiring.scheduleBroadcast`;
+     * a no-op for a group with no hub-backed peer to fan out to. Handlers invoke
+     * this via `stores.onCommit(...)` so the hub send runs after the mutation
+     * transaction commits.
      */
     scheduleBroadcast: (groupID: string, message: GroupBroadcastMessage) => void;
     /**
      * Awaitable broadcast (encrypt + send completed on resolve). Wired to
-     * `HubWiring.broadcastNow`; a no-op resolve under `DISABLED_HUB`. Used where
+     * `HubWiring.broadcastNow`; a no-op resolve for a group with no hub-backed
+     * peer. Used where
      * the send must complete before a following local op — e.g. a leave-request
      * encrypted while the MLS handle is still live, before `leaveGroup`.
      */
     broadcastNow: (groupID: string, message: GroupBroadcastMessage) => Promise<void>;
     /**
-     * Fire-and-forget fan-out of an MLS handshake Commit to a group's existing
-     * members. Wired to `HubWiring.scheduleSendCommit`; a no-op under
-     * `DISABLED_HUB`. Handlers invoke it via `stores.onCommit(...)` so the send
-     * runs after the mutation transaction commits.
+     * Drive a commit through the group's canonical commit hub and await its
+     * outcome. Wired to `HubWiring.commitToGroup`. Used by the control-ledger
+     * enact path: the admin's role entry rides the commit's bodies, published to
+     * the commit log, and the local MLS handle is advanced only when the log
+     * accepts. A group with no hub bound publishes to its in-process loopback log,
+     * so the enact path is available with or without a hub.
      */
-    scheduleSendCommit: (groupID: string, commitBytes: Uint8Array) => void;
+    commitToGroup: (groupID: string, build: () => Promise<PendingCommit>) => Promise<LaneResult>;
     /** Shared group-health monitor; source for the `groupHealth` query. */
     monitor: GroupHealthMonitor;
     /**
-     * Run stale-device recovery for a group. Wired to `HubWiring.rejoinGroup`;
-     * a no-op `recovery-failed` under `DISABLED_HUB`.
+     * Run stale-device recovery for a group. Wired to `HubWiring.rejoinGroup`,
+     * which recovers through the rendezvous when a live member answers — reporting
+     * `recovered` on success, or `recovery-failed` (without throwing) when no
+     * responder is reachable.
      */
     rejoinGroup: (groupID: string) => Promise<RejoinResult>;
+    /**
+     * Gather the group's whole control ledger from its current members and adopt
+     * it locally, verified against this device's authenticated head. Wired to
+     * `HubWiring.requestLedgerCatchup`; a no-op all-zero summary for a group with
+     * no hub-backed peer to gather from, or when every responder's ledger was
+     * refused. The drift/backstop path for a joiner whose invite snapshot missed
+     * entries appended after the invite was minted.
+     */
+    requestLedgerCatchup: (groupID: string, options?: LedgerCatchupOptions) => Promise<LedgerCatchupSummary>;
     logger: Logger;
 };
 export declare function toISO(timestamp: unknown): string;
+/**
+ * The one circle row → API mapping, so every producer (queries, events, mutation
+ * payloads) reports the same shape — notably the projected `open` flag, stored as
+ * integer 0/1 to read back uniformly across SQLite and Postgres.
+ */
+export declare function toCircleData(row: Circle): CircleData;
 /**
  * Normalize a credential value from the DB.
  * Kysely's ParseJSONResultsPlugin may have already parsed the JSON string

package/lib/context/types.js

@@ -1 +1,48 @@
-export function toISO(e){return"number"==typeof e?new Date(1e3*e).toISOString():e instanceof Date?e.toISOString():String(e)}export function normalizeCredential(e){return"string"==typeof e?e:JSON.stringify(e)}export function checkPeerAccess(e,t,n){if(null!=n){if(!n.includes(e))throw Error("Peer not in autoAcceptPeers list")}else if(e!==t)throw Error("Only the engine identity can perform this operation")}
+export function toISO(timestamp) {
+    if (typeof timestamp === 'number') {
+        return new Date(timestamp * 1000).toISOString();
+    }
+    if (timestamp instanceof Date) {
+        return timestamp.toISOString();
+    }
+    return String(timestamp);
+}
+/**
+ * The one circle row → API mapping, so every producer (queries, events, mutation
+ * payloads) reports the same shape — notably the projected `open` flag, stored as
+ * integer 0/1 to read back uniformly across SQLite and Postgres.
+ */ export function toCircleData(row) {
+    return {
+        id: row.id,
+        groupID: row.group_id,
+        name: row.name,
+        description: row.description,
+        open: row.open === 1,
+        createdAt: toISO(row.created_at)
+    };
+}
+/**
+ * Normalize a credential value from the DB.
+ * Kysely's ParseJSONResultsPlugin may have already parsed the JSON string
+ * into an object. SerializedMLSGroupState expects a JSON string.
+ */ export function normalizeCredential(value) {
+    if (typeof value === 'string') return value;
+    return JSON.stringify(value);
+}
+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
+    // never lock the device out of inviting/joining on its own behalf — an
+    // inviter that trusts a peer via `autoAcceptPeers` still runs the invite as
+    // itself, and a joiner drives its own inbound dance locally.
+    if (viewerDID === identityID) {
+        return;
+    }
+    if (autoAcceptPeers != null) {
+        if (!autoAcceptPeers.includes(viewerDID)) {
+            throw new Error('Peer not in autoAcceptPeers list');
+        }
+    } else {
+        throw new Error('Only the engine identity can perform this operation');
+    }
+}

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

@@ -0,0 +1,44 @@
+import { type OwnIdentity } from '@kokuin/token';
+/** The rule a member states for one of its models. Mirrors the stored shape. */
+export type AccessDefaultRule = {
+    level: string;
+    allowedDIDs: Array<string> | null;
+    allowedCircles: Array<string> | null;
+    allowedGroups: Array<string> | null;
+};
+type SetPayload = {
+    op: 'set';
+    modelID: string;
+    permissionType: 'read' | 'write';
+    rule: AccessDefaultRule;
+    hlc: string;
+};
+type RemovePayload = {
+    op: 'remove';
+    modelID: string;
+    permissionTypes: Array<'read' | 'write'>;
+    hlc: string;
+};
+/**
+ * The verified claim behind an access-default broadcast. `issuer` is the
+ * authenticated author (the verified token `iss`) — the owner whose sharing
+ * policy this is. Every authoritative field comes from the signed payload, so a
+ * receiver never trusts the surrounding plaintext frame.
+ */
+export type VerifiedAccessDefault = {
+    issuer: string;
+    claim: SetPayload;
+} | {
+    issuer: string;
+    claim: RemovePayload;
+};
+export declare function signAccessDefaultSet(identity: OwnIdentity, claim: Omit<SetPayload, 'op'>): Promise<string>;
+export declare function signAccessDefaultRemove(identity: OwnIdentity, claim: Omit<RemovePayload, 'op'>): Promise<string>;
+/**
+ * Verify a signed access-default token and extract its claim. Returns `null`
+ * (never throws) when the token is unparseable, unsigned (`alg: 'none'`), or
+ * structurally malformed — an attacker cannot forge an `iss` this way. The
+ * issuer is the normalized verified `iss`.
+ */
+export declare function verifyAccessDefault(token: string): Promise<VerifiedAccessDefault | null>;
+export {};