@kubun/store-p2p 0.17.0 → 0.18.1

package/lib/ops/mls.js

@@ -1,12 +1,49 @@
 export function createMLSOps(db, adapter) {
     return {
-        async saveMLSState (state) {
-            await db.insertInto('kubun_p2p_group_mls_state').values({
+        async saveMLSState (state, expected) {
+            if (expected === null) {
+                const inserted = await db.insertInto('kubun_p2p_group_mls_state').values({
+                    group_id: state.group_id,
+                    device_id: state.device_id,
+                    mls_state: adapter.encodeBinary(state.mls_state),
+                    credential: state.credential,
+                    epoch: state.epoch,
+                    state_version: state.state_version ?? 0,
+                    is_deleted: 0,
+                    sender_generation_hwm: state.sender_generation_hwm ?? 0,
+                    ledger_entries: state.ledger_entries
+                }).onConflict((oc)=>oc.columns([
+                        'group_id',
+                        'device_id'
+                    ]).doNothing()).returning('state_version').executeTakeFirst();
+                return inserted != null;
+            }
+            if (expected != null) {
+                if (state.epoch < expected.epoch) return false;
+                if ((state.state_version ?? 0) <= expected.stateVersion) {
+                    throw new Error(`MLS state version must advance for group ${state.group_id}`);
+                }
+                const saved = await db.updateTable('kubun_p2p_group_mls_state').set((eb)=>({
+                        mls_state: adapter.encodeBinary(state.mls_state),
+                        credential: state.credential,
+                        epoch: state.epoch,
+                        state_version: state.state_version ?? 0,
+                        is_deleted: 0,
+                        sender_generation_hwm: state.epoch === expected.epoch ? eb.ref('sender_generation_hwm') : 0,
+                        ledger_entries: state.ledger_entries ?? '[]',
+                        updated_at: adapter.encodeTimestamp(new Date())
+                    })).where('group_id', '=', state.group_id).where('device_id', '=', state.device_id).where('epoch', '=', expected.epoch).where('state_version', '=', expected.stateVersion).returning('state_version').executeTakeFirst();
+                return saved != null;
+            }
+            const saved = await db.insertInto('kubun_p2p_group_mls_state').values({
                 group_id: state.group_id,
                 device_id: state.device_id,
                 mls_state: adapter.encodeBinary(state.mls_state),
                 credential: state.credential,
                 epoch: state.epoch,
+                state_version: state.state_version ?? 0,
+                is_deleted: 0,
+                sender_generation_hwm: state.sender_generation_hwm ?? 0,
                 ledger_entries: state.ledger_entries
             }).onConflict((oc)=>oc.columns([
                     'group_id',
@@ -15,36 +52,93 @@ export function createMLSOps(db, adapter) {
                         mls_state: eb.ref('excluded.mls_state'),
                         credential: eb.ref('excluded.credential'),
                         epoch: eb.ref('excluded.epoch'),
+                        state_version: eb.ref('excluded.state_version'),
+                        is_deleted: 0,
+                        sender_generation_hwm: eb.case().when('kubun_p2p_group_mls_state.epoch', '=', eb.ref('excluded.epoch')).then(eb.ref('kubun_p2p_group_mls_state.sender_generation_hwm')).else(0).end(),
                         ledger_entries: eb.ref('excluded.ledger_entries'),
                         updated_at: adapter.encodeTimestamp(new Date())
-                    }))// Monotonic-epoch guard: only overwrite when the incoming epoch is
-                // at least the stored one. The MLS epoch never moves backwards, so a
-                // write carrying a lower epoch is a stale handle re-persisting an
-                // already-superseded ratchet — apply it and we roll the ratchet back.
-                // When this predicate is false the existing row is left untouched
-                // with no error (a silent no-op); a fresh insert has no conflict and
-                // is unaffected. The bound is `<=`, not `<`: decrypting an
-                // application message advances the secret-tree generation WITHIN an
-                // epoch while `epoch` stays constant, so a legitimate same-epoch
-                // re-persist carries a changed `mls_state` blob at the same epoch and
-                // must still win — `<` would reject it and wedge decryption.
-                .where((eb)=>eb('kubun_p2p_group_mls_state.epoch', '<=', eb.ref('excluded.epoch')))).execute();
+                    }))// Epochs order commits; the state version orders in-place secret-tree
+                // mutations within an epoch. A late persist of an older snapshot
+                // must never overwrite a newer generation at the same epoch.
+                .where((eb)=>eb.or([
+                        eb('kubun_p2p_group_mls_state.epoch', '<', eb.ref('excluded.epoch')),
+                        eb.and([
+                            eb('kubun_p2p_group_mls_state.epoch', '=', eb.ref('excluded.epoch')),
+                            eb('kubun_p2p_group_mls_state.state_version', '<', eb.ref('excluded.state_version'))
+                        ])
+                    ]))).returning('state_version').executeTakeFirst();
+            return saved != null;
+        },
+        async reserveSenderGenerations ({ groupID, deviceID, epoch, current, size, expectedHWM, senderState }) {
+            if (!Number.isSafeInteger(current) || current < 0 || !Number.isSafeInteger(size) || size < 1) {
+                throw new Error('Invalid sender generation reservation');
+            }
+            for(;;){
+                const row = await db.selectFrom('kubun_p2p_group_mls_state').select([
+                    'epoch',
+                    'sender_generation_hwm'
+                ]).where('group_id', '=', groupID).where('device_id', '=', deviceID).where('is_deleted', '=', 0).executeTakeFirst();
+                if (row == null || row.epoch !== epoch) {
+                    throw new Error(`Sender generation reservation has stale epoch for group ${groupID}`);
+                }
+                if (row.sender_generation_hwm !== expectedHWM) return null;
+                const next = Math.max(row.sender_generation_hwm, current + size);
+                if (!Number.isSafeInteger(next)) throw new Error('Sender generation reservation overflow');
+                let reserved = next;
+                if (next !== row.sender_generation_hwm) {
+                    const updated = await db.updateTable('kubun_p2p_group_mls_state').set({
+                        sender_generation_hwm: next
+                    }).where('group_id', '=', groupID).where('device_id', '=', deviceID).where('epoch', '=', epoch).where('is_deleted', '=', 0).where('sender_generation_hwm', '=', row.sender_generation_hwm).returning('sender_generation_hwm').executeTakeFirst();
+                    if (updated == null) continue;
+                    reserved = updated.sender_generation_hwm;
+                }
+                if (senderState != null) {
+                    // A later reservation by another holder wins: its state is newer.
+                    await db.updateTable('kubun_p2p_group_mls_state').set({
+                        mls_state: adapter.encodeBinary(senderState.mlsState)
+                    }).where('group_id', '=', groupID).where('device_id', '=', deviceID).where('epoch', '=', epoch).where('is_deleted', '=', 0).where('state_version', '=', senderState.stateVersion).where('sender_generation_hwm', '=', reserved).execute();
+                }
+                return reserved;
+            }
         },
-        async getMLSState (groupID, deviceID) {
-            return await db.selectFrom('kubun_p2p_group_mls_state').selectAll().where('group_id', '=', groupID).where('device_id', '=', deviceID).executeTakeFirst();
+        async getMLSState (groupID, deviceID, options) {
+            let query = db.selectFrom('kubun_p2p_group_mls_state').selectAll().where('group_id', '=', groupID).where('device_id', '=', deviceID);
+            if (options?.includeDeleted !== true) query = query.where('is_deleted', '=', 0);
+            return await query.executeTakeFirst();
         },
-        async deleteMLSState (groupID, deviceID) {
-            await db.deleteFrom('kubun_p2p_group_mls_state').where('group_id', '=', groupID).where('device_id', '=', deviceID).execute();
+        async deleteMLSState (groupID, deviceID, expected) {
+            let query = db.updateTable('kubun_p2p_group_mls_state').set((eb)=>({
+                    mls_state: adapter.encodeBinary(new Uint8Array()),
+                    credential: '',
+                    ledger_entries: '[]',
+                    sender_generation_hwm: 0,
+                    is_deleted: 1,
+                    state_version: eb('state_version', '+', 1),
+                    updated_at: adapter.encodeTimestamp(new Date())
+                })).where('group_id', '=', groupID).where('device_id', '=', deviceID).where('is_deleted', '=', 0);
+            if (expected != null) {
+                query = query.where('epoch', '=', expected.epoch).where('state_version', '=', expected.stateVersion);
+            }
+            const deleted = await query.returning('state_version').executeTakeFirst();
+            return deleted != null;
         },
         async listMLSStates (groupID) {
-            return await db.selectFrom('kubun_p2p_group_mls_state').selectAll().where('group_id', '=', groupID).execute();
+            return await db.selectFrom('kubun_p2p_group_mls_state').selectAll().where('group_id', '=', groupID).where('is_deleted', '=', 0).execute();
         },
         async listMLSStateGroupIDs (deviceID) {
-            const rows = await db.selectFrom('kubun_p2p_group_mls_state').select('group_id').where('device_id', '=', deviceID).execute();
+            const rows = await db.selectFrom('kubun_p2p_group_mls_state').select('group_id').where('device_id', '=', deviceID).where('is_deleted', '=', 0).execute();
             return rows.map((row)=>row.group_id);
         },
         async deleteGroupMLSStates (groupID) {
-            await db.deleteFrom('kubun_p2p_group_mls_state').where('group_id', '=', groupID).execute();
+            await db.updateTable('kubun_p2p_group_mls_state').set((eb)=>({
+                    mls_state: adapter.encodeBinary(new Uint8Array()),
+                    credential: '',
+                    ledger_entries: '[]',
+                    sender_generation_hwm: 0,
+                    is_deleted: 1,
+                    state_version: eb('state_version', '+', 1),
+                    updated_at: adapter.encodeTimestamp(new Date())
+                })).where('group_id', '=', groupID).where('is_deleted', '=', 0).execute();
         }
     };
 }

package/lib/ops/own-agents.d.ts

@@ -0,0 +1,68 @@
+import { type MethodRegistry } from '@kokuin/token';
+import { type Adapter } from '@kubun/db-adapter';
+import { type RecordDecision, type RecordDecisionMap, type RecordKey, type SignedRecord } from '@kubun/records';
+import { type Kysely } from 'kysely';
+import type { GroupKind, OwnAgentsGrantKind, P2PStoreTables } from '../tables.js';
+export type OwnAgentsRecordKey = RecordKey;
+export type OwnAgentsRecord = SignedRecord;
+export type OwnAgentsGrant = {
+    controllerDID: string;
+    kind: OwnAgentsGrantKind;
+    token: string;
+    issuedAt: number;
+    expiresAt: number;
+};
+export type OwnAgentsJoinCapability = {
+    groupID: string;
+    recipientDID: string;
+    capabilityID: string;
+    token: string;
+    expiresAt: number;
+    signerBinding?: {
+        did: string;
+        leafKey: Uint8Array;
+        capability: string;
+        prefix: Array<string>;
+    };
+};
+export type BindingEvidence = {
+    controllerDID: string;
+    deviceDID: string;
+};
+export declare class OwnAgentsTransactionError extends Error {
+    constructor();
+}
+export declare class OwnAgentsGroupNotFoundError extends Error {
+    constructor(groupID: string);
+}
+export declare class OwnAgentsKindDowngradeError extends Error {
+    constructor(groupID: string);
+}
+export declare class OwnAgentsRecordError extends Error {
+    constructor(message: string);
+}
+export type OwnAgentsOps = {
+    retainAccessDefaultRevocations(controllerDID: string, deviceDIDs: ReadonlyArray<string>): Promise<void>;
+    isAccessDefaultSignerRevoked(controllerDID: string, deviceDID: string): Promise<boolean>;
+    /** Idempotent and append-only: rows survive revocation, removal and MLS state loss. */
+    recordBindingEvidence(bindings: ReadonlyArray<BindingEvidence>): Promise<void>;
+    /** Every controller this device has seen `deviceDID` authentically bound to. */
+    listBindingControllers(deviceDID: string): Promise<Array<string>>;
+    setGroupKind(groupID: string, kind: GroupKind): Promise<void>;
+    getGroupKind(groupID: string): Promise<GroupKind | undefined>;
+    getOwnAgentsRecordDecision(key: RecordKey, methods?: MethodRegistry): Promise<RecordDecision | null>;
+    /** The stored decision of each key, from one read per chunk of ids of a type. */
+    getOwnAgentsRecordDecisions(keys: ReadonlyArray<RecordKey>, methods?: MethodRegistry): Promise<RecordDecisionMap>;
+    listOwnAgentsRecordDecisions(types: ReadonlyArray<string>, methods?: MethodRegistry): Promise<Array<RecordDecision>>;
+    putOwnAgentsRecordCopy(record: SignedRecord, methods?: MethodRegistry): Promise<boolean>;
+    pruneOwnAgentsRecordCopy(key: RecordKey, signerDID: string, methods?: MethodRegistry): Promise<void>;
+    lockOwnAgentsRecordKeys(keys: ReadonlyArray<string>): Promise<void>;
+    putOwnGrant(controllerDID: string, kind: OwnAgentsGrantKind, token: string, issuedAt: number, expiresAt: number): Promise<void>;
+    getOwnGrants(controllerDID?: string): Promise<Array<OwnAgentsGrant>>;
+    putJoinCapability(capability: OwnAgentsJoinCapability): Promise<void>;
+    getJoinCapability(groupID: string): Promise<OwnAgentsJoinCapability | undefined>;
+    deleteJoinCapability(groupID: string): Promise<void>;
+};
+export declare const ownAgentsRecordLockKey: (key: RecordKey) => string;
+export declare function ownAgentsAdvisoryLockIDs(ids: ReadonlyArray<bigint>): Array<bigint>;
+export declare function createOwnAgentsOps(db: Kysely<P2PStoreTables>, adapter: Adapter): OwnAgentsOps;

package/lib/ops/own-agents.js

@@ -0,0 +1,359 @@
+import { normalizeDID } from '@kokuin/token';
+import { AbstractPostgresAdapter, chunked } from '@kubun/db-adapter';
+import { recordClaimDigest, recordDecisionFromVerifiedCopies, recordKeyText, recordPayloadMatches, recordSignerKey, verifySignedRecord } from '@kubun/records';
+import { sql } from 'kysely';
+export class OwnAgentsTransactionError extends Error {
+    constructor(){
+        super('Own agents operation requires a transaction');
+        this.name = 'OwnAgentsTransactionError';
+    }
+}
+export class OwnAgentsGroupNotFoundError extends Error {
+    constructor(groupID){
+        super(`Group not found: ${groupID}`);
+        this.name = 'OwnAgentsGroupNotFoundError';
+    }
+}
+export class OwnAgentsKindDowngradeError extends Error {
+    constructor(groupID){
+        super(`Own agents kind cannot downgrade: ${groupID}`);
+        this.name = 'OwnAgentsKindDowngradeError';
+    }
+}
+export class OwnAgentsRecordError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'OwnAgentsRecordError';
+    }
+}
+const compareStrings = (left, right)=>left < right ? -1 : left > right ? 1 : 0;
+export const ownAgentsRecordLockKey = (key)=>JSON.stringify([
+        key.type,
+        key.owner,
+        key.id
+    ]);
+function requireType(type) {
+    if (type !== 'ownAgents.group' && type !== 'ownAgents.capability') throw new OwnAgentsRecordError(`Unsupported own agents record type: ${type}`);
+}
+async function verifiedRows(rows, methods) {
+    const valid = [];
+    for (const row of rows){
+        const copy = {
+            type: row.type,
+            owner: row.owner,
+            id: row.id,
+            hlc: row.hlc,
+            opJWT: row.op_jwt,
+            opHash: row.op_hash,
+            payload: row.payload === null ? null : Uint8Array.from(row.payload)
+        };
+        const op = await verifySignedRecord(copy, methods);
+        if (op !== null && recordPayloadMatches(copy, op.claim)) valid.push({
+            copy,
+            op
+        });
+    }
+    return valid;
+}
+export function ownAgentsAdvisoryLockIDs(ids) {
+    return [
+        ...new Set(ids)
+    ].sort((left, right)=>left < right ? -1 : left > right ? 1 : 0);
+}
+export function createOwnAgentsOps(db, adapter) {
+    const lockKeys = async (tx, keys)=>{
+        if (!(adapter instanceof AbstractPostgresAdapter)) return;
+        const ids = new Set();
+        for (const key of new Set(keys)){
+            const result = await sql`select hashtextextended(${key}, 0)::text as id`.execute(tx);
+            for (const row of result.rows)ids.add(BigInt(row.id));
+        }
+        for (const id of ownAgentsAdvisoryLockIDs([
+            ...ids
+        ])){
+            await sql`select pg_advisory_xact_lock(${id.toString()}::bigint)`.execute(tx);
+        }
+    };
+    const rowsFor = (tx, key)=>tx.selectFrom('kubun_p2p_own_agents_records').selectAll().where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).execute();
+    const deleteCopy = (tx, key, hash)=>tx.deleteFrom('kubun_p2p_own_agents_records').where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).where('op_hash', '=', hash).execute();
+    return {
+        async retainAccessDefaultRevocations (controllerDID, deviceDIDs) {
+            if (deviceDIDs.length === 0) return;
+            await db.insertInto('kubun_p2p_access_default_revocations').values(deviceDIDs.map((did)=>({
+                    controller_did: controllerDID,
+                    device_did: normalizeDID(did)
+                }))).onConflict((oc)=>oc.columns([
+                    'controller_did',
+                    'device_did'
+                ]).doNothing()).execute();
+        },
+        async isAccessDefaultSignerRevoked (controllerDID, deviceDID) {
+            return await db.selectFrom('kubun_p2p_access_default_revocations').select('device_did').where('controller_did', '=', controllerDID).where('device_did', '=', normalizeDID(deviceDID)).executeTakeFirst() != null;
+        },
+        async recordBindingEvidence (bindings) {
+            const rows = new Map();
+            for (const binding of bindings){
+                const row = {
+                    controller_did: normalizeDID(binding.controllerDID),
+                    device_did: normalizeDID(binding.deviceDID)
+                };
+                rows.set(JSON.stringify([
+                    row.controller_did,
+                    row.device_did
+                ]), row);
+            }
+            if (rows.size === 0) return;
+            await db.insertInto('kubun_p2p_binding_evidence').values([
+                ...rows.values()
+            ]).onConflict((oc)=>oc.columns([
+                    'controller_did',
+                    'device_did'
+                ]).doNothing()).execute();
+        },
+        async listBindingControllers (deviceDID) {
+            const rows = await db.selectFrom('kubun_p2p_binding_evidence').select('controller_did').where('device_did', '=', normalizeDID(deviceDID)).orderBy('controller_did').execute();
+            return rows.map((row)=>row.controller_did);
+        },
+        async setGroupKind (groupID, kind) {
+            if (!db.isTransaction) throw new OwnAgentsTransactionError();
+            let update = db.updateTable('kubun_p2p_groups').set({
+                kind
+            }).where('id', '=', groupID);
+            if (kind === 'standard') update = update.where('kind', '=', 'standard');
+            const result = await update.executeTakeFirst();
+            if (result.numUpdatedRows === 0n) {
+                const row = await db.selectFrom('kubun_p2p_groups').select('kind').where('id', '=', groupID).executeTakeFirst();
+                if (row === undefined) throw new OwnAgentsGroupNotFoundError(groupID);
+                throw new OwnAgentsKindDowngradeError(groupID);
+            }
+        },
+        async getGroupKind (groupID) {
+            return (await db.selectFrom('kubun_p2p_groups').select('kind').where('id', '=', groupID).executeTakeFirst())?.kind;
+        },
+        async getOwnAgentsRecordDecision (key, methods) {
+            requireType(key.type);
+            return recordDecisionFromVerifiedCopies(key, await verifiedRows(await rowsFor(db, key), methods), 'hlc');
+        },
+        async getOwnAgentsRecordDecisions (keys, methods) {
+            const wanted = new Map();
+            const idsByType = new Map();
+            for (const key of keys){
+                requireType(key.type);
+                wanted.set(recordKeyText(key), key);
+                const ids = idsByType.get(key.type) ?? new Set();
+                ids.add(key.id);
+                idsByType.set(key.type, ids);
+            }
+            const groups = new Map();
+            for (const [type, idSet] of idsByType){
+                const ids = [
+                    ...idSet
+                ];
+                for (const chunk of chunked(ids)){
+                    const rows = await db.selectFrom('kubun_p2p_own_agents_records').selectAll().where('type', '=', type).where('id', 'in', chunk).execute();
+                    for (const row of rows){
+                        const text = recordKeyText(row);
+                        if (!wanted.has(text)) continue;
+                        const group = groups.get(text) ?? [];
+                        group.push(row);
+                        groups.set(text, group);
+                    }
+                }
+            }
+            const decisions = new Map();
+            for (const [text, rows] of groups){
+                const key = wanted.get(text);
+                const decision = recordDecisionFromVerifiedCopies(key, await verifiedRows(rows, methods), 'hlc');
+                if (decision !== null) decisions.set(text, decision);
+            }
+            return decisions;
+        },
+        async listOwnAgentsRecordDecisions (types, methods) {
+            for (const type of types)requireType(type);
+            if (types.length === 0) return [];
+            const rows = await db.selectFrom('kubun_p2p_own_agents_records').selectAll().where('type', 'in', [
+                ...types
+            ]).orderBy('type').orderBy('owner').orderBy('id').execute();
+            const groups = new Map();
+            for (const row of rows){
+                const key = ownAgentsRecordLockKey(row);
+                const group = groups.get(key) ?? [];
+                group.push(row);
+                groups.set(key, group);
+            }
+            const decisions = [];
+            for (const rows of groups.values()){
+                const first = rows[0];
+                if (first === undefined) continue;
+                const key = {
+                    type: first.type,
+                    owner: first.owner,
+                    id: first.id
+                };
+                const decision = recordDecisionFromVerifiedCopies(key, await verifiedRows(rows, methods), 'hlc');
+                if (decision !== null) decisions.push(decision);
+            }
+            return decisions;
+        },
+        async putOwnAgentsRecordCopy (record, methods) {
+            requireType(record.type);
+            const op = await verifySignedRecord(record, methods);
+            if (op === null || !recordPayloadMatches(record, op.claim)) throw new OwnAgentsRecordError('Invalid signed own agents copy');
+            const signerKey = recordSignerKey(op.issuer, record.opJWT);
+            if (signerKey === null) throw new OwnAgentsRecordError('Invalid own agents signer key');
+            const key = {
+                type: record.type,
+                owner: record.owner,
+                id: record.id
+            };
+            const digest = recordClaimDigest(op.claim);
+            const write = async (tx)=>{
+                await lockKeys(tx, [
+                    ownAgentsRecordLockKey(key)
+                ]);
+                const rows = await rowsFor(tx, key);
+                const valid = await verifiedRows(rows, methods);
+                const winner = recordDecisionFromVerifiedCopies(key, valid, 'hlc');
+                const retained = winner?.decisionHLC === record.hlc && winner.contentDigest === digest ? valid : [];
+                const keepBySigner = new Map([
+                    [
+                        signerKey,
+                        record.opHash
+                    ]
+                ]);
+                for (const entry of retained){
+                    const key = recordSignerKey(entry.op.issuer, entry.copy.opJWT);
+                    if (key === null) continue;
+                    const previous = keepBySigner.get(key);
+                    if (previous === undefined || compareStrings(entry.copy.opHash, previous) < 0) keepBySigner.set(key, entry.copy.opHash);
+                }
+                for (const row of rows){
+                    const entry = retained.find((entry)=>entry.copy.opHash === row.op_hash);
+                    const signer = entry === undefined ? null : recordSignerKey(entry.op.issuer, entry.copy.opJWT);
+                    if (signer === null || keepBySigner.get(signer) !== row.op_hash) await deleteCopy(tx, key, row.op_hash);
+                }
+                if (keepBySigner.get(signerKey) !== record.opHash) return false;
+                await tx.insertInto('kubun_p2p_own_agents_records').values({
+                    type: record.type,
+                    owner: record.owner,
+                    id: record.id,
+                    hlc: record.hlc,
+                    op_hash: record.opHash,
+                    op_jwt: record.opJWT,
+                    payload: record.payload === null ? null : adapter.encodeBinary(record.payload),
+                    payload_digest: op.claim.payloadDigest,
+                    deleted: op.claim.deleted ? 1 : 0,
+                    meta: adapter.encodeJSON(op.claim.meta)
+                }).onConflict((oc)=>oc.columns([
+                        'type',
+                        'owner',
+                        'id',
+                        'op_hash'
+                    ]).doNothing()).execute();
+                return true;
+            };
+            if (db.isTransaction) return await write(db);
+            return await db.transaction().execute(write);
+        },
+        async pruneOwnAgentsRecordCopy (key, signerDID, methods) {
+            requireType(key.type);
+            const signer = normalizeDID(signerDID);
+            const write = async (tx)=>{
+                await lockKeys(tx, [
+                    ownAgentsRecordLockKey(key)
+                ]);
+                const valid = await verifiedRows(await rowsFor(tx, key), methods);
+                if (!valid.some((entry)=>entry.op.issuer !== signer)) return;
+                for (const entry of valid){
+                    if (entry.op.issuer === signer) await deleteCopy(tx, key, entry.copy.opHash);
+                }
+            };
+            if (db.isTransaction) await write(db);
+            else await db.transaction().execute(write);
+        },
+        async lockOwnAgentsRecordKeys (keys) {
+            if (!db.isTransaction) throw new OwnAgentsTransactionError();
+            await lockKeys(db, keys);
+        },
+        async putOwnGrant (controllerDID, kind, token, issuedAt, expiresAt) {
+            const row = {
+                controller_did: controllerDID,
+                kind,
+                token,
+                issued_at: issuedAt,
+                expires_at: expiresAt
+            };
+            await db.insertInto('kubun_p2p_own_agents_grants').values(row).onConflict((oc)=>oc.columns([
+                    'controller_did',
+                    'kind'
+                ]).doUpdateSet(row).whereRef('excluded.issued_at', '>', 'kubun_p2p_own_agents_grants.issued_at')).execute();
+        },
+        async getOwnGrants (controllerDID) {
+            let query = db.selectFrom('kubun_p2p_own_agents_grants').selectAll();
+            if (controllerDID != null) query = query.where('controller_did', '=', controllerDID);
+            const rows = await query.orderBy('kind').execute();
+            return rows.map((row)=>({
+                    controllerDID: row.controller_did,
+                    kind: row.kind,
+                    token: row.token,
+                    issuedAt: Number(row.issued_at),
+                    expiresAt: Number(row.expires_at)
+                }));
+        },
+        async putJoinCapability (capability) {
+            const row = {
+                group_id: capability.groupID,
+                recipient_did: capability.recipientDID,
+                capability_id: capability.capabilityID,
+                token: capability.token,
+                expires_at: capability.expiresAt,
+                signer_did: capability.signerBinding?.did ?? null,
+                signer_leaf_key: capability.signerBinding == null ? null : adapter.encodeBinary(capability.signerBinding.leafKey),
+                signer_capability: capability.signerBinding?.capability ?? null,
+                signer_prefix: capability.signerBinding == null ? null : adapter.encodeJSON({
+                    events: capability.signerBinding.prefix
+                })
+            };
+            const preserveBinding = (column)=>{
+                return sql`case
+          when kubun_p2p_own_agents_join_capabilities.token = excluded.token
+          then ${sql.ref(`kubun_p2p_own_agents_join_capabilities.${column}`)}
+          else null end`;
+            };
+            await db.insertInto('kubun_p2p_own_agents_join_capabilities').values(row).onConflict((oc)=>{
+                return oc.column('group_id').doUpdateSet({
+                    ...row,
+                    // Re-accepting the same consent must not erase authenticated admission evidence.
+                    ...capability.signerBinding != null ? {} : {
+                        signer_did: preserveBinding('signer_did'),
+                        signer_leaf_key: preserveBinding('signer_leaf_key'),
+                        signer_capability: preserveBinding('signer_capability'),
+                        signer_prefix: preserveBinding('signer_prefix')
+                    }
+                });
+            }).execute();
+        },
+        async deleteJoinCapability (groupID) {
+            await db.deleteFrom('kubun_p2p_own_agents_join_capabilities').where('group_id', '=', groupID).execute();
+        },
+        async getJoinCapability (groupID) {
+            const row = await db.selectFrom('kubun_p2p_own_agents_join_capabilities').selectAll().where('group_id', '=', groupID).executeTakeFirst();
+            return row == null ? undefined : {
+                groupID: row.group_id,
+                recipientDID: row.recipient_did,
+                capabilityID: row.capability_id,
+                token: row.token,
+                expiresAt: Number(row.expires_at),
+                ...row.signer_did == null || row.signer_leaf_key == null || row.signer_capability == null || row.signer_prefix == null ? {} : {
+                    signerBinding: {
+                        did: row.signer_did,
+                        leafKey: new Uint8Array(row.signer_leaf_key),
+                        capability: row.signer_capability,
+                        // The JSON results plugin also parses serialized events inside arrays.
+                        prefix: row.signer_prefix.events.map((event)=>typeof event === 'string' ? event : JSON.stringify(event))
+                    }
+                }
+            };
+        }
+    };
+}

package/lib/ops/sync.d.ts

@@ -1,6 +1,16 @@
 import type { Adapter } from '@kubun/db-adapter';
 import type { Kysely } from 'kysely';
 import type { InsertSyncPeer, P2PStoreTables, SyncPeer } from '../tables.js';
+export declare class BroadcastLogPruneParamsError extends Error {
+    get code(): 'P2P_BROADCAST_LOG_PRUNE_PARAMS';
+    constructor(message: string);
+}
+export type PruneBroadcastLogParams = {
+    /** Epoch milliseconds: rows broadcast before it are deleted. */
+    olderThan: number;
+    /** Most rows one call deletes. */
+    limit: number;
+};
 /** Sync peers and the broadcast dedup log. */
 export type SyncOps = {
     addSyncPeer(peer: InsertSyncPeer): Promise<void>;
@@ -18,5 +28,11 @@ export type SyncOps = {
         version: string;
         mlsGroupID: string;
     }): Promise<boolean>;
+    /**
+     * Delete up to `limit` rows broadcast before `olderThan` and return how many went. One
+     * statement, no transaction of its own: safe inside a caller's. A pruned row only dedups
+     * sends, so the next send of its version goes out again as a duplicate.
+     */
+    pruneBroadcastLog(params: PruneBroadcastLogParams): Promise<number>;
 };
 export declare function createSyncOps(db: Kysely<P2PStoreTables>, adapter: Adapter): SyncOps;

package/lib/ops/sync.js

@@ -1,4 +1,13 @@
 import { normalizeDID } from '@kokuin/token';
+export class BroadcastLogPruneParamsError extends Error {
+    get code() {
+        return 'P2P_BROADCAST_LOG_PRUNE_PARAMS';
+    }
+    constructor(message){
+        super(message);
+        this.name = 'BroadcastLogPruneParamsError';
+    }
+}
 export function createSyncOps(db, adapter) {
     return {
         async addSyncPeer (peer) {
@@ -47,6 +56,22 @@ export function createSyncOps(db, adapter) {
         async hasBroadcast (entry) {
             const row = await db.selectFrom('kubun_p2p_broadcast_log').select('doc_id').where('doc_id', '=', entry.docID).where('version', '=', entry.version).where('mls_group_id', '=', entry.mlsGroupID).limit(1).executeTakeFirst();
             return row != null;
+        },
+        async pruneBroadcastLog (params) {
+            if (!Number.isFinite(params.olderThan)) {
+                throw new BroadcastLogPruneParamsError('pruneBroadcastLog: olderThan must be finite');
+            }
+            // SQLite reads a negative LIMIT as no limit.
+            if (!Number.isInteger(params.limit) || params.limit <= 0) {
+                throw new BroadcastLogPruneParamsError('pruneBroadcastLog: limit must be a positive integer');
+            }
+            const before = adapter.encodeTimestamp(new Date(params.olderThan));
+            const result = await db.deleteFrom('kubun_p2p_broadcast_log').where((eb)=>eb(eb.refTuple('doc_id', 'version', 'mls_group_id'), 'in', eb.selectFrom('kubun_p2p_broadcast_log').select([
+                    'doc_id',
+                    'version',
+                    'mls_group_id'
+                ]).where('broadcast_at', '<', before).limit(params.limit).$asTuple('doc_id', 'version', 'mls_group_id'))).executeTakeFirst();
+            return Number(result?.numDeletedRows ?? 0n);
         }
     };
 }