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

package/src/components/message.ts

@@ -0,0 +1,253 @@
+import { encryptMessage, decryptMessage } from '../crypto/messages.js';
+import { systemRandom, type RandomSource } from '../crypto/primitives.js';
+import { ProtocolError } from '../errors.js';
+import { certificateId, accountDeviceStateCodec, accountRouteCodec, authorizedDevice, validateDeviceState } from '../models/identity.js';
+import { createIdentifier, validateIdentifier } from '../identity/identifiers.js';
+import { validateAccountId } from '../identity/neo.js';
+import type { SecretProtector } from '../interactions.js';
+import { accountContactSyncCodec, contactAuthorizationCodec, contactConsentCodec, contactGrantCodec, verifyContactGrant, verifyContactInvite,
+    type ContactAuthorization, type ContactGrant, type ContactInvite } from '../models/contacts.js';
+import { directMessageCodec, messageDeliveryStatusCodec, messageSendRequestCodec, messageTimelineChangedCodec, validateDirectMessage, validateMessageTimelineChanged, type DirectMessage } from '../models/messages.js';
+import { MessageContacts, ContactMessageRejection, cachedDeviceStateKey, contactKey, contactRequestKey, readContact, readContactRequest,
+    type ContactChange, type ContactRequestChange, type ContactChanges, type ContactInfo, type ContactRequestDirection, type ContactRequestInfo, type PreparedContactSend } from '../messages/contacts.js';
+import { MessageOutbox, decodeOutbox, outboxStatus, type MessageSendState, type MessageSendStatus, type OutboxChange } from '../messages/outbox.js';
+import { MessageRepository, snapshotReader, type AccountMessage, type MessageInfo, type MessageKey } from '../messages/repository.js';
+import { MessageReceiver, type ReceptionResult } from '../messages/receiver.js';
+import { registerAccountSender } from '../messages/account-sender.js';
+import { requireObject, type JsonObject } from '../protocol/json.js';
+import { AsyncGate } from '../runtime/async-gate.js';
+import { AsyncPulse } from '../runtime/async-pulse.js';
+import { throwIfAborted } from '../runtime/clock.js';
+import { EventHub, type EventListener } from '../runtime/events.js';
+import type { MeshlineStore, QueryReader, RecordKey } from '../storage/store.js';
+import { readSignedRequest, requestKey } from '../storage/signed-request.js';
+import type { RelayClientPool } from '../transport/pool.js';
+import type { RelayClient } from '../transport/client.js';
+import type { AccountManager } from './account.js';
+import type { DeviceManager } from './device.js';
+import { ClientComponent, type ClientOptions } from './component.js';
+
+export interface MessageManagerOptions extends ClientOptions {
+    readonly store: MeshlineStore; readonly relayClients: RelayClientPool; readonly accountManager: AccountManager; readonly deviceManager: DeviceManager;
+    readonly secretProtector?: SecretProtector; readonly random?: RandomSource;
+}
+export interface MessageEvents {
+    readonly timelineChanged: undefined; readonly messageReceived: readonly MessageInfo[]; readonly sendStatusChanged: MessageSendStatus;
+    readonly contactChanged: ContactChange;
+    readonly contactRequestChanged: ContactRequestChange;
+}
+export interface OutboxQuery { readonly recipient?: string; readonly states?: readonly MessageSendState[] }
+export interface ContactRequestQuery { readonly accountId?: string; readonly direction?: ContactRequestDirection }
+const sendStates = new Set<MessageSendState>(['queued', 'submitting', 'submissionUnknown', 'relayAccepted', 'targetAccepted', 'failed', 'canceled']);
+const routeKey = (account: string): RecordKey => ({ collection: 'account_routes', key: account });
+
+/** Account messaging and contact relationships share durable authorization, delivery and synchronization transactions. */
+export class MessageManager extends ClientComponent {
+    readonly #store: MeshlineStore; readonly #pool: RelayClientPool; readonly #account: AccountManager; readonly #device: DeviceManager; readonly #random: RandomSource;
+    readonly #events = new EventHub<MessageEvents>(); readonly #writes = new AsyncGate();
+    readonly #repository: MessageRepository; readonly #contacts: MessageContacts; readonly #outbox: MessageOutbox; readonly #receiver: MessageReceiver;
+    readonly #deliveryGrants = new Map<string, ContactGrant>();
+    readonly #observed = new Map<string, { client: RelayClient; detach: (() => void)[] }>();
+    readonly #pendingRoutes = new Set<string>(); #routeRecording = Promise.resolve(); #removeRouteListener: (() => void) | undefined;
+    #sendPulse: AsyncPulse | undefined; #syncPulse: AsyncPulse | undefined; #maintenancePulse: AsyncPulse | undefined; #runtimeJobs: Promise<void>[] = [];
+    #pendingDeviceRevision: number | undefined; #deviceListeners: (() => void)[] = [];
+    constructor(options: MessageManagerOptions) {
+        super(options);
+        for (const dependency of [options.relayClients, options.accountManager, options.deviceManager]) if (dependency.accountId !== this.accountId || dependency.context.toString() !== this.context.toString())
+            throw new ProtocolError('invalid_context', 'Message dependencies belong to another account or network.');
+        this.#store = options.store; this.#pool = options.relayClients; this.#account = options.accountManager; this.#device = options.deviceManager; this.#random = options.random ?? systemRandom;
+        this.#repository = new MessageRepository({ store: this.#store, context: this.context, accountId: this.accountId, deviceId: () => certificateId(this.#device.certificate, this.context), clock: this.clock,
+            ...(options.secretProtector ? { secretProtector: options.secretProtector } : {}) });
+        this.#contacts = new MessageContacts({ store: this.#store, context: this.context, accountId: this.accountId, device: this.#device, clock: this.clock,
+            getState: (target, signal) => this.#getState(target, signal), prepareSend: (recipient, payload, authorization, devices, signal) => this.#prepareSend(recipient, payload, authorization, devices, signal),
+            changed: changes => this.#contactChanges(changes) });
+        this.#outbox = new MessageOutbox(this.#store, this.clock, {
+            getHome: async signal => { const route = await this.#account.getRoute(undefined, signal); if (!route) throw new ProtocolError('route_required', 'The account has no current route.'); return route.relayId; },
+            currentHome: () => this.#account.route?.relayId,
+            prepare: async (relayId, signal) => { const relay = await this.#pool.get(relayId, { mode: 'device', signer: this.#device }, signal); return {
+                send: async (request, token) => messageDeliveryStatusCodec.decode((await relay.requestHttp('POST', 'message.send', messageSendRequestCodec.encode(request), { ...(token ? { signal: token } : {}) }))!),
+                status: async (messageId, token) => messageDeliveryStatusCodec.decode((await relay.requestHttp('GET', 'message.delivery.status', { message_id: messageId }, { ...(token ? { signal: token } : {}) }))!),
+            }; },
+        }, this.#contacts.deliveryEffects(this.#deliveryGrants));
+        this.#receiver = new MessageReceiver(this.#repository, this.context, this.#device, { prepare: (entry, payload, signal) => this.#contacts.prepareReception(entry, payload, signal),
+            isPermanentRejection: (error): error is ContactMessageRejection => error instanceof ContactMessageRejection });
+        registerAccountSender(this, async (payload, devices, signal, effects) => {
+            await this.runOperation(scope => this.#writes.run(async () => {
+                const prepared = await this.#prepareSend(this.accountId, payload, undefined, devices, scope);
+                await this.#repository.enqueue(prepared.outbox, undefined, prepared.guards, effects, scope);
+            }, scope), signal);
+            this.#sendPulse?.pulse();
+        });
+    }
+    on<K extends keyof MessageEvents>(event: K, listener: EventListener<MessageEvents[K]>): () => void { return this.#events.on(event, listener); }
+    #notify<K extends keyof MessageEvents>(event: K, value: MessageEvents[K]): void {
+        this.#events.notify(event, value, error => this.notifyBackgroundError({ operation: 'observer', resource: event, error }));
+    }
+    #contactChanges(changes: ContactChanges): void {
+        for (const change of changes.contacts) this.#notify('contactChanged', change);
+        for (const change of changes.requests) this.#notify('contactRequestChanged', change);
+        this.#sendPulse?.pulse(); this.#maintenancePulse?.pulse();
+    }
+    protected override async onInitialize(signal: AbortSignal): Promise<void> {
+        this.#account.ensureInitialized(); this.#device.ensureInitialized(); await this.#store.initialize({ context: this.context.toString(), accountId: this.accountId }, signal);
+        await this.#outbox.recover(signal);
+        this.#removeRouteListener?.(); this.#removeRouteListener = this.#account.on('accountChanged', value => { if (value.route) this.#observeRoute(value.route.relayId); });
+        if (this.#account.route) this.#observeRoute(this.#account.route.relayId); await this.#routeRecording;
+    }
+    #observeRoute(relayId: string): void {
+        this.#pendingRoutes.add(relayId);
+        this.#routeRecording = this.#routeRecording.then(async () => {
+            for (const relay of [...this.#pendingRoutes]) { try { await this.#repository.observeRelay(relay); this.#pendingRoutes.delete(relay); }
+                catch (error) { this.notifyBackgroundError({ operation: 'record_route', resource: relay, error }); } }
+            this.#sendPulse?.pulse(); this.#syncPulse?.pulse();
+        });
+    }
+    async #getState(target: string | ContactAuthorization, signal?: AbortSignal) {
+        const state = await this.#device.getDeviceState(target, signal); if (!state) throw new ProtocolError('device_state_required', 'The requested account has no device state.'); return state;
+    }
+    async #prepareSend(recipient: string, payload: JsonObject, explicit: ContactAuthorization | undefined, deviceIds: readonly string[] | undefined, signal?: AbortSignal): Promise<PreparedContactSend> {
+        validateAccountId(recipient); const self = recipient === this.accountId;
+        const contactQueries = self ? [] : [contactKey(recipient), contactRequestKey(recipient, 'incoming')];
+        const before = await this.#store.read(contactQueries, signal);
+        const contact = self ? undefined : readContact(before.sets[0]![0]?.value); const incoming = self ? undefined : readContactRequest(before.sets[1]![0]?.value);
+        const authorization = explicit ?? (contact?.record.status === 'active' ? contact.record.grantFromContact : undefined) ?? incoming?.consent.grant;
+        if (payload['$type'] === 'meshline.message.direct' && !self && (!authorization || !('grantor' in authorization))) throw new ProtocolError('contact_required', 'A direct message requires a contact grant from its recipient.');
+        await this.#getState(this.accountId, signal); if (!self) await this.#getState(authorization ?? recipient, signal);
+        const queries = [routeKey(this.accountId), cachedDeviceStateKey(this.accountId), ...(self ? [] : [cachedDeviceStateKey(recipient)]), requestKey('device.state.publish')]; const snapshot = await this.#store.read(queries, signal);
+        const route = accountRouteCodec.decode(snapshot.sets[0]![0]?.value!); const own = accountDeviceStateCodec.decode(snapshot.sets[1]![0]?.value!);
+        const remote = self ? own : accountDeviceStateCodec.decode(snapshot.sets[2]![0]?.value!); const now = this.clock.nowSeconds();
+        validateDeviceState(own, this.context); validateDeviceState(remote, this.context);
+        const pendingState = readSignedRequest(snapshot.sets.at(-1)![0]?.value);
+        if (pendingState?.pending) {
+            const proposed = accountDeviceStateCodec.decode(pendingState.document); const ids = new Set(proposed.certificates.map(value => certificateId(value, this.context)));
+            if (own.certificates.some(value => !ids.has(certificateId(value, this.context)))) throw new ProtocolError('device_removal_pending', 'Resolve the pending device removal before preparing new messages or grants.');
+        }
+        if (route.account !== this.accountId || own.account !== this.accountId || remote.account !== recipient || route.expiresAt <= now) throw new ProtocolError('invalid_authorization', 'Message routing or device state is outside its account scope or validity.');
+        authorizedDevice(own, certificateId(this.#device.certificate, this.context), this.context, now);
+        if (authorization) { if ('grantor' in authorization) verifyContactGrant(authorization, remote, this.context, now); else verifyContactInvite(authorization, remote, this.context, now); }
+        let recipients = remote.certificates.filter(value => value.notBefore <= now && now < value.expiresAt);
+        if (deviceIds) { const selected = new Set(deviceIds); recipients = recipients.filter(value => selected.has(certificateId(value, this.context)));
+            if (recipients.length !== selected.size) throw new ProtocolError('unauthorized_device', 'A selected receiving device is no longer authorized.'); }
+        const request = await encryptMessage({ context: this.context, signer: this.#device, messageId: createIdentifier('message', this.#random), createdAt: now, recipient, payload,
+            recipientDevices: recipients, ...(self ? {} : { senderDevices: own.certificates.filter(value => value.notBefore <= now && now < value.expiresAt) }),
+            ...(authorization ? { authorization } : {}), random: this.#random, ...(signal ? { signal } : {}) });
+        return { outbox: { request, relayId: route.relayId, state: 'queued', nextAttemptAt: now, isDirect: payload['$type'] === 'meshline.message.direct' },
+            guards: [...queries.map((query, index) => ({ query, value: snapshot.sets[index]![0]?.value })), ...contactQueries.map((query, index) => ({ query, value: before.sets[index]![0]?.value }))] };
+    }
+    async sendMessage(recipient: string, draft: DirectMessage, signal?: AbortSignal): Promise<MessageSendStatus> {
+        const payload = directMessageCodec.encode(draft); validateDirectMessage(directMessageCodec.decode(payload));
+        const status = await this.runOperation(scope => this.#writes.run(async () => { const prepared = await this.#prepareSend(recipient, payload, undefined, undefined, scope);
+            const message = await this.#repository.prepare(prepared.outbox.request.envelope, payload, scope); await this.#repository.enqueue(prepared.outbox, message, prepared.guards, undefined, scope); return outboxStatus(prepared.outbox); }, scope), signal);
+        this.#sendPulse?.pulse(); this.#notify('timelineChanged', undefined); this.#notify('sendStatusChanged', status); return status;
+    }
+    getMessage(key: MessageKey, signal?: AbortSignal): Promise<MessageInfo | undefined> { const copy = { ...key }; return this.runOperation(scope => this.#repository.get(copy, scope), signal); }
+    getMessageHistory(peer?: string, signal?: AbortSignal): Promise<QueryReader<MessageInfo>> { return this.runOperation(scope => this.#repository.history(peer, scope), signal); }
+    readTimeline(after: number, count: number, signal?: AbortSignal): Promise<readonly AccountMessage[]> { return this.runOperation(scope => this.#repository.readTimeline(after, count, scope), signal); }
+    getOutbox(query: OutboxQuery = {}, signal?: AbortSignal): Promise<QueryReader<MessageSendStatus>> {
+        const recipient = query.recipient; const states = query.states && [...query.states]; if (recipient !== undefined) validateAccountId(recipient);
+        if (states?.some(value => !sendStates.has(value))) throw new TypeError('Unknown message send state.');
+        return this.runOperation(async scope => { const rows = await this.#store.read([{ collection: 'message_outbox' }], scope);
+            return snapshotReader(rows.sets[0]!.map(decodeOutbox).filter(value => value.isDirect && (recipient === undefined || value.request.envelope.to === recipient) && (states === undefined || states.includes(value.state)))
+                .sort((a, b) => a.request.envelope.createdAt - b.request.envelope.createdAt || ordinal(a.request.envelope.messageId, b.request.envelope.messageId)).map(outboxStatus)); }, signal);
+    }
+    getSendStatus(messageId: string, signal?: AbortSignal): Promise<MessageSendStatus | undefined> { return this.runOperation(async scope => { const record = await this.#outbox.get(messageId, scope); return record && outboxStatus(record); }, signal); }
+    async cancelMessage(messageId: string, signal?: AbortSignal): Promise<boolean> { const change = await this.runOperation(scope => this.#outbox.cancel(messageId, scope), signal); if (change) await this.#sendChanges([change]); return Boolean(change); }
+    createInvite(expiresAt: number, signal?: AbortSignal): Promise<ContactInvite> { return this.runOperation(scope => this.#contacts.invite(expiresAt, scope), signal); }
+    addContact(target: string | ContactInvite, note?: string, signal?: AbortSignal): Promise<ContactRequestInfo> {
+        const copy = typeof target === 'string' ? target : contactAuthorizationCodec.decode(contactAuthorizationCodec.encode(target)) as ContactInvite;
+        return this.runOperation(scope => this.#writes.run(() => this.#contacts.add(copy, note, scope), scope), signal);
+    }
+    acceptContactRequest(account: string, signal?: AbortSignal): Promise<ContactInfo> { return this.runOperation(scope => this.#writes.run(() => this.#contacts.accept(account, scope), scope), signal); }
+    dismissContactRequest(account: string, signal?: AbortSignal): Promise<void> { return this.runOperation(scope => this.#contacts.dismiss(account, scope), signal); }
+    getContacts(search?: string, signal?: AbortSignal): Promise<QueryReader<ContactInfo>> { return this.runOperation(scope => this.#contacts.list(search, scope), signal); }
+    getContact(account: string, signal?: AbortSignal): Promise<ContactInfo | undefined> { return this.runOperation(scope => this.#contacts.get(account, scope), signal); }
+    getContactRequests(query: ContactRequestQuery = {}, signal?: AbortSignal): Promise<QueryReader<ContactRequestInfo>> { const { accountId, direction } = query; return this.runOperation(scope => this.#contacts.requests(accountId, direction, scope), signal); }
+    setContactAlias(account: string, alias: string | null, signal?: AbortSignal): Promise<ContactInfo> { return this.runOperation(scope => this.#writes.run(() => this.#contacts.edit(account, { alias }, scope), scope), signal); }
+    removeContact(account: string, signal?: AbortSignal): Promise<void> { return this.runOperation(scope => this.#writes.run(() => this.#contacts.edit(account, { deleted: true }, scope), scope), signal); }
+    protected override async onStart(signal: AbortSignal): Promise<void> {
+        const own = await this.#getState(this.accountId, signal); authorizedDevice(own, certificateId(this.#device.certificate, this.context), this.context, this.clock.nowSeconds());
+        const initial = await this.#prepareSend(this.accountId, accountContactSyncCodec.encode({ records: [], requestSnapshot: true }), undefined, undefined, signal);
+        await this.#repository.enqueue(initial.outbox, undefined, initial.guards, undefined, signal);
+        this.#sendPulse = new AsyncPulse(); this.#syncPulse = new AsyncPulse(); this.#maintenancePulse = new AsyncPulse(); this.#pendingDeviceRevision = own.revision;
+        this.#deviceListeners = [this.#device.on('deviceChanged', () => { this.#maintenancePulse?.pulse(); }), this.#device.on('deviceStateChanged', value => {
+            if (value.account === this.accountId) { this.#pendingDeviceRevision = Math.max(value.revision, this.#pendingDeviceRevision ?? -1); this.#maintenancePulse?.pulse(); }
+        })];
+        this.#runtimeJobs = [this.#sendLoop(this.runtimeSignal), this.#syncLoop(this.runtimeSignal), this.#poll(this.runtimeSignal), this.#maintainContacts(this.runtimeSignal), this.#pollContacts(this.runtimeSignal)];
+        for (const job of this.#runtimeJobs) job.catch(() => undefined); this.#sendPulse.pulse(); this.#syncPulse.pulse(); this.#maintenancePulse.pulse();
+    }
+    async #poll(signal: AbortSignal): Promise<void> { try { for (;;) { await this.clock.delay(15_000, signal); this.#sendPulse?.pulse(); this.#syncPulse?.pulse(); } } catch (error) { if (!signal.aborted) throw error; } }
+    async #pollContacts(signal: AbortSignal): Promise<void> { try { for (;;) { await this.clock.delay(30_000, signal); this.#maintenancePulse?.pulse(); } } catch (error) { if (!signal.aborted) throw error; } }
+    async #maintainContacts(signal: AbortSignal): Promise<void> {
+        try { for (;;) {
+            await this.#maintenancePulse!.wait(signal); const revision = this.#pendingDeviceRevision; let failed = false;
+            try {
+                const rows = await this.#store.read([{ collection: 'contacts' }], signal);
+                for (const row of rows.sets[0]!) {
+                    if (readContact(row.value)?.record.status !== 'active') continue;
+                    try { await this.#contacts.maintain(row.key, revision, signal); }
+                    catch (error) { throwIfAborted(signal); failed = true; this.notifyBackgroundError({ operation: 'maintain_contact', resource: row.key, error }); }
+                }
+                if (!failed && this.#pendingDeviceRevision === revision) this.#pendingDeviceRevision = undefined;
+            } catch (error) { throwIfAborted(signal); this.notifyBackgroundError({ operation: 'maintain_contacts', error }); }
+        } } catch (error) { if (!signal.aborted) throw error; }
+    }
+    async #sendLoop(signal: AbortSignal): Promise<void> {
+        try { for (;;) {
+            await this.#sendPulse!.wait(signal);
+            try { for (const messageId of await this.#outbox.due(signal)) {
+                try {
+                const record = await this.#outbox.get(messageId, signal); if (!record) continue;
+                if (!record.isDirect && record.request.envelope.to !== this.accountId) {
+                    const box = record.request.senderBoxes?.find(value => value.deviceId === certificateId(this.#device.certificate, this.context));
+                    if (!box) throw new ProtocolError('missing_key_box', 'Outgoing protocol message has no local sender key box.');
+                    const payload = await decryptMessage({ context: this.context, receiver: this.#device, sender: this.#device.certificate, envelope: record.request.envelope, keyBox: box, signal });
+                    const grant = payload['$type'] === 'meshline.contact.consent' ? contactConsentCodec.decode(payload).grant : payload['$type'] === 'meshline.contact.grant' ? contactGrantCodec.decode(payload) : undefined;
+                    if (grant) this.#deliveryGrants.set(messageId, grant);
+                }
+                const result = await this.#outbox.process(messageId, signal); await this.#sendChanges(result.changes); if (result.error && !signal.aborted) this.notifyBackgroundError({ operation: 'send_message', resource: messageId, error: result.error });
+                } catch (error) { throwIfAborted(signal); this.notifyBackgroundError({ operation: 'send_message', resource: messageId, error }); }
+                finally { this.#deliveryGrants.delete(messageId); }
+            } } catch (error) { throwIfAborted(signal); this.notifyBackgroundError({ operation: 'send_message', error }); }
+        } } catch (error) { if (!signal.aborted) throw error; }
+    }
+    async #sendChanges(changes: readonly OutboxChange[]): Promise<void> {
+        for (const { current } of changes) {
+            if (current.isDirect) this.#notify('sendStatusChanged', outboxStatus(current));
+        }
+    }
+    async #syncLoop(signal: AbortSignal): Promise<void> {
+        try { for (;;) {
+            await this.#syncPulse!.wait(signal);
+            try {
+                try { await this.#account.getRoute(undefined, signal); } catch (error) { throwIfAborted(signal); this.notifyBackgroundError({ operation: 'resolve_route', error }); }
+                await this.#routeRecording;
+                const rows = await this.#store.read([{ collection: 'message_timelines' }], signal);
+                for (const row of rows.sets[0]!) {
+                    try { const client = await this.#pool.get(row.key, { mode: 'device', signer: this.#device }, signal); await this.#observeClient(client, signal);
+                        await this.#receiver.synchronize(row.key, { read: async (after, scope) => (await client.requestHttp('GET', 'message.timeline.sync', { after }, { ...(scope ? { signal: scope } : {}) }))! }, result => this.#received(row.key, result), signal);
+                    } catch (error) { throwIfAborted(signal); this.notifyBackgroundError({ operation: 'synchronize_messages', resource: row.key, error }); }
+                }
+            } catch (error) { throwIfAborted(signal); this.notifyBackgroundError({ operation: 'synchronize_messages', error }); }
+        } } catch (error) { if (!signal.aborted) throw error; }
+    }
+    async #observeClient(client: RelayClient, signal: AbortSignal): Promise<void> {
+        const previous = this.#observed.get(client.relayId); if (previous?.client === client) return;
+        const descriptor = await client.getDescriptor(signal); const detach = [client.on('notificationReceived', request => {
+            if (request.method !== 'message.timeline.changed') return; validateMessageTimelineChanged(messageTimelineChangedCodec.decode(requireObject(request.params!))); this.#syncPulse?.pulse();
+        }), client.on('socketConnected', () => { this.#syncPulse?.pulse(); }), client.on('errorOccurred', error => this.notifyBackgroundError({ operation: 'connect', resource: client.relayId, error }))];
+        for (const remove of previous?.detach ?? []) remove(); this.#observed.set(client.relayId, { client, detach });
+        if (descriptor.endpoints.some(value => value.startsWith('wss://'))) client.startNotifications();
+    }
+    #received(relayId: string, result: ReceptionResult): void {
+        if (result.inserted) this.#notify('timelineChanged', undefined); if (result.messages.length) this.#notify('messageReceived', result.messages);
+        for (const rejection of result.rejected) this.notifyBackgroundError({ operation: 'reject_message', resource: `${relayId}/${rejection.sequence}`, error: rejection.error });
+        this.#sendPulse?.pulse();
+    }
+    protected override async onStop(): Promise<void> {
+        try { const results = await Promise.allSettled(this.#runtimeJobs); const failures = results.filter((value): value is PromiseRejectedResult => value.status === 'rejected'); if (failures.length) throw new AggregateError(failures.map(value => value.reason), 'Message runtime failed.'); }
+        finally { for (const observed of this.#observed.values()) for (const remove of observed.detach) remove(); this.#observed.clear();
+            for (const remove of this.#deviceListeners) remove(); this.#deviceListeners = []; this.#runtimeJobs = []; this.#sendPulse = this.#syncPulse = this.#maintenancePulse = undefined; this.#pendingDeviceRevision = undefined; }
+    }
+    protected override async onDispose(): Promise<void> { this.#removeRouteListener?.(); this.#removeRouteListener = undefined; await this.#routeRecording; if (this.#pendingRoutes.size) throw new Error('Some observed message timelines could not be persisted.'); this.#events.clear(); }
+}
+function ordinal(a: string, b: string): number { return a < b ? -1 : a > b ? 1 : 0; }

package/src/components/profile.ts

@@ -0,0 +1,179 @@
+import { ProtocolError, StateConflictError } from '../errors.js';
+import { validateAccountId } from '../identity/neo.js';
+import type { DeviceSigner } from '../interactions.js';
+import { contentReferenceCodec, type ContentReference } from '../models/content.js';
+import { deviceCertificateCodec } from '../models/identity.js';
+import { accountProfileCodec, profileInput, profileResolveResultCodec, validateProfile, validateProfileResult, type AccountProfile, type ProfileResolveResult } from '../models/profile.js';
+import { canonicalJson, type JsonObject } from '../protocol/json.js';
+import { AsyncGate } from '../runtime/async-gate.js';
+import { EventHub, type EventListener } from '../runtime/events.js';
+import { finishSignedRequest, putSignedRequest, readSignedRequest, requestKey, type SignedRequest } from '../storage/signed-request.js';
+import type { MeshlineStore, RecordKey, StoreMutation } from '../storage/store.js';
+import { updateStore } from '../storage/transaction.js';
+import type { RelayClientPool } from '../transport/pool.js';
+import { RelayError } from '../transport/relay-error.js';
+import type { AccountManager } from './account.js';
+import { ClientComponent, type ClientOptions } from './component.js';
+
+/** Omitted fields are retained; null removes an optional field, including an existing empty string. */
+export interface ProfileUpdate { readonly nickname?: string | null; readonly bio?: string | null; readonly avatar?: ContentReference | null; readonly publicDiscovery?: boolean }
+export interface ProfileEvents { readonly profileChanged: AccountProfile | undefined }
+export interface ProfileManagerOptions extends ClientOptions {
+    readonly store: MeshlineStore; readonly relayClients: RelayClientPool; readonly accountManager: AccountManager; readonly deviceSigner: DeviceSigner;
+}
+const method = 'profile.publish';
+const profileKey = (account: string): RecordKey => ({ collection: 'profiles', key: account });
+const clone = (value: AccountProfile): AccountProfile => accountProfileCodec.decode(accountProfileCodec.encode(value));
+const fingerprint = (value: JsonObject | undefined): string => canonicalJson(value ?? null);
+function copyUpdate(value: ProfileUpdate): ProfileUpdate {
+    for (const key of Object.keys(value)) if (!['nickname', 'bio', 'avatar', 'publicDiscovery'].includes(key)) throw new TypeError(`Unknown profile update field ${key}.`);
+    if (value.publicDiscovery !== undefined && typeof value.publicDiscovery !== 'boolean') throw new TypeError('publicDiscovery must be boolean and cannot be deleted.');
+    for (const field of [value.nickname, value.bio]) if (field !== undefined && field !== null && typeof field !== 'string') throw new TypeError('Profile text must be a string or null.');
+    return { ...value, ...(value.avatar == null ? {} : { avatar: contentReferenceCodec.decode(contentReferenceCodec.encode(value.avatar)) }) };
+}
+function apply(update: ProfileUpdate, basis: AccountProfile): AccountProfile {
+    const document = accountProfileCodec.encode(basis);
+    for (const field of ['nickname', 'bio', 'avatar'] as const) {
+        const value = update[field];
+        if (value === null) delete document[field];
+        else if (value !== undefined) document[field] = typeof value === 'string' ? value : contentReferenceCodec.encode(value);
+    }
+    if (update.publicDiscovery !== undefined) document.public_discovery = update.publicDiscovery;
+    return accountProfileCodec.decode(document);
+}
+
+export class ProfileManager extends ClientComponent {
+    readonly #store: MeshlineStore; readonly #pool: RelayClientPool; readonly #account: AccountManager; readonly #signer: DeviceSigner;
+    readonly #gate = new AsyncGate(); readonly #events = new EventHub<ProfileEvents>();
+    #profile: AccountProfile | undefined;
+    constructor(options: ProfileManagerOptions) {
+        super(options);
+        for (const dependency of [options.relayClients, options.accountManager])
+            if (dependency.accountId !== this.accountId || dependency.context.toString() !== this.context.toString())
+                throw new ProtocolError('invalid_context', 'Profile dependencies belong to another account or network.');
+        this.#store = options.store; this.#pool = options.relayClients; this.#account = options.accountManager; this.#signer = options.deviceSigner;
+    }
+    get profile(): AccountProfile | undefined { return this.#profile && clone(this.#profile); }
+    on<K extends keyof ProfileEvents>(event: K, listener: EventListener<ProfileEvents[K]>): () => void { return this.#events.on(event, listener); }
+    protected override async onInitialize(signal: AbortSignal): Promise<void> {
+        this.#account.ensureInitialized();
+        await this.#store.initialize({ context: this.context.toString(), accountId: this.accountId }, signal);
+        const saved = (await this.#store.read([profileKey(this.accountId)], signal)).sets[0]![0]?.value;
+        if (saved) { const result = profileResolveResultCodec.decode(saved); validateProfileResult(result, this.context, this.accountId); this.#profile = result.profile; }
+    }
+    #accept(profile: AccountProfile | undefined): boolean {
+        const changed = (profile && accountProfileCodec.stringify(profile)) !== (this.#profile && accountProfileCodec.stringify(this.#profile));
+        this.#profile = profile && clone(profile); return changed;
+    }
+    #changed(): void { this.#events.notify('profileChanged', this.profile, error => this.notifyBackgroundError({ operation: 'observer', resource: 'profileChanged', error })); }
+    async getProfile(accountId = this.accountId, signal?: AbortSignal): Promise<AccountProfile | undefined> {
+        validateAccountId(accountId); let changed = false;
+        const profile = await this.runOperation(scope => this.#gate.run(async () => {
+            const result = await this.#resolve(accountId, await this.#home(scope), scope);
+            if (result) await this.#save(result, scope);
+            if (accountId === this.accountId) changed = this.#accept(result?.profile);
+            return result?.profile;
+        }, scope), signal);
+        if (changed) this.#changed(); return profile && clone(profile);
+    }
+    async updateProfile(update: ProfileUpdate, signal?: AbortSignal): Promise<AccountProfile> {
+        const copied = copyUpdate(update); let changed = false;
+        const result = await this.runOperation(scope => this.#gate.run(async () => {
+            const result = await this.#publish(copied, undefined, scope); changed = this.#accept(result); return result;
+        }, scope), signal);
+        if (changed) this.#changed(); return clone(result);
+    }
+    /** Republish the newest known local/pending/supplied snapshot, including during home-relay migration. */
+    async publishProfile(profile?: AccountProfile, signal?: AbortSignal): Promise<AccountProfile | undefined> {
+        const supplied = profile && clone(profile);
+        if (supplied) { validateProfile(supplied); if (supplied.account !== this.accountId) throw new ProtocolError('invalid_identity', 'Profile belongs to another account.'); }
+        let changed = false;
+        const result = await this.runOperation(scope => this.#gate.run(async () => {
+            const snapshot = await this.#store.read([profileKey(this.accountId), requestKey(method)], scope);
+            const local = snapshot.sets[0]![0]?.value;
+            const signed = readSignedRequest(snapshot.sets[1]![0]?.value);
+            let latest = local && profileResolveResultCodec.decode(local).profile;
+            if (signed?.pending && (!latest || signed.revision >= latest.updatedAt)) latest = accountProfileCodec.decode(signed.document);
+            if (supplied && (!latest || supplied.updatedAt > latest.updatedAt)) latest = supplied;
+            if (!latest) return undefined;
+            const published = await this.#publish({}, latest, scope); changed = this.#accept(published); return published;
+        }, scope), signal);
+        if (changed) this.#changed(); return result && clone(result);
+    }
+    async #home(signal: AbortSignal): Promise<string> {
+        const route = await this.#account.getRoute(undefined, signal);
+        if (!route) throw new ProtocolError('route_required', 'Establish or recover the account route before publishing profiles.');
+        return route.relayId;
+    }
+    async #resolve(account: string, relayId: string, signal: AbortSignal): Promise<ProfileResolveResult | undefined> {
+        const client = await this.#pool.get(relayId, { mode: 'device', signer: this.#signer }, signal);
+        let response;
+        try { response = await client.requestHttp('GET', 'profile.resolve', { account }, { signal }); }
+        catch (error) { if (error instanceof RelayError && error.code === 'not_found') return undefined; throw error; }
+        if (response === undefined) throw new ProtocolError('invalid_response', 'Profile resolution returned no document.');
+        const result = profileResolveResultCodec.decode(response); validateProfileResult(result, this.context, account); return result;
+    }
+    async #publish(update: ProfileUpdate, restored: AccountProfile | undefined, signal: AbortSignal): Promise<AccountProfile> {
+        const certificate = deviceCertificateCodec.decode(deviceCertificateCodec.encode(this.#signer.certificate));
+        if (certificate.account !== this.accountId) throw new ProtocolError('invalid_identity', 'Device signer belongs to another account.');
+        const relayId = await this.#home(signal);
+        const queries = [profileKey(this.accountId), requestKey(method)];
+        const snapshot = await this.#store.read(queries, signal);
+        const local = snapshot.sets[0]![0]?.value; const saved = snapshot.sets[1]![0]?.value;
+        let signed = readSignedRequest(saved); let request: AccountProfile;
+        if (signed?.pending && (!restored || signed.relayId === relayId)) {
+            request = accountProfileCodec.decode(signed.document);
+            if (signed.relayId !== relayId || accountProfileCodec.stringify(apply(update, request)) !== accountProfileCodec.stringify(request))
+                throw new StateConflictError('A profile publication has an unknown result. Retry the original update or resolve it first.');
+        } else {
+            const current = await this.#resolve(this.accountId, relayId, signal);
+            const cached = local && profileResolveResultCodec.decode(local).profile;
+            let basis = current?.profile;
+            if (basis && cached && basis.updatedAt < cached.updatedAt) throw new ProtocolError('stale_profile', 'Relay returned an older profile.');
+            for (const candidate of [cached, restored, signed?.pending ? accountProfileCodec.decode(signed.document) : undefined])
+                if (candidate && (!basis || candidate.updatedAt > basis.updatedAt)) basis = candidate;
+            basis ??= { account: this.accountId, publicDiscovery: false, updatedAt: 0, deviceSignature: new Uint8Array(64) };
+            request = { ...apply(update, basis), updatedAt: Math.max(this.clock.nowSeconds(), basis.updatedAt), deviceSignature: new Uint8Array(64) };
+            validateProfile(request);
+            request = { ...request, deviceSignature: (await this.#signer.sign(profileInput(request, this.context), signal)).slice() };
+            validateProfileResult({ profile: request, signerCertificate: certificate }, this.context, this.accountId);
+            const prepared: SignedRequest = { relayId, revision: request.updatedAt, document: accountProfileCodec.encode(request), pending: true };
+            await updateStore(this.#store, queries, state => {
+                if (fingerprint(state.sets[0]![0]?.value) !== fingerprint(local) || fingerprint(state.sets[1]![0]?.value) !== fingerprint(saved))
+                    throw new StateConflictError('Profile changed while signing. Resolve current state before retrying.');
+                return { mutations: [putSignedRequest(method, prepared)], result: undefined };
+            }, signal);
+            signed = prepared;
+        }
+        // A renewed certificate with the same key is valid; a replaced signing identity cannot replay the old request.
+        validateProfileResult({ profile: request, signerCertificate: certificate }, this.context, this.accountId);
+        const currentCertificate = this.#signer.certificate;
+        if (currentCertificate.account !== certificate.account || canonicalJson(deviceCertificateCodec.encode(currentCertificate)) !== canonicalJson(deviceCertificateCodec.encode(certificate)))
+            throw new StateConflictError('Device signer changed during profile publication.');
+        const client = await this.#pool.get(relayId, { mode: 'device', signer: this.#signer }, signal);
+        try { await client.requestHttp('PUT', method, signed!.document, { signal }); }
+        catch (error) {
+            if (error instanceof RelayError && error.isDefinitiveRejection) {
+                try { await finishSignedRequest(this.#store, method, signed!); }
+                catch (storageError) { throw new AggregateError([error, storageError], 'Profile rejection could not be persisted.'); }
+            }
+            throw error;
+        }
+        await this.#save({ profile: request, signerCertificate: certificate }, signal); return request;
+    }
+    async #save(result: ProfileResolveResult, signal: AbortSignal): Promise<void> {
+        const profile = result.profile;
+        await updateStore(this.#store, [profileKey(profile.account), requestKey(method)], snapshot => {
+            const previous = snapshot.sets[0]![0]?.value;
+            if (previous && profile.updatedAt < profileResolveResultCodec.decode(previous).profile.updatedAt)
+                throw new ProtocolError('stale_profile', 'Returned profile is older than the known profile.');
+            const mutations: StoreMutation[] = [{ ...profileKey(profile.account), kind: 'put', value: profileResolveResultCodec.encode(result) }];
+            const signed = readSignedRequest(snapshot.sets[1]![0]?.value);
+            if (profile.account === this.accountId && signed?.pending && (profile.updatedAt > signed.revision
+                || profile.updatedAt === signed.revision && accountProfileCodec.stringify(profile) === canonicalJson(signed.document)))
+                mutations.push(putSignedRequest(method, { ...signed, pending: false }));
+            return { mutations, result: undefined };
+        }, signal);
+    }
+    protected override async onDispose(): Promise<void> { this.#events.clear(); }
+}

package/src/crypto/groups.ts

@@ -0,0 +1,107 @@
+import { ProtocolError } from '../errors.js';
+import { validateIdentifier } from '../identity/identifiers.js';
+import { validateAccountId } from '../identity/neo.js';
+import type { DeviceSigner } from '../interactions.js';
+import { contentHashBytes } from '../models/content.js';
+import { certificateId, deviceCertificateCodec, validateCertificate, type DeviceCertificate } from '../models/identity.js';
+import { groupMessageEnvelopeCodec, groupMessageEnvelopeInput, groupPayloadCodec, validateGroupPayload, validateGroupSecretBox, verifyGroupMessageEnvelope,
+    type GroupMessageEnvelope, type GroupSecretBox } from '../models/groups.js';
+import { signingInput, type NetworkContext } from '../protocol/context.js';
+import { concatBytes, encodeBase64Url, encodeUtf8 } from '../protocol/encoding.js';
+import { canonicalBytes, parseJson, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import { throwIfAborted } from '../runtime/clock.js';
+import { agreeKey, decryptAes, deriveKey, encryptAes, encryptionPublicKey, requireLength, sha256, systemRandom, type RandomSource } from './primitives.js';
+
+const boxSalt = sha256(encodeUtf8('Meshline/keybox-salt/v1'));
+const epochSalt = sha256(encodeUtf8('Meshline/group-epoch-salt/v1'));
+const messageSalt = sha256(encodeUtf8('Meshline/group-message-salt/v1'));
+/** Local protection/key-access failures remain retryable and never reject remote group messages. */
+export class GroupKeyAccessError extends Error { override readonly name = 'GroupKeyAccessError'; }
+/** Hash the complete signed management object, including its device signature; timeline metadata is external. */
+export function groupManagementHash(value: JsonObject, context: NetworkContext): string {
+    if (typeof value.$type !== 'string') throw new ProtocolError('invalid_type', 'Management hashes require a typed protocol object.');
+    return `sha256:${encodeBase64Url(sha256(signingInput(value, context)))}`;
+}
+export function groupClientSecretCommitment(groupId: string, secret: Uint8Array, context: NetworkContext): string {
+    validateIdentifier('group', groupId); requireLength(secret, 32, 'Client group secret');
+    return groupManagementHash({ $type: 'meshline.group.client_secret.commitment', group_id: groupId, secret: encodeBase64Url(secret) }, context);
+}
+export interface GroupClientSecretBoxHeader { readonly groupId: string; readonly account: string; readonly memberEncryptionPublicKey: Uint8Array; readonly clientSecretCommitment: string }
+export function groupClientSecretBoxAad(value: GroupClientSecretBoxHeader, context: NetworkContext): Uint8Array {
+    validateIdentifier('group', value.groupId); validateAccountId(value.account); requireLength(value.memberEncryptionPublicKey, 32, 'Member encryption public key'); contentHashBytes(value.clientSecretCommitment);
+    return signingInput({ $type: 'meshline.group.client_secret_box.aad', group_id: value.groupId, account: value.account,
+        member_encryption_public_key: encodeBase64Url(value.memberEncryptionPublicKey), client_secret_commitment: value.clientSecretCommitment }, context);
+}
+export interface GroupRelaySecretBoxHeader { readonly groupId: string; readonly account: string; readonly deviceId: string; readonly epoch: number }
+export function groupRelaySecretBoxAad(value: GroupRelaySecretBoxHeader, context: NetworkContext): Uint8Array {
+    validateIdentifier('group', value.groupId); validateAccountId(value.account); validateIdentifier('device', value.deviceId); requireSafeInteger(value.epoch, 0);
+    return signingInput({ $type: 'meshline.group.relay_secret_box.aad', group_id: value.groupId, account: value.account, device_id: value.deviceId, epoch: value.epoch }, context);
+}
+/** Low-level secret wrapping with a protocol AAD projection; caller-owned secret and public key are never erased. */
+export function sealGroupSecret(secret: Uint8Array, publicKey: Uint8Array, aad: Uint8Array, random: RandomSource = systemRandom): GroupSecretBox {
+    requireLength(secret, 32, 'Group secret'); requireLength(publicKey, 32, 'Secret recipient public key');
+    let ephemeral: Uint8Array | undefined; let shared: Uint8Array | undefined; let key: Uint8Array | undefined;
+    try {
+        ephemeral = random.bytes(32); requireLength(ephemeral, 32, 'Ephemeral private key'); const enc = encryptionPublicKey(ephemeral);
+        shared = agreeKey(ephemeral, publicKey); key = deriveKey(shared, boxSalt, aad);
+        const nonce = random.bytes(12); requireLength(nonce, 12, 'Secret box nonce');
+        return { alg: 'X25519-HKDF-SHA256-AES256GCM', enc, sealedSecret: concatBytes(nonce, encryptAes(key, nonce, secret, aad)) };
+    } finally { ephemeral?.fill(0); shared?.fill(0); key?.fill(0); }
+}
+/** Caller owns both the supplied shared secret and the returned plaintext; erase them after use. */
+export function openGroupSecret(box: GroupSecretBox, shared: Uint8Array, aad: Uint8Array): Uint8Array {
+    validateGroupSecretBox(box); requireLength(shared, 32, 'Secret box shared secret');
+    if (shared.every(byte => byte === 0)) throw new ProtocolError('invalid_key', 'An all-zero shared secret is forbidden.');
+    const key = deriveKey(shared, boxSalt, aad);
+    try { return decryptAes(key, box.sealedSecret.subarray(0, 12), box.sealedSecret.subarray(12), aad); }
+    finally { key.fill(0); }
+}
+export function sealGroupClientSecret(header: GroupClientSecretBoxHeader, secret: Uint8Array, context: NetworkContext, random: RandomSource = systemRandom): GroupSecretBox {
+    const aad = groupClientSecretBoxAad(header, context);
+    if (groupClientSecretCommitment(header.groupId, secret, context) !== header.clientSecretCommitment) throw new ProtocolError('invalid_commitment', 'Client group secret does not match its commitment.');
+    return sealGroupSecret(secret, header.memberEncryptionPublicKey, aad, random);
+}
+/** Validates the client half before combining both independently supplied 32-byte secrets. */
+export function deriveGroupApplicationSecret(groupId: string, epoch: number, clientSecretCommitment: string, clientSecret: Uint8Array, relaySecret: Uint8Array, context: NetworkContext): Uint8Array {
+    validateIdentifier('group', groupId); requireSafeInteger(epoch, 0); contentHashBytes(clientSecretCommitment);
+    requireLength(clientSecret, 32, 'Client group secret'); requireLength(relaySecret, 32, 'Relay epoch secret');
+    if (groupClientSecretCommitment(groupId, clientSecret, context) !== clientSecretCommitment) throw new ProtocolError('invalid_commitment', 'Client group secret does not match its commitment.');
+    const material = concatBytes(clientSecret, relaySecret);
+    try { return deriveKey(material, epochSalt, signingInput({ $type: 'meshline.group.epoch_secret', group_id: groupId, epoch, client_secret_commitment: clientSecretCommitment }, context)); }
+    finally { material.fill(0); }
+}
+export type GroupMessageHeader = Pick<GroupMessageEnvelope, 'groupId' | 'epoch' | 'messageId' | 'createdAt'>;
+export function groupMessageAad(value: GroupMessageHeader, account: string, deviceId: string, context: NetworkContext): Uint8Array {
+    validateIdentifier('group', value.groupId); validateIdentifier('message', value.messageId); requireSafeInteger(value.epoch, 0); requireSafeInteger(value.createdAt, 0); validateAccountId(account); validateIdentifier('device', deviceId);
+    return signingInput({ $type: 'meshline.group.message.aad', group_id: value.groupId, epoch: value.epoch, message_id: value.messageId, created_at: value.createdAt, from: account, from_device_id: deviceId }, context);
+}
+export function deriveGroupMessageKey(applicationSecret: Uint8Array, aad: Uint8Array): Uint8Array { requireLength(applicationSecret, 32, 'Epoch application secret'); return deriveKey(applicationSecret, messageSalt, aad); }
+export interface EncryptGroupMessageOptions extends GroupMessageHeader {
+    readonly context: NetworkContext; readonly signer: DeviceSigner; readonly applicationSecret: Uint8Array; readonly payload: JsonObject; readonly random?: RandomSource; readonly signal?: AbortSignal;
+}
+export async function encryptGroupMessage(options: EncryptGroupMessageOptions): Promise<GroupMessageEnvelope> {
+    const { context, signer, signal } = options; throwIfAborted(signal);
+    const certificate = deviceCertificateCodec.decode(deviceCertificateCodec.encode(signer.certificate)); validateCertificate(certificate, context);
+    const signerId = certificateId(certificate, context); const header = { groupId: options.groupId, epoch: options.epoch, messageId: options.messageId, createdAt: options.createdAt };
+    if (header.createdAt < certificate.notBefore || header.createdAt >= certificate.expiresAt) throw new ProtocolError('unauthorized_device', 'Group signer certificate is outside its validity window.');
+    const payload = groupPayloadCodec.decode(options.payload); validateGroupPayload(payload);
+    const aad = groupMessageAad(header, certificate.account, signerId, context); const key = deriveGroupMessageKey(options.applicationSecret, aad); let plaintext: Uint8Array | undefined;
+    try {
+        plaintext = canonicalBytes(payload); const nonce = (options.random ?? systemRandom).bytes(12); requireLength(nonce, 12, 'Group message nonce');
+        let envelope: GroupMessageEnvelope = { ...header, payload: { alg: 'AES-256-GCM', nonce, ciphertext: encryptAes(key, nonce, plaintext, aad) }, deviceSignature: new Uint8Array(64) };
+        envelope = { ...envelope, deviceSignature: (await signer.sign(groupMessageEnvelopeInput(envelope, context), signal)).slice() }; throwIfAborted(signal);
+        if (certificateId(signer.certificate, context) !== signerId) throw new ProtocolError('invalid_identity', 'Group signer changed identity during signing.');
+        verifyGroupMessageEnvelope(envelope, certificate, signerId, context); return envelope;
+    } finally { key.fill(0); plaintext?.fill(0); }
+}
+export interface DecryptGroupMessageOptions {
+    readonly context: NetworkContext; readonly envelope: GroupMessageEnvelope; readonly sender: DeviceCertificate; readonly signerDeviceId: string; readonly applicationSecret: Uint8Array;
+}
+/** Authenticates the signature, sender account and device before returning typed content. Membership validation remains mandatory in the receiver. */
+export function decryptGroupMessage(options: DecryptGroupMessageOptions): JsonObject {
+    const { context, signerDeviceId } = options; const envelope = groupMessageEnvelopeCodec.decode(groupMessageEnvelopeCodec.encode(options.envelope));
+    const sender = deviceCertificateCodec.decode(deviceCertificateCodec.encode(options.sender)); verifyGroupMessageEnvelope(envelope, sender, signerDeviceId, context);
+    const key = deriveGroupMessageKey(options.applicationSecret, groupMessageAad(envelope, sender.account, signerDeviceId, context)); let plaintext: Uint8Array | undefined;
+    try { plaintext = decryptAes(key, envelope.payload.nonce, envelope.payload.ciphertext, groupMessageAad(envelope, sender.account, signerDeviceId, context)); return groupPayloadCodec.decode(parseJson(plaintext)); }
+    finally { key.fill(0); plaintext?.fill(0); }
+}