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

package/src/crypto/messages.ts

@@ -0,0 +1,129 @@
+import { ProtocolError } from '../errors.js';
+import type { DeviceSigner } from '../interactions.js';
+import { validateIdentifier } from '../identity/identifiers.js';
+import { validateAccountId } from '../identity/neo.js';
+import { contactAuthorizationCodec, type ContactAuthorization } from '../models/contacts.js';
+import { certificateId, deviceCertificateCodec, validateCertificate, type DeviceCertificate } from '../models/identity.js';
+import { messageEnvelopeCodec, messageEnvelopeInput, messageKeyBoxCodec, messagePayloadCodec, validateMessageKeyBox, validateMessageSendRequest, verifyMessageEnvelope,
+    type MessageEnvelope, type MessageKeyBox, type MessageSendRequest } from '../models/messages.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 keyBoxSalt = sha256(encodeUtf8('Meshline/keybox-salt/v1'));
+type MessageHeader = Pick<MessageEnvelope, 'messageId' | 'createdAt' | 'from' | 'fromDeviceId' | 'to'>;
+function validateHeader(value: MessageHeader): void {
+    validateIdentifier('message', value.messageId); validateIdentifier('device', value.fromDeviceId); validateAccountId(value.from); validateAccountId(value.to); requireSafeInteger(value.createdAt, 0);
+}
+/** Fixed protocol projection; envelope extensions are signed but are not part of payload AAD. */
+export function messageAad(value: MessageHeader, context: NetworkContext): Uint8Array {
+    validateHeader(value);
+    return signingInput({ $type: 'meshline.message.aad', message_id: value.messageId, created_at: value.createdAt, from: value.from, from_device_id: value.fromDeviceId, to: value.to }, context);
+}
+/** Fixed projection shared by HKDF info and AES-GCM key wrapping AAD. */
+export function messageKeyBoxAad(value: MessageHeader & { readonly payload: { readonly alg: string } }, box: Pick<MessageKeyBox, 'alg' | 'deviceId' | 'enc'>, account: string, context: NetworkContext): Uint8Array {
+    validateHeader(value); validateAccountId(account); validateIdentifier('device', box.deviceId); requireLength(box.enc, 32, 'Ephemeral public key');
+    if (account !== value.from && account !== value.to) throw new ProtocolError('invalid_identity', 'Key box account must be a message participant.');
+    if (box.alg !== 'X25519-HKDF-SHA256-AES256GCM' || value.payload.alg !== 'AES-256-GCM') throw new ProtocolError('unsupported_algorithm', 'Unsupported message key wrapping algorithms.');
+    return signingInput({ $type: 'meshline.message.key_box.aad', alg: box.alg, payload_alg: value.payload.alg, message_id: value.messageId,
+        created_at: value.createdAt, from: value.from, from_device_id: value.fromDeviceId, account, device_id: box.deviceId, enc: encodeBase64Url(box.enc) }, context);
+}
+export interface EncryptMessageOptions {
+    readonly context: NetworkContext; readonly signer: DeviceSigner; readonly messageId: string; readonly createdAt: number;
+    readonly recipient: string; readonly payload: JsonObject; readonly recipientDevices: readonly DeviceCertificate[];
+    readonly senderDevices?: readonly DeviceCertificate[]; readonly authorization?: ContactAuthorization; readonly random?: RandomSource; readonly signal?: AbortSignal;
+}
+/** Builds immutable delivery material. Device lists must come from current authoritative states, checked by the calling manager. */
+export async function encryptMessage(options: EncryptMessageOptions): Promise<MessageSendRequest> {
+    const { context, signer, messageId, createdAt, recipient, signal } = options; throwIfAborted(signal);
+    const random = options.random ?? systemRandom;
+    const certificate = deviceCertificateCodec.decode(deviceCertificateCodec.encode(signer.certificate)); validateCertificate(certificate, context);
+    const senderId = certificateId(certificate, context);
+    const recipients = copyDevices(options.recipientDevices, recipient, createdAt, context);
+    const senders = recipient === certificate.account ? undefined : copyDevices(options.senderDevices ?? [certificate], certificate.account, createdAt, context);
+    const authorization = options.authorization === undefined ? undefined : contactAuthorizationCodec.decode(contactAuthorizationCodec.encode(options.authorization));
+    if (createdAt < certificate.notBefore || createdAt >= certificate.expiresAt) throw new ProtocolError('unauthorized_device', 'Message signer certificate is outside its validity window.');
+    if (recipient === certificate.account && (authorization !== undefined || options.senderDevices !== undefined)) throw new ProtocolError('invalid_self_delivery', 'Self messages must omit sender devices and authorization.');
+    const header = { messageId, createdAt, from: certificate.account, fromDeviceId: senderId, to: recipient };
+    const aad = messageAad(header, context);
+    const plaintext = canonicalBytes(messagePayloadCodec.decode(options.payload));
+    let contentKey: Uint8Array | undefined;
+    try {
+        contentKey = random.bytes(32); requireLength(contentKey, 32, 'Content key');
+        const nonce = random.bytes(12); requireLength(nonce, 12, 'Payload nonce');
+        let envelope: MessageEnvelope = { ...header, payload: { alg: 'AES-256-GCM', nonce, ciphertext: encryptAes(contentKey, nonce, plaintext, aad) }, deviceSignature: new Uint8Array(64) };
+        envelope = { ...envelope, deviceSignature: (await signer.sign(messageEnvelopeInput(envelope, context), signal)).slice() };
+        throwIfAborted(signal);
+        if (certificateId(signer.certificate, context) !== senderId) throw new ProtocolError('invalid_identity', 'Device signer changed identity during message signing.');
+        verifyMessageEnvelope(envelope, certificate, context);
+        const recipientBoxes = sealKeys(envelope, recipient, recipients, contentKey, context, random);
+        const senderBoxes = senders && sealKeys(envelope, certificate.account, senders, contentKey, context, random);
+        const result: MessageSendRequest = { envelope, recipientBoxes, ...(senderBoxes ? { senderBoxes } : {}), ...(authorization ? { authorization } : {}) };
+        validateMessageSendRequest(result, createdAt); throwIfAborted(signal); return result;
+    } finally { contentKey?.fill(0); plaintext.fill(0); }
+}
+function copyDevices(values: readonly DeviceCertificate[], account: string, now: number, context: NetworkContext): DeviceCertificate[] {
+    if (values.length < 1 || values.length > 8) throw new ProtocolError('invalid_size', 'Message encryption requires between one and eight devices per account.');
+    const ids = new Set<string>();
+    return values.map(value => {
+        const copy = deviceCertificateCodec.decode(deviceCertificateCodec.encode(value)); validateCertificate(copy, context);
+        if (copy.account !== account || copy.notBefore > now || now >= copy.expiresAt) throw new ProtocolError('unauthorized_device', 'Encryption certificate belongs to another account or is outside its validity window.');
+        const id = certificateId(copy, context); if (ids.has(id)) throw new ProtocolError('duplicate_device', 'Duplicate encryption device.'); ids.add(id); return copy;
+    });
+}
+function sealKeys(envelope: MessageEnvelope, account: string, certificates: readonly DeviceCertificate[], contentKey: Uint8Array, context: NetworkContext, random: RandomSource): MessageKeyBox[] {
+    return certificates.map(certificate => {
+        let ephemeral: Uint8Array | undefined; let shared: Uint8Array | undefined; let wrappingKey: Uint8Array | undefined;
+        try {
+            ephemeral = random.bytes(32); requireLength(ephemeral, 32, 'Ephemeral private key');
+            const box = { deviceId: certificateId(certificate, context), alg: 'X25519-HKDF-SHA256-AES256GCM', enc: encryptionPublicKey(ephemeral) };
+            shared = agreeKey(ephemeral, certificate.encryptionPublicKey);
+            const aad = messageKeyBoxAad(envelope, box, account, context); wrappingKey = deriveKey(shared, keyBoxSalt, aad);
+            const nonce = random.bytes(12); requireLength(nonce, 12, 'Key box nonce');
+            return { ...box, sealedKey: concatBytes(nonce, encryptAes(wrappingKey, nonce, contentKey, aad)) };
+        } finally { ephemeral?.fill(0); shared?.fill(0); wrappingKey?.fill(0); }
+    });
+}
+/** Implementations return a fresh 32-byte shared secret; this function owns and erases that buffer. */
+export interface MessageDecryptor { readonly certificate: DeviceCertificate; deriveSharedSecret(peerPublicKey: Uint8Array, signal?: AbortSignal): Promise<Uint8Array> }
+/** Local key access failures are retryable reception failures, never grounds for discarding a remote message. */
+export class MessageKeyAccessError extends Error { override readonly name = 'MessageKeyAccessError'; }
+export interface DecryptMessageOptions {
+    readonly context: NetworkContext; readonly receiver: MessageDecryptor; readonly envelope: MessageEnvelope; readonly keyBox: MessageKeyBox;
+    readonly sender: DeviceCertificate; readonly signal?: AbortSignal;
+}
+/** Verifies signature before key agreement and returns no plaintext until both GCM authentications and complete JSON validation pass. */
+export async function decryptMessage(options: DecryptMessageOptions): Promise<JsonObject> {
+    const { context, receiver, signal } = options; throwIfAborted(signal);
+    const envelope = messageEnvelopeCodec.decode(messageEnvelopeCodec.encode(options.envelope));
+    const box = messageKeyBoxCodec.decode(messageKeyBoxCodec.encode(options.keyBox));
+    const sender = deviceCertificateCodec.decode(deviceCertificateCodec.encode(options.sender));
+    verifyMessageEnvelope(envelope, sender, context); validateMessageKeyBox(box);
+    // Public low-order-point validation distinguishes malformed remote input from failures opening local protected keys.
+    const probe = agreeKey(new Uint8Array(32).fill(1), box.enc); probe.fill(0);
+    let local: DeviceCertificate;
+    try { local = deviceCertificateCodec.decode(deviceCertificateCodec.encode(receiver.certificate)); validateCertificate(local, context); }
+    catch (cause) { throw new MessageKeyAccessError('Local device certificate is unavailable or invalid.', { cause }); }
+    const localId = certificateId(local, context);
+    if (local.account !== envelope.from && local.account !== envelope.to || box.deviceId !== localId) throw new ProtocolError('invalid_identity', 'Message or key box belongs to another account or device.');
+    let shared: Uint8Array | undefined; let wrappingKey: Uint8Array | undefined; let contentKey: Uint8Array | undefined; let plaintext: Uint8Array | undefined;
+    try {
+        try {
+            shared = await receiver.deriveSharedSecret(box.enc.slice(), signal); throwIfAborted(signal);
+            if (certificateId(receiver.certificate, context) !== localId) throw new Error('Decrypting device changed identity during key agreement.');
+            requireLength(shared, 32, 'X25519 shared secret');
+            if (shared.every(byte => byte === 0)) throw new MessageKeyAccessError('Device key agreement produced an all-zero shared secret.');
+        } catch (cause) {
+            throwIfAborted(signal);
+            if (cause instanceof MessageKeyAccessError) throw cause;
+            throw new MessageKeyAccessError('Local device key agreement failed.', { cause });
+        }
+        const aad = messageKeyBoxAad(envelope, box, local.account, context); wrappingKey = deriveKey(shared, keyBoxSalt, aad);
+        contentKey = decryptAes(wrappingKey, box.sealedKey.subarray(0, 12), box.sealedKey.subarray(12), aad);
+        requireLength(contentKey, 32, 'Content key');
+        plaintext = decryptAes(contentKey, envelope.payload.nonce, envelope.payload.ciphertext, messageAad(envelope, context));
+        return messagePayloadCodec.decode(parseJson(plaintext));
+    } finally { shared?.fill(0); wrappingKey?.fill(0); contentKey?.fill(0); plaintext?.fill(0); }
+}

package/src/crypto/primitives.ts

@@ -0,0 +1,103 @@
+import { ed25519, x25519 } from '@noble/curves/ed25519.js';
+import { p256 } from '@noble/curves/nist.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { ripemd160 } from '@noble/hashes/legacy.js';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { gcm } from '@noble/ciphers/aes.js';
+import { ProtocolError } from '../errors.js';
+
+export { sha256 };
+
+/** Platform cryptographic random source; implementations must never use Math.random. */
+export interface RandomSource { bytes(length: number): Uint8Array }
+
+/** Browser and Node.js random source. Expo supplies an explicit native source. */
+export const systemRandom: RandomSource = {
+    bytes(length) {
+        if (!Number.isSafeInteger(length) || length < 0) throw new RangeError('Invalid random byte count.');
+        if (!globalThis.crypto?.getRandomValues)
+            throw new ProtocolError('random_unavailable', 'A cryptographic random source is required.');
+        const result = new Uint8Array(length);
+        for (let offset = 0; offset < length; offset += 65_536)
+            globalThis.crypto.getRandomValues(result.subarray(offset, offset + 65_536));
+        return result;
+    },
+};
+
+export function requireLength(value: Uint8Array, length: number, name: string): void {
+    if (!(value instanceof Uint8Array) || value.length !== length)
+        throw new ProtocolError('invalid_length', `${name} must contain ${length} bytes.`);
+}
+
+/** Ed25519 public key derived from a 32-byte seed. */
+export function devicePublicKey(seed: Uint8Array): Uint8Array {
+    requireLength(seed, 32, 'Ed25519 seed');
+    return ed25519.getPublicKey(seed);
+}
+
+/** Signs the exact supplied bytes with Ed25519. */
+export function signDevice(input: Uint8Array, seed: Uint8Array): Uint8Array {
+    requireLength(seed, 32, 'Ed25519 seed');
+    return ed25519.sign(input, seed);
+}
+
+/** Uses strict RFC 8032 verification, not permissive ZIP215 acceptance. */
+export function verifyDevice(input: Uint8Array, signature: Uint8Array, publicKey: Uint8Array): boolean {
+    if (signature.length !== 64 || publicKey.length !== 32) return false;
+    return ed25519.verify(signature, input, publicKey, { zip215: false });
+}
+
+/** Compressed P-256 public key, in the format used by Neo N3 accounts. */
+export function accountPublicKey(privateKey: Uint8Array): Uint8Array {
+    requireLength(privateKey, 32, 'P-256 private key');
+    return p256.getPublicKey(privateKey, true);
+}
+
+/** Verifies SHA-256 / P-256 compact signatures; both valid high-S and low-S forms are accepted. */
+export function verifyAccount(input: Uint8Array, signature: Uint8Array, publicKey: Uint8Array): boolean {
+    if (signature.length !== 64 || publicKey.length !== 33 || (publicKey[0] !== 2 && publicKey[0] !== 3)) return false;
+    return p256.verify(signature, input, publicKey, { prehash: true, lowS: false, format: 'compact' });
+}
+
+/** Low-level signing helper; application signers retain ownership of account keys. */
+export function signAccount(input: Uint8Array, privateKey: Uint8Array, random: RandomSource = systemRandom): Uint8Array {
+    requireLength(privateKey, 32, 'P-256 private key');
+    const entropy = random.bytes(32);
+    requireLength(entropy, 32, 'Signing entropy');
+    try { return p256.sign(input, privateKey, { prehash: true, lowS: false, format: 'compact', extraEntropy: entropy }); }
+    finally { entropy.fill(0); }
+}
+
+export function encryptionPublicKey(privateKey: Uint8Array): Uint8Array {
+    requireLength(privateKey, 32, 'X25519 private key');
+    return x25519.getPublicKey(privateKey);
+}
+
+export function agreeKey(privateKey: Uint8Array, publicKey: Uint8Array): Uint8Array {
+    requireLength(privateKey, 32, 'X25519 private key');
+    requireLength(publicKey, 32, 'X25519 public key');
+    try { return x25519.getSharedSecret(privateKey, publicKey); }
+    catch (cause) { throw new ProtocolError('invalid_key', 'X25519 agreement failed, including an all-zero shared secret.', { cause }); }
+}
+
+export function hash160(value: Uint8Array): Uint8Array { return ripemd160(sha256(value)); }
+
+export function deriveKey(secret: Uint8Array, salt: Uint8Array, info: Uint8Array, length = 32): Uint8Array {
+    return hkdf(sha256, secret, salt, info, length);
+}
+
+/** AES-256-GCM ciphertext followed by a 16-byte tag. The caller guarantees nonce uniqueness. */
+export function encryptAes(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): Uint8Array {
+    requireLength(key, 32, 'AES-256 key');
+    requireLength(nonce, 12, 'GCM nonce');
+    return gcm(key, nonce, aad).encrypt(plaintext);
+}
+
+/** Authenticates before exposing plaintext; malformed ciphertext is a protocol failure. */
+export function decryptAes(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad: Uint8Array): Uint8Array {
+    requireLength(key, 32, 'AES-256 key');
+    requireLength(nonce, 12, 'GCM nonce');
+    if (ciphertext.length < 16) throw new ProtocolError('invalid_ciphertext', 'Missing GCM tag.');
+    try { return gcm(key, nonce, aad).decrypt(ciphertext); }
+    catch (cause) { throw new ProtocolError('invalid_ciphertext', 'GCM authentication failed.', { cause }); }
+}

package/src/errors.ts

@@ -0,0 +1,13 @@
+/** A local encoding, identity, signature, or authorization violation. */
+export class ProtocolError extends Error {
+    override readonly name = 'ProtocolError';
+
+    constructor(readonly code: string, message: string, options?: ErrorOptions) {
+        super(message, options);
+    }
+}
+
+/** A persisted operation cannot safely overwrite the current revision. */
+export class StateConflictError extends Error {
+    override readonly name = 'StateConflictError';
+}

package/src/groups/account-sync.ts

@@ -0,0 +1,144 @@
+import type { DeviceManager } from '../components/device.js';
+import type { MessageManager } from '../components/message.js';
+import { ProtocolError, StateConflictError } from '../errors.js';
+import { sendGroupAccountPayload } from '../messages/account-sender.js';
+import { cachedDeviceStateKey } from '../messages/contacts.js';
+import type { AccountMessage, MessageEffects } from '../messages/repository.js';
+import { accountGroupHistorySecretSyncCodec, accountGroupPrivateStateRequestCodec, accountGroupPrivateStateSyncCodec,
+    validateAccountGroupHistorySecretSync, validateAccountGroupPrivateStateRequest, validateAccountGroupPrivateStateSync, type GroupHistorySecret, type GroupRef } from '../models/groups.js';
+import { accountDeviceStateCodec, authorizedDevice, certificateId } from '../models/identity.js';
+import type { NetworkContext } from '../protocol/context.js';
+import { canonicalJson, requireObject, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import { throwIfAborted, type RuntimeClock } 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 { groupApplicationSecretKey, groupMemberSecretKey, type GroupSecrets, type GroupSecretEffect } from './secrets.js';
+
+export interface GroupAccountSyncOptions {
+    readonly store: MeshlineStore; readonly context: NetworkContext; readonly accountId: string; readonly clock: RuntimeClock;
+    readonly device: DeviceManager; readonly messages: MessageManager; readonly secrets: GroupSecrets;
+    rejected(messageId: string, error: ProtocolError): void;
+}
+const cursorKey: RecordKey = { collection: 'group_account_meta', key: 'local_sequence' };
+const types = new Set(['meshline.account.group.state.request', 'meshline.account.group.state.sync', 'meshline.account.group.history_secret.sync']);
+const fingerprint = (value: JsonObject | undefined): string => canonicalJson(value ?? null);
+class AccountGroupRejection extends ProtocolError {}
+function input<T>(action: () => T): T {
+    try { return action(); } catch (error) { if (!(error instanceof ProtocolError)) throw error; throw new AccountGroupRejection(error.code, error.message, { cause: error }); }
+}
+function secretEffect(effect: GroupSecretEffect): GroupSecretEffect {
+    return { queries: effect.queries, plan: snapshot => {
+        try { return effect.plan(snapshot); }
+        catch (error) { if (!(error instanceof ProtocolError) || error.code !== 'invalid_binding') throw error; throw new AccountGroupRejection(error.code, error.message, { cause: error }); }
+    } };
+}
+
+/** One consumer cursor commits with all key effects; local protection/storage failures remain retryable. */
+export class GroupAccountSync {
+    constructor(readonly options: GroupAccountSyncOptions) {}
+    request(signal?: AbortSignal): Promise<void> { return sendGroupAccountPayload(this.options.messages, accountGroupPrivateStateRequestCodec.encode({}), undefined, signal); }
+    async consume(signal: AbortSignal): Promise<void> {
+        const { store, messages } = this.options;
+        for (;;) {
+            const after = (await store.read([cursorKey], signal)).sets[0]![0]?.value.sequence ?? 0; requireSafeInteger(after, 0);
+            const page = await messages.readTimeline(after, 64, signal); if (!page.length) return;
+            for (const message of page) {
+                throwIfAborted(signal); let effect: GroupSecretEffect | undefined; let rejection: AccountGroupRejection | undefined;
+                try { effect = await this.#prepare(message, signal); }
+                catch (error) { throwIfAborted(signal); if (!(error instanceof AccountGroupRejection)) throw error; rejection = error; }
+                try { await this.#commit(message, effect, rejection, signal); }
+                catch (error) {
+                    throwIfAborted(signal); if (rejection || !(error instanceof AccountGroupRejection)) throw error;
+                    rejection = error; await this.#commit(message, undefined, rejection, signal);
+                }
+                if (rejection) this.options.rejected(message.messageId, rejection);
+            }
+        }
+    }
+    async #commit(message: AccountMessage, effect: GroupSecretEffect | undefined, rejection: ProtocolError | undefined, signal: AbortSignal): Promise<void> {
+        requireSafeInteger(message.localSequence, 1);
+        await updateStore(this.options.store, [cursorKey, ...effect?.queries ?? []], snapshot => {
+            const previous = snapshot.sets[0]![0]?.value.sequence ?? 0; requireSafeInteger(previous, 0);
+            if (previous >= message.localSequence) return { mutations: [], result: undefined };
+            const mutations: StoreMutation[] = [...effect?.plan({ ...snapshot, sets: snapshot.sets.slice(1) }) ?? [], { kind: 'put', ...cursorKey, value: { sequence: message.localSequence } }];
+            if (rejection) mutations.push({ kind: 'put', collection: 'group_account_rejections', key: String(message.localSequence).padStart(16, '0'), value: { messageId: message.messageId, code: rejection.code, message: rejection.message } });
+            return { mutations, result: undefined };
+        }, signal);
+    }
+    #authorize(senderDeviceId: string, effect?: GroupSecretEffect): GroupSecretEffect {
+        return { queries: [cachedDeviceStateKey(this.options.accountId), ...effect?.queries ?? []], plan: snapshot => {
+            const row = snapshot.sets[0]![0]?.value; if (!row) throw new StateConflictError('Current device authorization disappeared during group account synchronization.');
+            const state = accountDeviceStateCodec.decode(row); if (state.account !== this.options.accountId) throw new ProtocolError('invalid_storage', 'Cached device authorization belongs to another account.');
+            input(() => authorizedDevice(state, senderDeviceId, this.options.context, this.options.clock.nowSeconds()));
+            return effect?.plan({ ...snapshot, sets: snapshot.sets.slice(1) }) ?? [];
+        } };
+    }
+    async #prepare(message: AccountMessage, signal: AbortSignal): Promise<GroupSecretEffect | undefined> {
+        if (!types.has(String(message.payload['$type']))) return undefined;
+        const { accountId, device, context, secrets } = this.options;
+        if (message.sender !== accountId || message.recipient !== accountId) throw new AccountGroupRejection('invalid_binding', 'Private group synchronization must stay within the current account.');
+        const own = await device.getDeviceState(undefined, signal); if (!own) throw new ProtocolError('device_state_required', 'Current account authorization is unavailable.');
+        input(() => authorizedDevice(own, message.senderDeviceId, context, this.options.clock.nowSeconds()));
+        let effect: GroupSecretEffect | undefined;
+        if (message.payload['$type'] === 'meshline.account.group.state.request') {
+            const request = input(() => { const value = accountGroupPrivateStateRequestCodec.decode(message.payload); validateAccountGroupPrivateStateRequest(value); return value; });
+            if (message.senderDeviceId !== certificateId(device.certificate, context)) await this.#reply(message.senderDeviceId, request.groupId, signal);
+        } else if (message.payload['$type'] === 'meshline.account.group.state.sync') {
+            const value = input(() => accountGroupPrivateStateSyncCodec.decode(message.payload));
+            try { input(() => validateAccountGroupPrivateStateSync(value)); effect = secretEffect(await secrets.prepareMemberStates(value.states, signal)); }
+            finally { for (const state of value.states) state.memberEncryptionPrivateKey.fill(0); }
+        } else {
+            const value = input(() => accountGroupHistorySecretSyncCodec.decode(message.payload));
+            try {
+                input(() => validateAccountGroupHistorySecretSync(value));
+                try { effect = await secrets.prepareHistorySecrets(value.secrets, signal); }
+                catch (error) { if (!(error instanceof ProtocolError) || error.code !== 'conflicting_epoch_secret') throw error; throw new AccountGroupRejection(error.code, error.message, { cause: error }); }
+            } finally { for (const secret of value.secrets) secret.applicationSecret.fill(0); }
+        }
+        return this.#authorize(message.senderDeviceId, effect);
+    }
+    #member(group: GroupRef, row: JsonObject | undefined) {
+        if (!row) return undefined; if (row.relayId !== group.relayId) throw new ProtocolError('invalid_binding', 'Synchronized group belongs to another hosting relay.');
+        if (!row.projection) return undefined; const projection = decodeGroupProjection(requireObject(row.projection), group);
+        if (row.localDepartureAfter !== undefined) { requireSafeInteger(row.localDepartureAfter, 0); if (projection.sequence <= row.localDepartureAfter) return undefined; }
+        return projection.members.some(value => value.account === this.options.accountId) ? projection : undefined;
+    }
+    #guard(queries: readonly RecordQuery[], before: StoreSnapshot, mutations: readonly StoreMutation[] = []): MessageEffects {
+        return { queries, plan: snapshot => {
+            if (snapshot.sets.some((rows, index) => fingerprint(rows[0]?.value) !== fingerprint(before.sets[index]![0]?.value))) throw new StateConflictError('Group key authority changed before account synchronization was enqueued.');
+            return mutations;
+        } };
+    }
+    async shareCurrent(group: GroupRef, signal: AbortSignal): Promise<void> { await this.#sendPrivate(group, undefined, signal); }
+    async #sendPrivate(group: GroupRef, devices: readonly string[] | undefined, signal: AbortSignal): Promise<void> {
+        const { store, secrets, messages } = this.options; const row = (await store.read([groupKey(group)], signal)).sets[0]![0]?.value;
+        const projection = this.#member(group, row); if (!projection) return;
+        const member = projection.members.find(value => value.account === this.options.accountId)!;
+        const key = groupMemberSecretKey(group.groupId, member.memberEncryptionPublicKey); const queries = [groupKey(group), groupEpochKey(group, projection.epoch), key]; const snapshot = await store.read(queries, signal);
+        if (fingerprint(snapshot.sets[0]![0]?.value) !== fingerprint(row)) throw new StateConflictError('Group authority changed before key sharing.');
+        const stored = snapshot.sets[2]![0]?.value; if (!stored || devices === undefined && stored.shared === true || snapshot.sets[1]![0]?.value.materialVerified !== true) return;
+        const privateKey = await secrets.readMemberKey(group.groupId, member.memberEncryptionPublicKey, signal); if (!privateKey) return;
+        try {
+            await sendGroupAccountPayload(messages, accountGroupPrivateStateSyncCodec.encode({ states: [{ ...group, memberEncryptionPrivateKey: privateKey }] }), devices, signal,
+                this.#guard(queries, snapshot, devices === undefined ? [{ kind: 'put', ...key, value: { ...stored, shared: true } }] : []));
+        } finally { privateKey.fill(0); }
+    }
+    async #reply(sender: string, requested: string | undefined, signal: AbortSignal): Promise<void> {
+        const { store, context, accountId, secrets, messages } = this.options; const repository = new GroupRepository(store, context, accountId);
+        const rows = (await store.read([{ collection: 'groups', ...(requested ? { key: requested } : {}) }], signal)).sets[0]!;
+        for (const row of rows) {
+            const group = { groupId: row.key, relayId: String(row.value.relayId) }; if (!this.#member(group, row.value)) continue;
+            await this.#sendPrivate(group, [sender], signal); const epochs = (await repository.epochs(group, signal)).filter(value => value.commitment);
+            for (let start = 0; start < epochs.length; start += 64) {
+                const batch = epochs.slice(start, start + 64); const queries = [groupKey(group), ...batch.flatMap(value => [groupEpochKey(group, value.epoch), groupApplicationSecretKey(group.groupId, value.epoch)])];
+                const snapshot = await store.read(queries, signal); if (!this.#member(group, snapshot.sets[0]![0]?.value)) break;
+                const history: GroupHistorySecret[] = [];
+                try {
+                    for (const value of batch) { const secret = await secrets.readApplicationSecret(group, value.epoch, signal); if (secret) history.push({ groupId: group.groupId, epoch: value.epoch, applicationSecret: secret }); }
+                    if (history.length) await sendGroupAccountPayload(messages, accountGroupHistorySecretSyncCodec.encode({ secrets: history }), [sender], signal, this.#guard(queries, snapshot));
+                } finally { for (const value of history) value.applicationSecret.fill(0); }
+            }
+        }
+    }
+}

package/src/groups/messages.ts

@@ -0,0 +1,89 @@
+import { decryptGroupMessage, GroupKeyAccessError } from '../crypto/groups.js';
+import { requireLength } from '../crypto/primitives.js';
+import { ProtocolError, StateConflictError } from '../errors.js';
+import { groupEventCodec } from '../models/group-management.js';
+import { groupMessageCodec, groupMessageEnvelopeCodec, groupMemberNicknameUpdateCodec, validateGroupPayload, validateGroupRef, type GroupMessage, type GroupRef } from '../models/groups.js';
+import { deviceCertificateCodec } from '../models/identity.js';
+import type { NetworkContext } from '../protocol/context.js';
+import { canonicalJson, requireObject, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import { throwIfAborted } from '../runtime/clock.js';
+import type { MeshlineStore, StoreMutation } from '../storage/store.js';
+import { updateStore } from '../storage/transaction.js';
+import { decodeGroupProjection, encodeGroupProjection, groupEpochKey, groupEventKey, groupKey, groupPendingMessageKey } from './repository.js';
+import type { GroupProjection } from './state.js';
+
+export interface GroupMessageInfo extends GroupMessage {
+    readonly group: GroupRef; readonly sequence: number; readonly messageId: string; readonly sender: string; readonly senderDeviceId: string; readonly createdAt: number; readonly acceptedAt: number;
+}
+export interface GroupMessageProcessingResult { readonly state: 'waitingForKey' | 'processed' | 'alreadyProcessed'; readonly message?: GroupMessageInfo; readonly nicknameChanged?: boolean; readonly groupRecord?: JsonObject; readonly error?: ProtocolError }
+export interface GroupApplicationSecrets {
+    /** Returns a fresh owned buffer only after the epoch's authority is verified. Caller erases it. */
+    readApplicationSecret(group: GroupRef, epoch: number, signal?: AbortSignal): Promise<Uint8Array | undefined>;
+}
+/** Sequence is scoped to this sender's and this recipient's current membership; unknown payload attributes never select the target member. */
+export function applyGroupNickname(projection: GroupProjection, accountId: string, sender: string, sequence: number, nickname: string | null): GroupProjection {
+    requireSafeInteger(sequence, 1);
+    const receiver = projection.members.find(member => member.account === accountId); const member = projection.members.find(member => member.account === sender);
+    if (!receiver || !member || sequence < receiver.joinedAtSequence || sequence < member.joinedAtSequence || sequence <= (member.nicknameSequence ?? -1)) return projection;
+    const next = { ...member, nicknameSequence: sequence }; if (nickname === null) delete next.nickname; else next.nickname = nickname;
+    return { ...projection, members: projection.members.map(value => value.account === sender ? next : value) };
+}
+
+/** Decryption is separate from verified timeline ingestion, so a missing old key cannot prevent recovery of later epochs. */
+export class GroupMessageProcessor {
+    constructor(readonly store: MeshlineStore, readonly context: NetworkContext, readonly accountId: string, readonly secrets: GroupApplicationSecrets) {}
+    async processPending(group: GroupRef, committed: (sequence: number, result: GroupMessageProcessingResult) => void, signal?: AbortSignal): Promise<void> {
+        validateGroupRef(group); const reader = await this.store.openQuery({ collection: 'group_pending_messages', prefix: `${group.groupId}|` }, signal);
+        try {
+            while (true) {
+                const rows = await reader.readNext(128, signal); if (!rows.length) break;
+                for (const row of rows) { requireSafeInteger(row.value.sequence, 1); const result = await this.process(group, row.value.sequence, signal); if (result.state === 'processed') committed(row.value.sequence, result); }
+            }
+        } finally { await reader.dispose(); }
+    }
+    async process(group: GroupRef, sequence: number, signal?: AbortSignal): Promise<GroupMessageProcessingResult> {
+        validateGroupRef(group); requireSafeInteger(sequence, 1); throwIfAborted(signal);
+        const queries = [groupKey(group), groupEventKey(group, sequence), groupPendingMessageKey(group, sequence)];
+        const initial = await this.store.read(queries, signal); const groupRow = initial.sets[0]![0]?.value; const stored = initial.sets[1]![0]?.value;
+        if (groupRow?.relayId !== group.relayId || !stored) throw new ProtocolError('invalid_storage', 'Verified group message or its hosting association is missing.');
+        const projection = decodeGroupProjection(requireObject(groupRow.projection!), group);
+        if (stored.decryptedPayload !== undefined || stored.rejection !== undefined || !initial.sets[2]!.length) return { state: 'alreadyProcessed' };
+        const event = groupEventCodec.decode(stored.event!); const message = requireObject(stored.message!); const sender = deviceCertificateCodec.decode(stored.certificate!);
+        if (event.sequence !== sequence || projection.sequence < sequence || message.sender !== sender.account || message.senderDeviceId !== event.signerDeviceId) throw new ProtocolError('invalid_storage', 'Stored group message evidence has inconsistent identities or sequence.');
+        const envelope = groupMessageEnvelopeCodec.decode(event.payload);
+        if (message.messageId !== envelope.messageId || message.createdAt !== envelope.createdAt || envelope.groupId !== group.groupId || envelope.epoch !== event.epoch) throw new ProtocolError('invalid_storage', 'Stored group envelope differs from its verified metadata.');
+        const epoch = (await this.store.read([groupEpochKey(group, event.epoch)], signal)).sets[0]![0];
+        if (!epoch?.value.commitment) throw new ProtocolError('invalid_storage', 'Verified group message has no established epoch.');
+        // Key access is outside the permanent-content rejection boundary, even when a local provider throws ProtocolError.
+        const secret = await this.secrets.readApplicationSecret(group, event.epoch, signal); if (!secret) return { state: 'waitingForKey' };
+        let payload: JsonObject | undefined; let error: ProtocolError | undefined;
+        try {
+            throwIfAborted(signal); try { requireLength(secret, 32, 'Stored application secret'); } catch (cause) { throw new GroupKeyAccessError('Local group application secret has an invalid length.', { cause }); }
+            try {
+                payload = decryptGroupMessage({ context: this.context, envelope, sender, signerDeviceId: event.signerDeviceId!, applicationSecret: secret }); validateGroupPayload(payload);
+                if (payload.$type === 'meshline.group.message.content' && (groupMessageCodec.decode(payload).replyToSeq ?? 0) >= sequence) throw new ProtocolError('invalid_reply', 'Group reply sequence must precede its containing message.');
+            } catch (cause) { if (!(cause instanceof ProtocolError)) throw cause; error = cause; }
+        } finally { secret.fill(0); }
+        throwIfAborted(signal);
+        return updateStore(this.store, queries, snapshot => {
+            const current = snapshot.sets[1]![0]?.value; const currentGroup = snapshot.sets[0]![0]?.value;
+            if (current?.decryptedPayload !== undefined || current?.rejection !== undefined) return { mutations: [], result: { state: 'alreadyProcessed' } as GroupMessageProcessingResult };
+            if (canonicalJson(current ?? null) !== canonicalJson(stored) || currentGroup?.relayId !== group.relayId) throw new StateConflictError('Group message evidence changed during decryption.');
+            const mutations: StoreMutation[] = [{ kind: 'delete', ...groupPendingMessageKey(group, sequence) }];
+            const result: GroupMessageProcessingResult = error ? { state: 'processed', error } : { state: 'processed' };
+            if (error) mutations.push({ kind: 'put', ...groupEventKey(group, sequence), value: { ...current, rejection: { code: error.code, message: error.message } } });
+            else {
+                const content = payload!; let next = decodeGroupProjection(requireObject(currentGroup.projection!), group); const before = next;
+                if (content.$type === 'meshline.group.member.nickname.update') next = applyGroupNickname(next, this.accountId, sender.account, sequence, groupMemberNicknameUpdateCodec.decode(content).nickname);
+                const groupRecord = next === before ? undefined : { ...currentGroup, projection: encodeGroupProjection(next) };
+                if (groupRecord) mutations.push({ kind: 'put', ...groupKey(group), value: groupRecord });
+                const isMessage = content.$type === 'meshline.group.message.content';
+                mutations.push({ kind: 'put', ...groupEventKey(group, sequence), value: { ...current, decryptedPayload: content, isMessage } });
+                return { mutations, result: { state: 'processed', ...(groupRecord ? { nicknameChanged: true, groupRecord } : {}), ...(isMessage ? { message: {
+                    ...groupMessageCodec.decode(content), group: { ...group }, sequence, sender: sender.account, senderDeviceId: event.signerDeviceId!, messageId: envelope.messageId, createdAt: envelope.createdAt, acceptedAt: event.acceptedAt,
+                } } : {}) } as GroupMessageProcessingResult };
+            }
+            return { mutations, result };
+        }, signal);
+    }
+}