@meshline/sdk 0.0.0-stage → 0.1.0-alpha.1

package/src/groups/operations.ts

@@ -0,0 +1,145 @@
+import { ProtocolError, StateConflictError } from '../errors.js';
+import { validateAccountId } from '../identity/neo.js';
+import { groupApplicationCodec, groupCreateRequestCodec, groupEventCodec, groupInviteCodec, groupManagementPayloadCodec, groupMemberRecoveryRequestCodec, groupStateCodec, validateGroupApplication, validateGroupCreateRequest, validateGroupInvite, validateGroupManagementPayload, validateGroupMemberRecoveryRequest, validateGroupState, type GroupState } from '../models/group-management.js';
+import { groupAccountsRequestCodec, groupApplicationApproveRequestCodec, groupInviteQueryCodec, groupRecoveryApproveRequestCodec, groupRecoverySubmitResultCodec, validateGroupAccountsRequest, validateGroupApplicationApproveRequest, validateGroupInviteQuery, validateGroupRecoveryApproveRequest, validateGroupRecoverySubmitResult } from '../models/group-admission.js';
+import { groupMessageEnvelopeCodec, validateGroupMessageEnvelope, validateGroupRef, type GroupRef } from '../models/groups.js';
+import type { NetworkContext } from '../protocol/context.js';
+import { equalBytes } from '../protocol/encoding.js';
+import { canonicalJson, requireObject, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import type { MeshlineStore, RecordKey, StoreMutation } from '../storage/store.js';
+import { updateStore } from '../storage/transaction.js';
+import type { HttpMethod } from '../transport/http.js';
+import { decodeGroupProjection, groupAcceptanceKey, groupEventKey, groupKey } from './repository.js';
+import { groupMemberSecretKey, groupRotationKey, type PreparedGroupMemberKey } from './secrets.js';
+
+export const groupOperationMethods = {
+    'group.create': 'POST', 'group.update': 'PATCH', 'group.close': 'DELETE', 'group.message.send': 'POST',
+    'group.member.leave': 'DELETE', 'group.member.remove': 'DELETE', 'group.member.ban': 'PUT', 'group.member.unban': 'DELETE',
+    'group.role.update': 'PUT', 'group.owner.transfer': 'POST',
+    'group.invite.create': 'POST', 'group.invite.revoke': 'DELETE',
+    'group.application.submit': 'POST', 'group.application.approve': 'POST', 'group.application.reject': 'DELETE',
+    'group.member.recovery.submit': 'POST', 'group.member.recovery.approve': 'POST', 'group.member.recovery.reject': 'DELETE',
+    'group.secret.rotation.commit': 'POST',
+} as const satisfies Record<string, HttpMethod>;
+export type GroupOperationMethod = keyof typeof groupOperationMethods;
+export interface GroupOperation { readonly group: GroupRef; readonly method: GroupOperationMethod; readonly request: JsonObject; readonly accepted?: true; readonly acceptedSequence?: number; readonly acceptedResult?: JsonObject }
+const key = (operation: Pick<GroupOperation, 'group' | 'method'>): RecordKey => ({ collection: 'group_operations', key: `${operation.group.groupId}|${operation.method}` });
+const put = (record: RecordKey, value: JsonObject): StoreMutation => ({ ...record, kind: 'put', value });
+export function groupOperationPayload(operation: GroupOperation): JsonObject | undefined {
+    validateGroupRef(operation.group); if (!Object.hasOwn(groupOperationMethods, operation.method)) throw new ProtocolError('invalid_operation', 'Unknown stored group operation.');
+    let payload: JsonObject | undefined;
+    if (operation.method === 'group.create') { const request = groupCreateRequestCodec.decode(operation.request); validateGroupCreateRequest(request); payload = requireObject(operation.request.create!); }
+    else if (operation.method === 'group.invite.create') { const request = groupInviteCodec.decode(operation.request); validateGroupInvite(request, request.createdAt); }
+    else if (operation.method === 'group.invite.revoke') validateGroupInviteQuery(groupInviteQueryCodec.decode(operation.request));
+    else if (operation.method === 'group.application.submit') validateGroupApplication(groupApplicationCodec.decode(operation.request));
+    else if (operation.method === 'group.member.recovery.submit') validateGroupMemberRecoveryRequest(groupMemberRecoveryRequestCodec.decode(operation.request));
+    else if (operation.method === 'group.application.reject' || operation.method === 'group.member.recovery.reject') validateGroupAccountsRequest(groupAccountsRequestCodec.decode(operation.request));
+    else if (operation.method === 'group.application.approve') { validateGroupApplicationApproveRequest(groupApplicationApproveRequestCodec.decode(operation.request)); payload = requireObject(operation.request.approval!); }
+    else if (operation.method === 'group.member.recovery.approve') { validateGroupRecoveryApproveRequest(groupRecoveryApproveRequestCodec.decode(operation.request)); payload = requireObject(operation.request.approval!); }
+    else if (operation.method === 'group.message.send') { validateGroupMessageEnvelope(groupMessageEnvelopeCodec.decode(operation.request)); payload = operation.request; }
+    else {
+        const value = groupManagementPayloadCodec.decode(operation.request); validateGroupManagementPayload(value);
+        const expected: Partial<Record<GroupOperationMethod, typeof value.kind>> = { 'group.update': 'update', 'group.close': 'close', 'group.member.leave': 'memberLeave', 'group.member.remove': 'memberRemoval', 'group.member.ban': 'memberBan', 'group.member.unban': 'memberUnban', 'group.role.update': 'roleUpdate', 'group.owner.transfer': 'ownerTransfer', 'group.secret.rotation.commit': 'secretRotation' };
+        if (value.kind !== expected[operation.method]) throw new ProtocolError('invalid_operation', 'Stored operation method and signed payload differ.'); payload = operation.request;
+    }
+    if ((payload ?? operation.request).group_id !== operation.group.groupId) throw new ProtocolError('invalid_binding', 'Stored operation belongs to another group.');
+    if (operation.acceptedSequence !== undefined) { requireSafeInteger(operation.acceptedSequence, 1); if (operation.method !== 'group.message.send' || !operation.accepted) throw new ProtocolError('invalid_operation', 'Unexpected group operation sequence acknowledgement.'); }
+    if (operation.acceptedResult !== undefined) {
+        if (operation.method !== 'group.member.recovery.submit' || !operation.accepted) throw new ProtocolError('invalid_operation', 'Unexpected group operation acceptance result.');
+        validateGroupRecoverySubmitResult(groupRecoverySubmitResultCodec.decode(operation.acceptedResult));
+    }
+    return payload;
+}
+function encode(operation: GroupOperation): JsonObject { return { groupId: operation.group.groupId, relayId: operation.group.relayId, method: operation.method, request: operation.request, ...(operation.accepted ? { accepted: true } : {}), ...(operation.acceptedSequence === undefined ? {} : { acceptedSequence: operation.acceptedSequence }), ...(operation.acceptedResult === undefined ? {} : { acceptedResult: operation.acceptedResult }) }; }
+function decode(value: JsonObject): GroupOperation {
+    if (typeof value.groupId !== 'string' || typeof value.relayId !== 'string' || typeof value.method !== 'string' || value.accepted !== undefined && value.accepted !== true) throw new ProtocolError('invalid_storage', 'Malformed stored group operation.');
+    const operation: GroupOperation = { group: { groupId: value.groupId, relayId: value.relayId }, method: value.method as GroupOperationMethod, request: requireObject(value.request!), ...(value.accepted ? { accepted: true } : {}), ...(value.acceptedSequence === undefined ? {} : { acceptedSequence: value.acceptedSequence as number }), ...(value.acceptedResult === undefined ? {} : { acceptedResult: requireObject(value.acceptedResult) }) };
+    groupOperationPayload(operation); return operation;
+}
+const same = (a: GroupOperation, b: GroupOperation): boolean => a.group.relayId === b.group.relayId && canonicalJson(a.request) === canonicalJson(b.request);
+
+/** Exact signed requests survive uncertain responses; positive receipts are durable before any follow-up I/O. */
+export class GroupOperations {
+    constructor(readonly store: MeshlineStore, readonly context: NetworkContext, readonly accountId: string) { validateAccountId(accountId); }
+    async all(signal?: AbortSignal): Promise<readonly GroupOperation[]> { return (await this.store.read([{ collection: 'group_operations' }], signal)).sets[0]!.map(row => { const value = decode(row.value); if (key(value).key !== row.key) throw new ProtocolError('invalid_storage', 'Group operation key differs from its record.'); return value; }); }
+    async ensureAvailable(group: GroupRef, method: GroupOperationMethod, signal?: AbortSignal): Promise<void> {
+        if ((await this.store.read([key({ group, method })], signal)).sets[0]!.length) throw new StateConflictError('An earlier group operation is awaiting confirmation; start the manager to recover it.');
+    }
+    async save(operation: GroupOperation, member: PreparedGroupMemberKey | undefined, signal?: AbortSignal, preview?: GroupState): Promise<void> {
+        operation = decode(encode(operation)); const queries = [key(operation), groupKey(operation.group)];
+        const previewWire = preview === undefined ? undefined : groupStateCodec.encode(preview);
+        if (preview) { validateGroupState(preview); if (preview.groupId !== operation.group.groupId) throw new ProtocolError('invalid_binding', 'Group preview belongs to another group.'); }
+        if (member) { if (member.group.groupId !== operation.group.groupId || member.group.relayId !== operation.group.relayId) throw new ProtocolError('invalid_binding', 'Prepared member key belongs to another group.'); queries.push(groupMemberSecretKey(member.group.groupId, member.publicKey)); }
+        await updateStore(this.store, queries, snapshot => {
+            if (snapshot.sets[0]!.length) throw new StateConflictError('An earlier group operation is awaiting confirmation.');
+            const group = snapshot.sets[1]![0]?.value;
+            if (group && group.relayId !== operation.group.relayId) throw new ProtocolError('invalid_binding', 'Stored group belongs to another hosting relay.');
+            const mutations: StoreMutation[] = [put(key(operation), encode(operation))];
+            if (!group || previewWire && !group.projection) mutations.push(put(groupKey(operation.group), { ...group, relayId: operation.group.relayId, ...(previewWire ? { preview: previewWire } : {}) }));
+            if (member) {
+                if (snapshot.sets[2]!.length) throw new StateConflictError('Prepared member key already exists.');
+                mutations.push(put(queries[2]!, { publicKey: queries[2]!.key.split('|')[1]!, protectedKey: member.protectedKey, shared: false }));
+            }
+            return { mutations, result: undefined };
+        }, signal);
+    }
+    async acknowledge(operation: GroupOperation, acceptedSequence?: number, acceptedResult?: JsonObject): Promise<GroupOperation> {
+        if (acceptedSequence !== undefined) requireSafeInteger(acceptedSequence, 1);
+        return updateStore(this.store, [key(operation)], snapshot => {
+            const row = snapshot.sets[0]![0]; if (!row) throw new StateConflictError('Group operation disappeared before its acceptance was recorded.'); const current = decode(row.value);
+            if (!same(current, operation) || current.acceptedSequence !== undefined && current.acceptedSequence !== acceptedSequence || current.acceptedResult !== undefined && canonicalJson(current.acceptedResult) !== canonicalJson(acceptedResult ?? null)) throw new StateConflictError('Group operation acknowledgement conflicts with the pending request.');
+            const result: GroupOperation = { ...current, accepted: true, ...(acceptedSequence === undefined ? {} : { acceptedSequence }), ...(acceptedResult === undefined ? {} : { acceptedResult }) }; groupOperationPayload(result);
+            return { mutations: [put(key(operation), encode(result))], result };
+        });
+    }
+    async acceptedEvent(operation: GroupOperation, signal?: AbortSignal): Promise<{ sequence: number; record: JsonObject } | undefined> {
+        const payload = groupOperationPayload(operation); if (!payload) return undefined;
+        const row = (await this.store.read([groupAcceptanceKey(operation.group, payload, this.context)], signal)).sets[0]![0]; if (!row) return undefined;
+        requireSafeInteger(row.value.sequence, 0); const sequence = row.value.sequence;
+        const record = (await this.store.read([groupEventKey(operation.group, sequence)], signal)).sets[0]![0]?.value;
+        if (!record || canonicalJson(groupEventCodec.decode(record.event!).payload) !== canonicalJson(payload)) throw new ProtocolError('invalid_storage', 'Group acceptance evidence differs from its indexed signed payload.');
+        if (operation.acceptedSequence !== undefined && operation.acceptedSequence !== sequence) throw new ProtocolError('conflicting_acknowledgement', 'Relay acknowledgement and verified group message sequence differ.');
+        return { sequence, record };
+    }
+    /** Approval can outlive a lost or malformed submission acknowledgement. */
+    async acceptedMemberRequest(operation: GroupOperation, signal?: AbortSignal): Promise<boolean> {
+        const recovery = operation.method === 'group.member.recovery.submit';
+        if (!recovery && operation.method !== 'group.application.submit') return false;
+        const request = recovery ? groupMemberRecoveryRequestCodec.decode(operation.request) : groupApplicationCodec.decode(operation.request);
+        if (request.account !== this.accountId) throw new ProtocolError('invalid_binding', 'Pending member request belongs to another account.');
+        const snapshot = await this.store.read([groupKey(operation.group), { collection: 'group_events', prefix: `${operation.group.groupId}|` }], signal);
+        const group = snapshot.sets[0]![0]?.value;
+        if (!group?.projection) return false;
+        if (group.relayId !== operation.group.relayId) throw new ProtocolError('invalid_binding', 'Pending member request belongs to another hosting relay.');
+        const projection = decodeGroupProjection(requireObject(group.projection), operation.group);
+        for (const row of snapshot.sets[1]!) {
+            if (row.value.rejection !== undefined) continue;
+            const event = groupEventCodec.decode(row.value.event!);
+            if (event.payload.$type !== (recovery ? 'meshline.group.member.recovery.approval' : 'meshline.group.application.approval')) continue;
+            const approval = groupManagementPayloadCodec.decode(event.payload);
+            if (approval.kind !== 'applicationApproval' && approval.kind !== 'memberRecoveryApproval') continue;
+            if (approval.value.groupId !== operation.group.groupId
+                || !approval.value.members.some(member => member.account === request.account && equalBytes(member.memberEncryptionPublicKey, request.memberEncryptionPublicKey))) continue;
+            const index = (await this.store.read([groupAcceptanceKey(operation.group, event.payload, this.context)], signal)).sets[0]![0];
+            if (!event.signerDeviceId || event.sequence > projection.sequence || row.key !== groupEventKey(operation.group, event.sequence).key || index?.value.sequence !== event.sequence) throw new ProtocolError('invalid_storage', 'Member request approval is not indexed in verified group history.');
+            return true;
+        }
+        return false;
+    }
+    /** The caller supplies verified evidence or a positive acknowledgement. Rejections never erase an earlier uncertain operation. */
+    async complete(operation: GroupOperation, localEffect = false): Promise<JsonObject | undefined> {
+        return updateStore(this.store, [key(operation), groupKey(operation.group), groupRotationKey(operation.group)], snapshot => {
+            const row = snapshot.sets[0]![0]; if (!row) return { mutations: [], result: undefined };
+            if (!same(decode(row.value), operation)) throw new StateConflictError('Pending group request changed before completion.');
+            const mutations: StoreMutation[] = [{ kind: 'delete', ...key(operation) }]; const group = snapshot.sets[1]![0]?.value;
+            if (localEffect && group) {
+                if (operation.method === 'group.close') mutations.push(put(groupKey(operation.group), { ...group, locallyClosed: true }));
+                if (operation.method === 'group.member.leave') mutations.push(put(groupKey(operation.group), { ...group, localDepartureAfter: requireObject(group.projection!).sequence! }));
+                if (operation.method === 'group.application.submit' && (!group.projection || !decodeGroupProjection(requireObject(group.projection), operation.group).members.some(member => member.account === this.accountId))) mutations.push(put(groupKey(operation.group), { ...group, pendingApplication: true }));
+                if (operation.method === 'group.secret.rotation.commit' && snapshot.sets[2]![0]?.value.commitment === operation.request.client_secret_commitment) mutations.push({ kind: 'delete', ...groupRotationKey(operation.group) });
+            }
+            const change = mutations.find(mutation => mutation.collection === 'groups' && mutation.kind === 'put');
+            return { mutations, result: change?.kind === 'put' ? change.value : undefined };
+        });
+    }
+}

package/src/groups/repository.ts

@@ -0,0 +1,161 @@
+import { ProtocolError, StateConflictError } from '../errors.js';
+import { groupManagementHash } from '../crypto/groups.js';
+import { validateAccountId } from '../identity/neo.js';
+import { contentHashBytes } from '../models/content.js';
+import { groupEventCodec, groupMemberCodec, groupStateCodec, groupSyncPageCodec, validateGroupState, validateGroupSyncPage, type GroupEvent, type GroupSequenceQuery, type GroupSyncPage } from '../models/group-management.js';
+import { groupKeyEntryCodec, groupKeyPageCodec, validateGroupKeyPage, type GroupKeyEntry, type GroupKeyPage } from '../models/group-keys.js';
+import { validateGroupRef, type GroupRef } from '../models/groups.js';
+import { certificateId, deviceCertificateCodec } from '../models/identity.js';
+import type { NetworkContext } from '../protocol/context.js';
+import { decodeBase64Url, encodeBase64Url, equalBytes } from '../protocol/encoding.js';
+import { canonicalJson, requireObject, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import { requireLength } from '../crypto/primitives.js';
+import type { MeshlineStore, RecordKey, StoreMutation, StoredRecord } from '../storage/store.js';
+import { updateStore } from '../storage/transaction.js';
+import { applyGroupEvent, groupChangeKinds, type GroupChangeKind, type GroupDeparture, type GroupEventResult, type GroupProjectedMember, type GroupProjection } from './state.js';
+
+export interface GroupEpochRecord { readonly group: GroupRef; readonly epoch: number; readonly commitment: string; readonly memberPublicKey?: Uint8Array; readonly keyEntry?: GroupKeyEntry }
+export interface GroupPageResult { readonly projection?: GroupProjection; readonly hasMore: boolean; readonly rejected: readonly { readonly sequence: number; readonly error: ProtocolError }[]; readonly messageSequences: readonly number[];
+    readonly change?: { readonly record: JsonObject; readonly kinds: readonly GroupChangeKind[] } }
+export interface GroupTimelineSource { read(query: GroupSequenceQuery, signal?: AbortSignal): Promise<GroupSyncPage> }
+const index = (value: number): string => { requireSafeInteger(value, 0); return String(value).padStart(16, '0'); };
+export const groupKey = (group: GroupRef): RecordKey => ({ collection: 'groups', key: group.groupId });
+export const groupEventKey = (group: GroupRef, sequence: number): RecordKey => ({ collection: 'group_events', key: `${group.groupId}|${index(sequence)}` });
+export const groupEpochKey = (group: GroupRef, epoch: number): RecordKey => ({ collection: 'group_epochs', key: `${group.groupId}|${index(epoch)}` });
+export const groupPendingMessageKey = (group: GroupRef, sequence: number): RecordKey => ({ collection: 'group_pending_messages', key: `${group.groupId}|${index(sequence)}` });
+export const groupAcceptanceKey = (group: GroupRef, payload: JsonObject, context: NetworkContext): RecordKey => ({ collection: 'group_acceptances', key: `${group.groupId}|${groupManagementHash(payload, context)}` });
+const messageKey = (group: GroupRef, sender: string, messageId: string): RecordKey => ({ collection: 'group_message_ids', key: `${group.groupId}|${sender}|${messageId}` });
+const put = (key: RecordKey, value: JsonObject): StoreMutation => ({ ...key, kind: 'put', value });
+const fingerprint = (value: JsonObject | undefined): string => canonicalJson(value ?? null);
+export function encodeGroupProjection(value: GroupProjection): JsonObject {
+    return { sequence: value.sequence, epoch: value.epoch, managementHash: value.managementHash, clientSecretCommitment: value.clientSecretCommitment, state: groupStateCodec.encode(value.state),
+        members: value.members.map(member => ({ ...groupMemberCodec.encode({ account: member.account, role: member.role, memberEncryptionPublicKey: member.memberEncryptionPublicKey }), joinedAtSequence: member.joinedAtSequence,
+            ...(member.nickname === undefined ? {} : { nickname: member.nickname }), ...(member.nicknameSequence === undefined ? {} : { nicknameSequence: member.nicknameSequence }) })), bans: [...value.bans], departures: { ...value.departures } };
+}
+/** Persisted projections are validated as local state, never accepted from a relay preview. */
+export function decodeGroupProjection(value: JsonObject, group: GroupRef): GroupProjection {
+    validateGroupRef(group); requireSafeInteger(value.sequence, 0); requireSafeInteger(value.epoch, 0); const sequence = value.sequence; const state = groupStateCodec.decode(value.state!); validateGroupState(state);
+    if (state.groupId !== group.groupId || typeof value.managementHash !== 'string' || typeof value.clientSecretCommitment !== 'string' || !Array.isArray(value.members) || !Array.isArray(value.bans)) throw new ProtocolError('invalid_storage', 'Malformed verified group state.');
+    contentHashBytes(value.managementHash); contentHashBytes(value.clientSecretCommitment); const seen = new Set<string>();
+    const members = value.members.map(item => {
+        const wire = { ...requireObject(item) }; const joinedAtSequence = wire.joinedAtSequence; const nickname = wire.nickname; const nicknameSequence = wire.nicknameSequence;
+        delete wire.joinedAtSequence; delete wire.nickname; delete wire.nicknameSequence;
+        const member = groupMemberCodec.decode(wire); validateAccountId(member.account); requireLength(member.memberEncryptionPublicKey, 32, 'Stored member public key'); requireSafeInteger(joinedAtSequence, 0);
+        if (joinedAtSequence > sequence || seen.has(member.account)) throw new ProtocolError('invalid_storage', 'Stored group member has an invalid join sequence or duplicate account.'); seen.add(member.account);
+        if (nickname !== undefined && typeof nickname !== 'string') throw new ProtocolError('invalid_storage', 'Stored nickname must be a string.');
+        if (nicknameSequence !== undefined) { requireSafeInteger(nicknameSequence, joinedAtSequence); if (nicknameSequence > sequence) throw new ProtocolError('invalid_storage', 'Stored nickname sequence exceeds group position.'); }
+        return { ...member, joinedAtSequence, ...(nickname === undefined ? {} : { nickname }), ...(nicknameSequence === undefined ? {} : { nicknameSequence }) } as GroupProjectedMember;
+    });
+    const bans = value.bans.map(item => { if (typeof item !== 'string') throw new ProtocolError('invalid_storage', 'Stored ban must name an account.'); validateAccountId(item); return item; });
+    if (new Set(bans).size !== bans.length || bans.some(account => seen.has(account)) || members.length !== state.memberCount || members.filter(member => member.role === 'owner').length !== 1 || members.find(member => member.role === 'owner')!.account !== state.owner) throw new ProtocolError('invalid_storage', 'Stored group membership, owner or bans are inconsistent.');
+    const departures: Record<string, GroupDeparture> = Object.create(null) as Record<string, GroupDeparture>;
+    for (const [account, departure] of Object.entries(requireObject(value.departures!))) {
+        validateAccountId(account); if (typeof departure !== 'string' || !['left', 'removed', 'banned', 'not_member'].includes(departure) || seen.has(account)) throw new ProtocolError('invalid_storage', 'Invalid stored departure.'); departures[account] = departure as GroupDeparture;
+    }
+    return { ...group, sequence: value.sequence, epoch: value.epoch, managementHash: value.managementHash, clientSecretCommitment: value.clientSecretCommitment, state, members, bans, departures };
+}
+function recordProjection(value: JsonObject | undefined, group: GroupRef): GroupProjection | undefined {
+    if (!value) return undefined; if (value.relayId !== group.relayId) throw new ProtocolError('invalid_binding', 'Stored group belongs to another hosting relay.');
+    return value.projection === undefined ? undefined : decodeGroupProjection(requireObject(value.projection), group);
+}
+function decodeEpoch(row: StoredRecord, group: GroupRef): GroupEpochRecord {
+    const value = row.value; requireSafeInteger(value.epoch, 0);
+    if (row.key !== groupEpochKey(group, value.epoch).key || typeof value.commitment !== 'string') throw new ProtocolError('invalid_storage', 'Stored group epoch has an invalid identity or commitment.'); contentHashBytes(value.commitment);
+    const memberPublicKey = value.memberPublicKey === undefined ? undefined : decodeBase64Url(String(value.memberPublicKey)); if (memberPublicKey) requireLength(memberPublicKey, 32, 'Epoch member public key');
+    const keyEntry = value.keyEntry === undefined ? undefined : groupKeyEntryCodec.decode(value.keyEntry);
+    if (keyEntry && keyEntry.epoch !== value.epoch) throw new ProtocolError('invalid_storage', 'Stored group key entry belongs to another epoch.');
+    return { group, epoch: value.epoch, commitment: value.commitment, ...(memberPublicKey ? { memberPublicKey } : {}), ...(keyEntry ? { keyEntry } : {}) };
+}
+
+/** Commits verified group state, epoch authority, signed evidence, deduplication and cursor in one CAS batch. */
+export class GroupRepository {
+    constructor(readonly store: MeshlineStore, readonly context: NetworkContext, readonly accountId: string) { validateAccountId(accountId); }
+    async get(group: GroupRef, signal?: AbortSignal): Promise<GroupProjection | undefined> { validateGroupRef(group); return recordProjection((await this.store.read([groupKey(group)], signal)).sets[0]![0]?.value, group); }
+    /** Pre-admission relay previews are presentation data and never replace verified history or establish epoch authority. */
+    async savePreview(group: GroupRef, source: ReturnType<typeof groupStateCodec.decode>, signal?: AbortSignal): Promise<void> {
+        group = { ...group }; validateGroupRef(group); const state = groupStateCodec.decode(groupStateCodec.encode(source)); validateGroupState(state);
+        if (state.groupId !== group.groupId) throw new ProtocolError('invalid_binding', 'Relay preview belongs to another group.');
+        await updateStore(this.store, [groupKey(group)], snapshot => {
+            const current = snapshot.sets[0]![0]?.value; recordProjection(current, group);
+            return { mutations: current?.projection ? [] : [put(groupKey(group), { ...current, relayId: group.relayId, preview: groupStateCodec.encode(state) })], result: undefined };
+        }, signal);
+    }
+    async event(group: GroupRef, sequence: number, signal?: AbortSignal): Promise<JsonObject | undefined> {
+        validateGroupRef(group); const snapshot = await this.store.read([groupKey(group), groupEventKey(group, sequence)], signal); recordProjection(snapshot.sets[0]![0]?.value, group); return snapshot.sets[1]![0]?.value;
+    }
+    async epochs(group: GroupRef, signal?: AbortSignal): Promise<readonly GroupEpochRecord[]> {
+        validateGroupRef(group); const snapshot = await this.store.read([groupKey(group), { collection: 'group_epochs', prefix: `${group.groupId}|` }], signal); recordProjection(snapshot.sets[0]![0]?.value, group); return snapshot.sets[1]!.map(row => decodeEpoch(row, group));
+    }
+    async keyProgress(group: GroupRef, signal?: AbortSignal): Promise<number> { const values = await this.epochs(group, signal); return values.reduce((after, entry) => entry.keyEntry ? Math.max(after, entry.epoch) : after, -1); }
+    async synchronizePage(group: GroupRef, source: GroupTimelineSource, signal?: AbortSignal): Promise<GroupPageResult> {
+        validateGroupRef(group); const initial = (await this.store.read([groupKey(group)], signal)).sets[0]![0]?.value; const before = recordProjection(initial, group);
+        const query = { groupId: group.groupId, after: before?.sequence ?? -1 };
+        const page = groupSyncPageCodec.decode(groupSyncPageCodec.encode(await source.read(query, signal))); validateGroupSyncPage(page, query, this.context);
+        const certificates = new Map(page.certificates.map(certificate => [certificateId(certificate, this.context), certificate]));
+        const verified: { entry: GroupEvent; result: GroupEventResult; epochChanged: boolean }[] = []; let projection = before;
+        for (const entry of page.events) {
+            const result = applyGroupEvent(projection, entry, entry.signerDeviceId === undefined ? undefined : certificates.get(entry.signerDeviceId), group, this.context);
+            verified.push({ entry, result, epochChanged: projection?.epoch !== result.projection.epoch }); projection = result.projection;
+        }
+        const keys = new Map<string, RecordKey>(); const addKey = (key: RecordKey): void => { keys.set(`${key.collection}|${key.key}`, key); };
+        addKey(groupKey(group));
+        for (const item of verified) {
+            addKey(groupEventKey(group, item.entry.sequence)); if (item.epochChanged) addKey(groupEpochKey(group, item.entry.epoch));
+            const message = item.result.message; if (message) addKey(messageKey(group, message.sender.account, message.envelope.messageId));
+        }
+        const queries = [...keys.values()];
+        return updateStore(this.store, queries, snapshot => {
+            const rows = new Map(queries.map((key, i) => [`${key.collection}|${key.key}`, snapshot.sets[i]![0]]));
+            const row = (key: RecordKey) => rows.get(`${key.collection}|${key.key}`);
+            if (fingerprint(row(groupKey(group))?.value) !== fingerprint(initial)) throw new StateConflictError('Group state changed while its timeline was being verified.');
+            const mutations: StoreMutation[] = []; const rejected: { sequence: number; error: ProtocolError }[] = []; const messageSequences: number[] = []; const newMessages = new Set<string>();
+            for (const { entry, result, epochChanged } of verified) {
+                const key = groupEventKey(group, entry.sequence); if (row(key)) throw new ProtocolError('conflicting_event', 'Group event already exists beyond the verified cursor.');
+                let rejection = result.rejection; const message = result.message; const identity = message && messageKey(group, message.sender.account, message.envelope.messageId);
+                if (identity && (row(identity) || newMessages.has(identity.key))) rejection = new ProtocolError('duplicate_message', 'Relay assigned a second sequence to an existing logical group message.');
+                const certificate = entry.signerDeviceId === undefined ? undefined : certificates.get(entry.signerDeviceId)!;
+                const value: JsonObject = { event: groupEventCodec.encode(entry), ...(certificate ? { certificate: deviceCertificateCodec.encode(certificate) } : {}) };
+                if (rejection) { value.rejection = { code: rejection.code, message: rejection.message }; rejected.push({ sequence: entry.sequence, error: rejection }); }
+                else if (message && identity) {
+                    value.message = { sender: message.sender.account, messageId: message.envelope.messageId, senderDeviceId: message.signerDeviceId, createdAt: message.envelope.createdAt, joinedAtSequence: message.joinedAtSequence };
+                    newMessages.add(identity.key); mutations.push(put(identity, { sequence: entry.sequence }), put(groupPendingMessageKey(group, entry.sequence), { sequence: entry.sequence })); messageSequences.push(entry.sequence);
+                }
+                mutations.push(put(key, value));
+                if (!rejection && entry.signerDeviceId) mutations.push(put(groupAcceptanceKey(group, entry.payload, this.context), { sequence: entry.sequence }));
+                if (epochChanged) {
+                    const epochKey = groupEpochKey(group, entry.epoch); const old = row(epochKey)?.value; const memberPublicKey = result.projection.members.find(member => member.account === this.accountId)?.memberEncryptionPublicKey;
+                    if (old?.commitment !== undefined && (old.commitment !== result.projection.clientSecretCommitment || old.memberPublicKey !== (memberPublicKey && encodeBase64Url(memberPublicKey)))) throw new ProtocolError('conflicting_epoch', 'Stored group epoch authority conflicts with verified management history.');
+                    mutations.push(put(epochKey, { ...old, epoch: entry.epoch, commitment: result.projection.clientSecretCommitment, ...(memberPublicKey ? { memberPublicKey: encodeBase64Url(memberPublicKey) } : {}) }));
+                }
+            }
+            let change: GroupPageResult['change'];
+            if (verified.length) {
+                const ownerSequence = verified.filter(item => item.entry.payload.$type === 'meshline.group.owner.transfer').at(-1)?.entry.sequence ?? initial?.ownerSequence ?? 0;
+                const next: JsonObject = { ...initial, relayId: group.relayId, projection: encodeGroupProjection(projection!), ownerSequence };
+                if (projection!.members.some(member => member.account === this.accountId)) delete next.pendingApplication;
+                mutations.push(put(groupKey(group), next));
+                const kinds = groupChangeKinds.filter(kind => verified.some(item => item.result.changeKinds?.includes(kind)));
+                if (kinds.length) change = { record: next, kinds };
+            }
+            return { mutations, result: { ...(projection ? { projection } : {}), ...(change ? { change } : {}), hasMore: page.hasMore, rejected, messageSequences } };
+        }, signal);
+    }
+    /** Reuses an omitted client box only inside this page and only while both verified commitment and account key remain unchanged. */
+    async saveKeyPage(group: GroupRef, source: GroupKeyPage, after: number, signal?: AbortSignal): Promise<void> {
+        validateGroupRef(group); const page = groupKeyPageCodec.decode(groupKeyPageCodec.encode(source)); validateGroupKeyPage(page, after);
+        const keys = page.keys.map(entry => groupEpochKey(group, entry.epoch));
+        await updateStore(this.store, [groupKey(group), ...keys], snapshot => {
+            const projection = recordProjection(snapshot.sets[0]![0]?.value, group); const mutations: StoreMutation[] = []; let previous: GroupEpochRecord | undefined; let previousBox: GroupKeyEntry['clientSecretBox'];
+            for (let i = 0; i < page.keys.length; i++) {
+                const entry = page.keys[i]!; const row = snapshot.sets[i + 1]![0]; if (!projection || entry.epoch > projection.epoch || !row) throw new ProtocolError('unverified_epoch', 'Management history has not established this group key epoch.');
+                const epoch = decodeEpoch(row, group); if (!epoch.memberPublicKey) throw new ProtocolError('unauthorized_epoch', 'Group key epoch was not accessible to this account.');
+                const changed = !previous || previous.commitment !== epoch.commitment || !equalBytes(previous.memberPublicKey!, epoch.memberPublicKey);
+                if (changed && !entry.clientSecretBox) throw new ProtocolError('missing_secret_box', 'A changed verified commitment or member key requires a client secret box.');
+                const expanded = { ...entry, clientSecretBox: entry.clientSecretBox ?? previousBox! }; const wire = groupKeyEntryCodec.encode(expanded);
+                // Wrapping randomness is not an epoch identity. Derivation must compare any previously verified application secret before replacing it.
+                mutations.push(put(keys[i]!, { ...row.value, keyEntry: wire })); previous = epoch; previousBox = expanded.clientSecretBox;
+            }
+            return { mutations, result: undefined };
+        }, signal);
+    }
+}

package/src/groups/secrets.ts

@@ -0,0 +1,256 @@
+import { deriveGroupApplicationSecret, groupClientSecretBoxAad, groupClientSecretCommitment, groupRelaySecretBoxAad, GroupKeyAccessError, openGroupSecret } from '../crypto/groups.js';
+import { agreeKey, encryptionPublicKey, requireLength } from '../crypto/primitives.js';
+import type { MessageDecryptor } from '../crypto/messages.js';
+import { ProtocolError, StateConflictError } from '../errors.js';
+import { validateIdentifier } from '../identity/identifiers.js';
+import { validateAccountId } from '../identity/neo.js';
+import type { SecretProtector } from '../interactions.js';
+import { contentHashBytes } from '../models/content.js';
+import { groupKeyEntryCodec, validateGroupKeyEntry } from '../models/group-keys.js';
+import { groupHistorySecretCodec, groupMemberPrivateStateCodec, validateAccountGroupHistorySecretSync, validateAccountGroupPrivateStateSync, validateGroupMemberPrivateState, validateGroupRef, type GroupHistorySecret, type GroupMemberPrivateState, type GroupRef } from '../models/groups.js';
+import { certificateId, deviceCertificateCodec, validateCertificate } from '../models/identity.js';
+import type { NetworkContext } from '../protocol/context.js';
+import { decodeBase64Url, encodeBase64Url, equalBytes } from '../protocol/encoding.js';
+import { canonicalJson, requireObject, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import { throwIfAborted } from '../runtime/clock.js';
+import type { MeshlineStore, RecordKey, RecordQuery, StoreMutation, StoreSnapshot } from '../storage/store.js';
+import { updateStore } from '../storage/transaction.js';
+import { decodeGroupProjection, groupEpochKey, groupKey, GroupRepository } from './repository.js';
+import type { GroupApplicationSecrets } from './messages.js';
+
+const fingerprint = (value: JsonObject | undefined): string => canonicalJson(value ?? null);
+const put = (key: RecordKey, value: JsonObject): StoreMutation => ({ ...key, kind: 'put', value });
+export const groupMemberSecretKey = (groupId: string, publicKey: Uint8Array): RecordKey => ({ collection: 'group_member_keys', key: `${groupId}|${encodeBase64Url(publicKey)}` });
+export const groupApplicationSecretKey = (groupId: string, epoch: number): RecordKey => ({ collection: 'group_application_secrets', key: `${groupId}|${String(epoch).padStart(16, '0')}` });
+export const groupRotationKey = (group: GroupRef): RecordKey => ({ collection: 'group_rotations', key: group.groupId });
+const clientSecretKey = (groupId: string, commitment: string): RecordKey => ({ collection: 'group_client_secrets', key: `${groupId}|${commitment}` });
+export interface PreparedGroupMemberKey { readonly group: GroupRef; readonly publicKey: Uint8Array; readonly protectedKey: string; readonly deviceId: string }
+export interface GroupSecretEffect { readonly queries: readonly RecordQuery[]; plan(snapshot: StoreSnapshot): readonly StoreMutation[] }
+export interface GroupSecretsOptions { readonly store: MeshlineStore; readonly context: NetworkContext; readonly accountId: string; readonly deviceId: () => string; readonly protector: SecretProtector }
+export interface GroupKeyRecoveryResult { readonly derived: readonly number[]; readonly missing: readonly number[]; readonly rejected: readonly { readonly epoch: number; readonly error: ProtocolError }[] }
+export interface GroupRotation { readonly group: GroupRef; readonly baseCommitment: string; readonly commitment: string; readonly ownerSequence: number; readonly deviceId: string; readonly ownerPublicKey?: Uint8Array; readonly expiresAt?: number }
+function rotationRecord(value: JsonObject, group: GroupRef): GroupRotation {
+    validateGroupRef(group);
+    if (value.relayId !== group.relayId || typeof value.baseCommitment !== 'string' || typeof value.commitment !== 'string' || typeof value.deviceId !== 'string' || typeof value.protectedSecret !== 'string') throw new ProtocolError('invalid_storage', 'Stored rotation has inconsistent group, commitment or secret metadata.');
+    contentHashBytes(value.baseCommitment); contentHashBytes(value.commitment); validateIdentifier('device', value.deviceId); requireSafeInteger(value.ownerSequence, 0);
+    if (value.baseCommitment === value.commitment) throw new ProtocolError('invalid_storage', 'Stored rotation did not select a new secret.');
+    if (value.expiresAt !== undefined) requireSafeInteger(value.expiresAt, 1);
+    const ownerPublicKey = value.ownerPublicKey === undefined ? undefined : decodeBase64Url(String(value.ownerPublicKey)); if (ownerPublicKey) requireLength(ownerPublicKey, 32, 'Candidate owner public key');
+    return { group, baseCommitment: value.baseCommitment, commitment: value.commitment, ownerSequence: value.ownerSequence, deviceId: value.deviceId, ...(ownerPublicKey ? { ownerPublicKey } : {}), ...(value.expiresAt === undefined ? {} : { expiresAt: value.expiresAt }) };
+}
+
+/** Account-message authentication is the caller's responsibility; arriving keys never select current membership or advance verified history. */
+export class GroupSecrets implements GroupApplicationSecrets {
+    constructor(readonly options: GroupSecretsOptions) { validateAccountId(options.accountId); }
+    #purpose(groupId: string, kind: string, key: string): string {
+        validateIdentifier('group', groupId); const deviceId = this.options.deviceId(); validateIdentifier('device', deviceId);
+        return `Meshline/${this.options.context}/${this.options.accountId}/${deviceId}/group/${groupId}/${kind}/${key}`;
+    }
+    async #protect(secret: Uint8Array, purpose: string, signal?: AbortSignal): Promise<string> {
+        try {
+            const protectedData = await this.options.protector.protect(secret, purpose, signal); throwIfAborted(signal);
+            if (!(protectedData instanceof Uint8Array) || !protectedData.length) throw new Error('Secret protector returned empty data.'); return encodeBase64Url(protectedData);
+        } catch (cause) { throwIfAborted(signal); throw new GroupKeyAccessError('Local group secret protection failed.', { cause }); }
+    }
+    async #unprotect(value: JsonObject, field: string, purpose: string, signal?: AbortSignal): Promise<Uint8Array> {
+        let result: Uint8Array | undefined;
+        try {
+            if (typeof value[field] !== 'string') throw new Error('Protected group secret is missing.');
+            result = await this.options.protector.unprotect(decodeBase64Url(value[field]), purpose, signal); throwIfAborted(signal); requireLength(result, 32, 'Protected group secret'); return result;
+        } catch (cause) { if (result instanceof Uint8Array) result.fill(0); throwIfAborted(signal); throw new GroupKeyAccessError('Local group secret could not be restored.', { cause }); }
+    }
+    async prepareMemberState(source: GroupMemberPrivateState, signal?: AbortSignal): Promise<PreparedGroupMemberKey> {
+        const value = groupMemberPrivateStateCodec.decode(groupMemberPrivateStateCodec.encode(source));
+        try {
+            validateGroupMemberPrivateState(value); const deviceId = this.options.deviceId();
+            const group = { groupId: value.groupId, relayId: value.relayId }; const publicKey = encryptionPublicKey(value.memberEncryptionPrivateKey);
+            const purpose = this.#purpose(group.groupId, 'member', encodeBase64Url(publicKey));
+            const protectedKey = await this.#protect(value.memberEncryptionPrivateKey, purpose, signal);
+            if (purpose !== this.#purpose(group.groupId, 'member', encodeBase64Url(publicKey))) throw new GroupKeyAccessError('Local device changed during group key protection.');
+            return { group, publicKey, protectedKey, deviceId };
+        } finally { value.memberEncryptionPrivateKey.fill(0); }
+    }
+    /** Current and historical private keys coexist by derived public key; arrival order has no authority. */
+    async saveMemberState(source: GroupMemberPrivateState, signal?: AbortSignal): Promise<void> {
+        const effect = await this.prepareMemberStates([source], signal);
+        await updateStore(this.options.store, effect.queries, snapshot => ({ mutations: effect.plan(snapshot), result: undefined }), signal);
+    }
+    /** Prepared mutations can join an account-message consumer cursor in one atomic commit. */
+    async prepareMemberStates(sources: readonly GroupMemberPrivateState[], signal?: AbortSignal): Promise<GroupSecretEffect> {
+        const states = sources.map(source => groupMemberPrivateStateCodec.decode(groupMemberPrivateStateCodec.encode(source)));
+        try {
+            validateAccountGroupPrivateStateSync({ states }); const prepared: PreparedGroupMemberKey[] = [];
+            for (const state of states) prepared.push(await this.prepareMemberState(state, signal));
+            const queries = prepared.flatMap(value => [groupKey(value.group), groupMemberSecretKey(value.group.groupId, value.publicKey)]);
+            return { queries, plan: snapshot => {
+                const mutations: StoreMutation[] = [];
+                for (const [index, value] of prepared.entries()) {
+                    if (this.options.deviceId() !== value.deviceId) throw new GroupKeyAccessError('Local device changed before member key persistence.');
+                    const record = snapshot.sets[index * 2]![0]?.value; const existing = snapshot.sets[index * 2 + 1]![0]?.value; const publicKey = encodeBase64Url(value.publicKey);
+                    if (record && record.relayId !== value.group.relayId) throw new ProtocolError('invalid_binding', 'Private group state names another hosting relay.');
+                    if (existing && existing.publicKey !== publicKey) throw new ProtocolError('invalid_storage', 'Stored group member key does not match its identity.');
+                    if (!record) mutations.push(put(groupKey(value.group), { relayId: value.group.relayId }));
+                    if (!existing) mutations.push(put(groupMemberSecretKey(value.group.groupId, value.publicKey), { publicKey, protectedKey: value.protectedKey, shared: false }));
+                }
+                return mutations;
+            } };
+        } finally { for (const state of states) state.memberEncryptionPrivateKey.fill(0); }
+    }
+    async readMemberKey(groupId: string, publicKey: Uint8Array, signal?: AbortSignal): Promise<Uint8Array | undefined> {
+        validateIdentifier('group', groupId); requireLength(publicKey, 32, 'Member public key'); const key = publicKey.slice();
+        const row = (await this.options.store.read([groupMemberSecretKey(groupId, key)], signal)).sets[0]![0]?.value; if (!row) return undefined;
+        const purpose = this.#purpose(groupId, 'member', encodeBase64Url(key)); const privateKey = await this.#unprotect(row, 'protectedKey', purpose, signal);
+        try { if (row.publicKey !== encodeBase64Url(key) || !equalBytes(encryptionPublicKey(privateKey), key) || purpose !== this.#purpose(groupId, 'member', encodeBase64Url(key))) throw new GroupKeyAccessError('Restored group member key differs from its public identity.'); return privateKey; }
+        catch (error) { privateKey.fill(0); throw error; }
+    }
+    async stageHistorySecret(source: GroupHistorySecret, signal?: AbortSignal): Promise<void> {
+        const effect = await this.prepareHistorySecrets([source], signal);
+        await updateStore(this.options.store, effect.queries, snapshot => ({ mutations: effect.plan(snapshot), result: undefined }), signal);
+    }
+    async prepareHistorySecrets(sources: readonly GroupHistorySecret[], signal?: AbortSignal): Promise<GroupSecretEffect> {
+        const secrets = sources.map(source => groupHistorySecretCodec.decode(groupHistorySecretCodec.encode(source)));
+        try {
+            validateAccountGroupHistorySecretSync({ secrets }); const deviceId = this.options.deviceId();
+            const queries = secrets.map(value => groupApplicationSecretKey(value.groupId, value.epoch)); const initial = await this.options.store.read(queries, signal); const mutations: StoreMutation[] = [];
+            for (const [index, value] of secrets.entries()) {
+                const row = initial.sets[index]![0]?.value; const purpose = this.#purpose(value.groupId, 'epoch', String(value.epoch));
+                if (row) {
+                    if (row.epoch !== value.epoch) throw new ProtocolError('invalid_storage', 'Stored group secret belongs to another epoch.');
+                    const existing = await this.#unprotect(row, 'protectedSecret', purpose, signal);
+                    try { if (!equalBytes(existing, value.applicationSecret)) throw new ProtocolError('conflicting_epoch_secret', 'Account synchronization conflicts with a previously stored epoch secret.'); }
+                    finally { existing.fill(0); }
+                } else {
+                    const protectedSecret = await this.#protect(value.applicationSecret, purpose, signal);
+                    mutations.push(put(queries[index]!, { epoch: value.epoch, protectedSecret, source: 'account', shared: false }));
+                }
+                if (deviceId !== this.options.deviceId()) throw new GroupKeyAccessError('Local device changed during epoch secret preparation.');
+            }
+            return { queries, plan: snapshot => {
+                if (deviceId !== this.options.deviceId()) throw new GroupKeyAccessError('Local device changed before epoch secret persistence.');
+                if (snapshot.sets.some((rows, index) => fingerprint(rows[0]?.value) !== fingerprint(initial.sets[index]![0]?.value))) throw new StateConflictError('Group epoch secret changed while synchronization was being prepared.');
+                return mutations;
+            } };
+        } finally { for (const value of secrets) value.applicationSecret.fill(0); }
+    }
+    async readApplicationSecret(group: GroupRef, epoch: number, signal?: AbortSignal): Promise<Uint8Array | undefined> {
+        validateGroupRef(group); requireSafeInteger(epoch, 0); const snapshot = await this.options.store.read([groupKey(group), groupEpochKey(group, epoch), groupApplicationSecretKey(group.groupId, epoch)], signal);
+        const association = snapshot.sets[0]![0]?.value; if (association && association.relayId !== group.relayId) throw new ProtocolError('invalid_binding', 'Group secret belongs to another hosting relay.');
+        if (!association?.projection || !snapshot.sets[1]![0]?.value.commitment) return undefined;
+        const projection = decodeGroupProjection(requireObject(association.projection), group); if (epoch > projection.epoch) return undefined;
+        const row = snapshot.sets[2]![0]?.value; if (!row) return undefined; if (row.epoch !== epoch) throw new ProtocolError('invalid_storage', 'Stored group secret belongs to another epoch.');
+        const purpose = this.#purpose(group.groupId, 'epoch', String(epoch)); const secret = await this.#unprotect(row, 'protectedSecret', purpose, signal);
+        if (purpose !== this.#purpose(group.groupId, 'epoch', String(epoch))) { secret.fill(0); throw new GroupKeyAccessError('Local device changed during group secret restoration.'); } return secret;
+    }
+    async readClientSecret(group: GroupRef, commitment: string, signal?: AbortSignal): Promise<Uint8Array | undefined> {
+        validateGroupRef(group); contentHashBytes(commitment); const epochs = await new GroupRepository(this.options.store, this.options.context, this.options.accountId).epochs(group, signal);
+        if (!epochs.some(epoch => epoch.commitment === commitment)) return undefined;
+        const row = (await this.options.store.read([clientSecretKey(group.groupId, commitment)], signal)).sets[0]![0]?.value; if (!row) return undefined;
+        const purpose = this.#purpose(group.groupId, 'client', commitment); const secret = await this.#unprotect(row, 'protectedSecret', purpose, signal);
+        if (groupClientSecretCommitment(group.groupId, secret, this.options.context) !== commitment || purpose !== this.#purpose(group.groupId, 'client', commitment)) { secret.fill(0); throw new GroupKeyAccessError('Stored client secret does not match its verified commitment or local device.'); } return secret;
+    }
+    async rotation(group: GroupRef, signal?: AbortSignal): Promise<GroupRotation | undefined> {
+        group = { ...group }; validateGroupRef(group); const snapshot = await this.options.store.read([groupKey(group), groupRotationKey(group)], signal);
+        if (snapshot.sets[0]![0]?.value.relayId !== group.relayId) throw new ProtocolError('invalid_binding', 'Rotation group has no matching hosting association.');
+        const row = snapshot.sets[1]![0]?.value; return row && rotationRecord(row, group);
+    }
+    async beginRotation(group: GroupRef, baseCommitment: string, source: Uint8Array, member: PreparedGroupMemberKey | undefined, signal?: AbortSignal): Promise<GroupRotation> {
+        group = { ...group }; validateGroupRef(group); contentHashBytes(baseCommitment); const secret = source.slice();
+        try {
+            const commitment = groupClientSecretCommitment(group.groupId, secret, this.options.context); if (commitment === baseCommitment) throw new ProtocolError('unchanged_secret', 'Rotation requires a fresh client group secret.');
+            const deviceId = this.options.deviceId(); const purpose = this.#purpose(group.groupId, 'rotation', commitment); const protectedSecret = await this.#protect(secret, purpose, signal);
+            if (member && (member.group.groupId !== group.groupId || member.group.relayId !== group.relayId || member.deviceId !== deviceId)) throw new ProtocolError('invalid_binding', 'Rotation member key belongs to another group or local device.');
+            const queries = [groupKey(group), groupRotationKey(group), ...(member ? [groupMemberSecretKey(group.groupId, member.publicKey)] : [])];
+            return await updateStore(this.options.store, queries, snapshot => {
+                if (purpose !== this.#purpose(group.groupId, 'rotation', commitment)) throw new GroupKeyAccessError('Local rotation protection identity changed.');
+                const row = snapshot.sets[0]![0]?.value; if (row?.relayId !== group.relayId || !row.projection) throw new ProtocolError('unverified_group', 'Rotation requires verified group history.');
+                const state = decodeGroupProjection(requireObject(row.projection), group);
+                if (state.clientSecretCommitment !== baseCommitment || state.state.owner !== this.options.accountId || state.state.status !== 'active') throw new StateConflictError('Verified group secret or owner changed before rotation staging.');
+                if (snapshot.sets[1]!.length) throw new StateConflictError('A group secret rotation is already staged.');
+                const value: JsonObject = { relayId: group.relayId, baseCommitment, commitment, protectedSecret, deviceId, ownerSequence: row.ownerSequence ?? 0, ...(member ? { ownerPublicKey: encodeBase64Url(member.publicKey) } : {}) };
+                const result = rotationRecord(value, group); const mutations: StoreMutation[] = [put(groupRotationKey(group), value)];
+                if (member) { if (snapshot.sets[2]!.length) throw new StateConflictError('Candidate owner key already exists.'); mutations.push(put(queries[2]!, { publicKey: encodeBase64Url(member.publicKey), protectedKey: member.protectedKey, shared: false })); }
+                return { mutations, result };
+            }, signal);
+        } finally { secret.fill(0); }
+    }
+    async readRotationSecret(rotation: GroupRotation, signal?: AbortSignal): Promise<Uint8Array> {
+        const row = (await this.options.store.read([groupRotationKey(rotation.group)], signal)).sets[0]![0]?.value;
+        if (!row || row.commitment !== rotation.commitment || row.baseCommitment !== rotation.baseCommitment) throw new StateConflictError('Candidate group secret changed before restoration.');
+        const current = rotationRecord(row, rotation.group); if (current.deviceId !== this.options.deviceId()) throw new GroupKeyAccessError('Rotation belongs to another local device.');
+        const purpose = this.#purpose(rotation.group.groupId, 'rotation', rotation.commitment); const secret = await this.#unprotect(row, 'protectedSecret', purpose, signal);
+        if (purpose !== this.#purpose(rotation.group.groupId, 'rotation', rotation.commitment) || groupClientSecretCommitment(rotation.group.groupId, secret, this.options.context) !== rotation.commitment) { secret.fill(0); throw new GroupKeyAccessError('Restored candidate secret differs from its commitment or local identity.'); } return secret;
+    }
+    async acknowledgeRotation(rotation: GroupRotation, expiresAt: number): Promise<GroupRotation> {
+        requireSafeInteger(expiresAt, 1);
+        return updateStore(this.options.store, [groupRotationKey(rotation.group)], snapshot => {
+            const value = snapshot.sets[0]![0]?.value; if (!value || value.commitment !== rotation.commitment) throw new StateConflictError('Candidate rotation changed before preparation was acknowledged.');
+            const current = rotationRecord(value, rotation.group); if (current.expiresAt !== undefined && current.expiresAt !== expiresAt) throw new ProtocolError('conflicting_expiry', 'Relay changed the original rotation preparation expiry.');
+            const next = { ...value, expiresAt }; return { mutations: [put(groupRotationKey(rotation.group), next)], result: rotationRecord(next, rotation.group) };
+        });
+    }
+    async discardRotation(rotation: GroupRotation, signal?: AbortSignal): Promise<void> {
+        await updateStore(this.options.store, [groupRotationKey(rotation.group)], snapshot => {
+            const row = snapshot.sets[0]![0]?.value; if (row && row.commitment !== rotation.commitment) throw new StateConflictError('Another rotation replaced the obsolete candidate.');
+            return { mutations: row ? [{ kind: 'delete', ...groupRotationKey(rotation.group) }] : [], result: undefined };
+        }, signal);
+    }
+    async derivePending(group: GroupRef, device: MessageDecryptor, signal?: AbortSignal): Promise<GroupKeyRecoveryResult> {
+        const epochs = await new GroupRepository(this.options.store, this.options.context, this.options.accountId).epochs(group, signal);
+        const derived: number[] = []; const missing: number[] = []; const rejected: { epoch: number; error: ProtocolError }[] = [];
+        for (const epoch of epochs) {
+            if (!epoch.keyEntry || !epoch.memberPublicKey) continue;
+            try { const result = await this.#deriveEpoch(group, epoch.epoch, device, signal); if (result === 'derived') derived.push(epoch.epoch); if (result === 'missing') missing.push(epoch.epoch); }
+            catch (error) {
+                throwIfAborted(signal);
+                if (!(error instanceof ProtocolError) || !['invalid_ciphertext', 'invalid_key', 'invalid_commitment', 'conflicting_epoch_secret'].includes(error.code)) throw error;
+                rejected.push({ epoch: epoch.epoch, error });
+            }
+        }
+        return { derived, missing, rejected };
+    }
+    async #deriveEpoch(group: GroupRef, epoch: number, device: MessageDecryptor, signal?: AbortSignal): Promise<'derived' | 'missing' | 'ready'> {
+        const { store, context, accountId } = this.options; const first = (await store.read([groupEpochKey(group, epoch)], signal)).sets[0]![0]?.value;
+        if (!first || typeof first.commitment !== 'string' || typeof first.memberPublicKey !== 'string') throw new ProtocolError('invalid_storage', 'Group epoch has no verified secret authority.');
+        const commitment = first.commitment; contentHashBytes(commitment); const publicKey = decodeBase64Url(first.memberPublicKey); requireLength(publicKey, 32, 'Verified member public key');
+        const queries = [groupKey(group), groupEpochKey(group, epoch), groupMemberSecretKey(group.groupId, publicKey), groupApplicationSecretKey(group.groupId, epoch), clientSecretKey(group.groupId, commitment)];
+        const snapshot = await store.read(queries, signal); const [association, epochRow, member, application, client] = snapshot.sets.map(rows => rows[0]?.value);
+        if (association?.relayId !== group.relayId || !association.projection || !epochRow || fingerprint(epochRow) !== fingerprint(first)) throw new StateConflictError('Group key authority changed during recovery.');
+        if (decodeGroupProjection(requireObject(association.projection), group).epoch < epoch) throw new ProtocolError('invalid_storage', 'Group epoch has not been reached by verified history.');
+        const certificate = deviceCertificateCodec.decode(deviceCertificateCodec.encode(device.certificate)); validateCertificate(certificate, context); const deviceId = certificateId(certificate, context);
+        if (certificate.account !== accountId || deviceId !== this.options.deviceId()) throw new GroupKeyAccessError('Group key receiver belongs to another local account or device.');
+        if (epochRow.materialVerified === true && application && client) return 'ready';
+        if (!member) return 'missing';
+        const entry = groupKeyEntryCodec.decode(epochRow.keyEntry!); validateGroupKeyEntry(entry);
+        if (entry.epoch !== epoch || !entry.clientSecretBox || member.publicKey !== encodeBase64Url(publicKey)) throw new ProtocolError('invalid_storage', 'Stored group key entry or member key has inconsistent metadata.');
+        const memberPurpose = this.#purpose(group.groupId, 'member', encodeBase64Url(publicKey)); const clientPurpose = this.#purpose(group.groupId, 'client', commitment); const epochPurpose = this.#purpose(group.groupId, 'epoch', String(epoch));
+        const privateKey = await this.#unprotect(member, 'protectedKey', memberPurpose, signal);
+        let shared: Uint8Array | undefined; let clientSecret: Uint8Array | undefined; let relaySecret: Uint8Array | undefined; let secret: Uint8Array | undefined; let oldApplication: Uint8Array | undefined; let oldClient: Uint8Array | undefined;
+        try {
+            if (!equalBytes(encryptionPublicKey(privateKey), publicKey)) throw new GroupKeyAccessError('Restored member key differs from its verified public key.');
+            shared = agreeKey(privateKey, entry.clientSecretBox.enc);
+            clientSecret = openGroupSecret(entry.clientSecretBox, shared, groupClientSecretBoxAad({ groupId: group.groupId, account: accountId, memberEncryptionPublicKey: publicKey, clientSecretCommitment: commitment }, context));
+            if (groupClientSecretCommitment(group.groupId, clientSecret, context) !== commitment) throw new ProtocolError('invalid_commitment', 'Unwrapped client secret differs from the verified commitment.');
+            shared.fill(0); shared = undefined;
+            const probe = agreeKey(new Uint8Array(32).fill(1), entry.relaySecretBox.enc); probe.fill(0);
+            try {
+                shared = await device.deriveSharedSecret(entry.relaySecretBox.enc.slice(), signal); throwIfAborted(signal); requireLength(shared, 32, 'Device shared secret');
+                if (shared.every(byte => byte === 0) || certificateId(device.certificate, context) !== deviceId) throw new Error('Device key agreement returned invalid identity or key material.');
+            } catch (cause) { throwIfAborted(signal); throw new GroupKeyAccessError('Local device could not open the group relay-secret box.', { cause }); }
+            relaySecret = openGroupSecret(entry.relaySecretBox, shared, groupRelaySecretBoxAad({ groupId: group.groupId, account: accountId, deviceId, epoch }, context));
+            secret = deriveGroupApplicationSecret(group.groupId, epoch, commitment, clientSecret, relaySecret, context);
+            if (application) { oldApplication = await this.#unprotect(application, 'protectedSecret', epochPurpose, signal); if (!equalBytes(oldApplication, secret)) throw new ProtocolError('conflicting_epoch_secret', 'Derived group secret conflicts with a previously synchronized epoch secret.'); }
+            if (client) { oldClient = await this.#unprotect(client, 'protectedSecret', clientPurpose, signal); if (!equalBytes(oldClient, clientSecret)) throw new GroupKeyAccessError('Stored client secret conflicts with its verified commitment.'); }
+            const protectedSecret = application?.protectedSecret ?? await this.#protect(secret, epochPurpose, signal);
+            const protectedClient = client?.protectedSecret ?? await this.#protect(clientSecret, clientPurpose, signal);
+            await updateStore(store, queries, current => {
+                if (this.options.deviceId() !== deviceId) throw new GroupKeyAccessError('Local device changed before epoch secret persistence.');
+                if (current.sets.some((rows, i) => fingerprint(rows[0]?.value) !== fingerprint(snapshot.sets[i]![0]?.value))) throw new StateConflictError('Group key material changed while recovery was being prepared.');
+                return { mutations: [put(queries[1]!, { ...epochRow, materialVerified: true }), put(queries[3]!, { ...application, epoch, protectedSecret, source: 'derived' }),
+                    put(queries[4]!, { commitment, protectedSecret: protectedClient })], result: undefined };
+            }, signal);
+            return 'derived';
+        } finally {
+            privateKey.fill(0); if (shared instanceof Uint8Array) shared.fill(0); clientSecret?.fill(0); relaySecret?.fill(0); secret?.fill(0); oldApplication?.fill(0); oldClient?.fill(0);
+        }
+    }
+}