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

package/src/models/contacts.ts

@@ -0,0 +1,141 @@
+import { requireLength, verifyDevice } from '../crypto/primitives.js';
+import { ProtocolError } from '../errors.js';
+import { validateIdentifier } from '../identity/identifiers.js';
+import { validateAccountId } from '../identity/neo.js';
+import { array, boolean, bytes, defineCodec, dictionary, enumeration, integer, text, type ExtensibleModel, type ValueCodec } from '../protocol/codec.js';
+import { signingInput, type NetworkContext } from '../protocol/context.js';
+import { encodeUtf8, equalBytes } from '../protocol/encoding.js';
+import { requireObject, requireSafeInteger } from '../protocol/json.js';
+import { validateCompleteObject } from '../protocol/validation.js';
+import { containsNonWhitespace } from './content.js';
+import { accountDeviceStateCodec, authorizedDevice, certificateId, deviceCertificateCodec, validateCertificate, validateDeviceState, type AccountDeviceState, type DeviceCertificate } from './identity.js';
+
+export interface ContactGrant extends ExtensibleModel { readonly grantor: string; readonly grantee: string; readonly expiresAt?: number; readonly signatures: Readonly<Record<string, Uint8Array>> }
+export const contactGrantCodec = defineCodec<ContactGrant>({ grantor: { wire: 'grantor', codec: text }, grantee: { wire: 'grantee', codec: text },
+    expiresAt: { wire: 'expires_at', codec: integer, optional: true }, signatures: { wire: 'signatures', codec: dictionary(bytes) } }, 'meshline.contact.grant');
+export const contactGrantInput = (value: ContactGrant, context: NetworkContext): Uint8Array => signingInput(contactGrantCodec.encode(value), context, ['signatures']);
+export function validateContactGrant(value: ContactGrant, now: number): void {
+    validateCompleteObject(contactGrantCodec.encode(value));
+    validateAccountId(value.grantor); validateAccountId(value.grantee); requireSafeInteger(now, 0);
+    if (value.expiresAt !== undefined) { requireSafeInteger(value.expiresAt, 0); if (value.expiresAt <= now) throw new ProtocolError('expired_grant', 'Contact grant has expired.'); }
+    const signatures = Object.entries(value.signatures);
+    if (!signatures.length) throw new ProtocolError('invalid_grant', 'A contact grant requires at least one signature.');
+    for (const [id, signature] of signatures) { validateIdentifier('device', id); requireLength(signature, 64, 'Grant signature'); }
+    contactGrantCodec.encode(value);
+}
+export function verifyContactGrant(value: ContactGrant, state: AccountDeviceState, context: NetworkContext, now: number): void {
+    if (Object.keys(filterContactGrantSignatures(value, state, context, now).signatures).length === 0)
+        throw new ProtocolError('unauthorized_grant', 'Contact grant has no valid signature from a currently authorized device.');
+}
+/** Returns a copy containing only signatures whose device identity is currently authorized by the verified state. */
+export function filterContactGrantSignatures(value: ContactGrant, state: AccountDeviceState, context: NetworkContext, now: number): ContactGrant {
+    validateContactGrant(value, now); validateDeviceState(state, context);
+    if (value.grantor !== state.account) throw new ProtocolError('invalid_identity', 'Contact grant state belongs to another grantor.');
+    const input = contactGrantInput(value, context);
+    const signatures: Record<string, Uint8Array> = Object.create(null) as Record<string, Uint8Array>;
+    for (const certificate of state.certificates) {
+        const id = certificateId(certificate, context); const signature = value.signatures[id];
+        if (certificate.notBefore <= now && now < certificate.expiresAt && signature !== undefined && verifyDevice(input, signature, certificate.signingPublicKey)) signatures[id] = signature.slice();
+    }
+    return contactGrantCodec.decode(contactGrantCodec.encode({ ...value, signatures }));
+}
+export interface ContactGrantSelection { readonly action: 'replace' | 'keep' | 'merge' | 'out_of_scope' | 'invalid'; readonly grant: ContactGrant | undefined; readonly error?: unknown }
+/** Saved grants are scoped to one network/account direction. Equal-expiry bodies never replace differing signed extensions. */
+export function selectContactGrant(current: ContactGrant | undefined, candidate: ContactGrant, state: AccountDeviceState,
+    context: NetworkContext, now: number, candidateContext = context): ContactGrantSelection {
+    const previous = current && contactGrantCodec.decode(contactGrantCodec.encode(current));
+    if (candidateContext.toString() !== context.toString() || previous && (candidate.grantor !== previous.grantor || candidate.grantee !== previous.grantee))
+        return { action: 'out_of_scope', grant: previous };
+    let incoming: ContactGrant;
+    try {
+        incoming = filterContactGrantSignatures(candidate, state, context, now);
+        if (Object.keys(incoming.signatures).length === 0) throw new ProtocolError('unauthorized_grant', 'Candidate has no currently authorized signature.');
+    } catch (error) { if (!(error instanceof ProtocolError)) throw error; return { action: 'invalid', grant: previous, error }; }
+    if (!previous) return { action: 'replace', grant: incoming };
+    if (!equalBytes(contactGrantInput(previous, context), contactGrantInput(incoming, context)))
+        return (incoming.expiresAt ?? Infinity) > (previous.expiresAt ?? Infinity) ? { action: 'replace', grant: incoming } : { action: 'keep', grant: previous };
+    const saved = filterContactGrantSignatures(previous, state, context, now);
+    return { action: 'merge', grant: { ...incoming, signatures: { ...incoming.signatures, ...saved.signatures } } };
+}
+export interface ContactInvite extends ExtensibleModel { readonly inviter: string; readonly expiresAt: number; readonly signerDeviceId: string; readonly deviceSignature: Uint8Array }
+export const contactInviteCodec = defineCodec<ContactInvite>({ inviter: { wire: 'inviter', codec: text }, expiresAt: { wire: 'expires_at', codec: integer },
+    signerDeviceId: { wire: 'signer_device_id', codec: text }, deviceSignature: { wire: 'device_signature', codec: bytes } }, 'meshline.contact.invite');
+export const contactInviteInput = (value: ContactInvite, context: NetworkContext): Uint8Array => signingInput(contactInviteCodec.encode(value), context, ['device_signature']);
+export function validateContactInvite(value: ContactInvite, now: number): void {
+    validateCompleteObject(contactInviteCodec.encode(value));
+    validateAccountId(value.inviter); requireSafeInteger(now, 0); requireSafeInteger(value.expiresAt, 0);
+    validateIdentifier('device', value.signerDeviceId); requireLength(value.deviceSignature, 64, 'Invitation signature');
+    if (value.expiresAt <= now) throw new ProtocolError('expired_invite', 'Contact invitation has expired.'); contactInviteCodec.encode(value);
+}
+export function verifyContactInvite(value: ContactInvite, state: AccountDeviceState, context: NetworkContext, now: number): void {
+    validateContactInvite(value, now); validateDeviceState(state, context);
+    if (value.inviter !== state.account) throw new ProtocolError('invalid_identity', 'Invitation belongs to another account.');
+    const certificate = authorizedDevice(state, value.signerDeviceId, context, now);
+    if (!verifyDevice(contactInviteInput(value, context), value.deviceSignature, certificate.signingPublicKey)) throw new ProtocolError('invalid_signature', 'Invalid contact invitation signature.');
+}
+export type ContactAuthorization = ContactGrant | ContactInvite;
+export const contactAuthorizationCodec: ValueCodec<ContactAuthorization> = {
+    decode(value) {
+        const type = requireObject(value)['$type'];
+        if (type === 'meshline.contact.grant') return contactGrantCodec.decode(value);
+        if (type === 'meshline.contact.invite') return contactInviteCodec.decode(value);
+        throw new ProtocolError('invalid_type', 'Expected a contact grant or invitation.');
+    },
+    encode(value) { return 'grantor' in value ? contactGrantCodec.encode(value) : contactInviteCodec.encode(value); },
+};
+export interface SignedDeviceStateQuery extends ExtensibleModel {
+    readonly account: string; readonly authorization: ContactAuthorization; readonly signerCertificate: DeviceCertificate; readonly createdAt: number; readonly deviceSignature: Uint8Array;
+}
+export const signedDeviceStateQueryCodec = defineCodec<SignedDeviceStateQuery>({ account: { wire: 'account', codec: text }, authorization: { wire: 'authorization', codec: contactAuthorizationCodec },
+    signerCertificate: { wire: 'signer_certificate', codec: deviceCertificateCodec }, createdAt: { wire: 'created_at', codec: integer }, deviceSignature: { wire: 'device_signature', codec: bytes } }, 'meshline.device.state.resolve');
+export const deviceStateQueryInput = (value: SignedDeviceStateQuery, context: NetworkContext): Uint8Array => signingInput(signedDeviceStateQueryCodec.encode(value), context, ['device_signature']);
+export function validateDeviceStateQuery(value: SignedDeviceStateQuery, context: NetworkContext, now: number): void {
+    validateCompleteObject(signedDeviceStateQueryCodec.encode(value));
+    validateAccountId(value.account); validateCertificate(value.signerCertificate, context); requireSafeInteger(value.createdAt, 0);
+    if (value.account === value.signerCertificate.account) throw new ProtocolError('invalid_authorization', 'Signed device queries cannot target the caller account.');
+    if ('grantor' in value.authorization) {
+        validateContactGrant(value.authorization, now);
+        if (value.authorization.grantor !== value.account || value.authorization.grantee !== value.signerCertificate.account) throw new ProtocolError('invalid_authorization', 'Contact grant does not authorize this query.');
+    } else { validateContactInvite(value.authorization, now); if (value.authorization.inviter !== value.account) throw new ProtocolError('invalid_authorization', 'Invitation is for another account.'); }
+    if (!verifyDevice(deviceStateQueryInput(value, context), value.deviceSignature, value.signerCertificate.signingPublicKey)) throw new ProtocolError('invalid_signature', 'Invalid signed device query.');
+}
+export interface ContactConsent extends ExtensibleModel { readonly deviceState: AccountDeviceState; readonly grant: ContactGrant; readonly note?: string }
+export const contactConsentCodec = defineCodec<ContactConsent>({ deviceState: { wire: 'device_state', codec: accountDeviceStateCodec }, grant: { wire: 'grant', codec: contactGrantCodec }, note: { wire: 'note', codec: text, optional: true } }, 'meshline.contact.consent');
+export function validateContactConsent(value: ContactConsent, context: NetworkContext, now: number): void {
+    validateCompleteObject(contactConsentCodec.encode(value));
+    if (value.note !== undefined && (!containsNonWhitespace(value.note) || encodeUtf8(value.note).length > 1024)) throw new ProtocolError('invalid_note', 'Consent note must contain non-whitespace text and fit 1024 UTF-8 bytes.');
+    verifyContactGrant(value.grant, value.deviceState, context, now); contactConsentCodec.encode(value);
+}
+export interface ContactRecord extends ExtensibleModel {
+    readonly account: string; readonly alias?: string; readonly status: 'active' | 'deleted';
+    readonly grantFromContact?: ContactGrant; readonly grantToContact?: ContactGrant; readonly updatedAt: number;
+}
+export const contactRecordCodec = defineCodec<ContactRecord>({ account: { wire: 'account', codec: text }, alias: { wire: 'alias', codec: text, optional: true }, status: { wire: 'status', codec: enumeration('active', 'deleted') },
+    grantFromContact: { wire: 'grant_from_contact', codec: contactGrantCodec, optional: true }, grantToContact: { wire: 'grant_to_contact', codec: contactGrantCodec, optional: true }, updatedAt: { wire: 'updated_at', codec: integer } });
+export function validateContactRecord(value: ContactRecord, now: number): void {
+    validateCompleteObject(contactRecordCodec.encode(value));
+    validateAccountId(value.account); requireSafeInteger(value.updatedAt, 0); requireSafeInteger(now, 0);
+    if (value.updatedAt > now + 300) throw new ProtocolError('invalid_time', 'Contact update is more than five minutes in the future.');
+    if (value.alias !== undefined && value.alias !== '' && (!containsNonWhitespace(value.alias) || encodeUtf8(value.alias).length > 256)) throw new ProtocolError('invalid_alias', 'Nonempty contact alias must contain non-whitespace text and fit 256 UTF-8 bytes.');
+    if (value.status === 'deleted' && (value.grantFromContact || value.grantToContact)) throw new ProtocolError('invalid_contact', 'Deleted contact records cannot contain grants.');
+    contactRecordCodec.encode(value);
+}
+export interface AccountContactSync extends ExtensibleModel { readonly records?: readonly ContactRecord[]; readonly requestSnapshot?: boolean }
+export const accountContactSyncCodec = defineCodec<AccountContactSync>({ records: { wire: 'records', codec: array(contactRecordCodec), optional: true }, requestSnapshot: { wire: 'request_snapshot', codec: boolean, optional: true } }, 'meshline.account.contacts.sync');
+export function validateAccountContactSync(value: AccountContactSync, now: number, ownerAccount?: string): void {
+    validateCompleteObject(accountContactSyncCodec.encode(value));
+    const accounts = new Set<string>(); let owner = ownerAccount;
+    for (const record of value.records ?? []) {
+        validateContactRecord(record, now);
+        if (accounts.has(record.account)) throw new ProtocolError('duplicate_contact', 'A contact sync batch cannot contain duplicate accounts.'); accounts.add(record.account);
+        if (record.grantFromContact) {
+            const grant = record.grantFromContact; validateContactGrant(grant, now);
+            if (grant.grantor !== record.account || owner !== undefined && grant.grantee !== owner) throw new ProtocolError('invalid_identity', 'Incoming contact grant has inconsistent accounts.'); owner = grant.grantee;
+        }
+        if (record.grantToContact) {
+            const grant = record.grantToContact; validateContactGrant(grant, now);
+            if (grant.grantee !== record.account || owner !== undefined && grant.grantor !== owner) throw new ProtocolError('invalid_identity', 'Outgoing contact grant has inconsistent accounts.'); owner = grant.grantor;
+        }
+    }
+    if (owner !== undefined && accounts.has(owner)) throw new ProtocolError('invalid_identity', 'A contact sync batch cannot contain its owner.'); accountContactSyncCodec.encode(value);
+}

package/src/models/content.ts

@@ -0,0 +1,105 @@
+import { decryptAes, encryptAes, requireLength, sha256 } from '../crypto/primitives.js';
+import { ProtocolError } from '../errors.js';
+import { bytes, defineCodec, integer, text, type ExtensibleModel } from '../protocol/codec.js';
+import { decodeBase64Url, encodeUtf8, equalBytes } from '../protocol/encoding.js';
+import { canonicalBytes, requireSafeInteger } from '../protocol/json.js';
+import { validateCompleteObject } from '../protocol/validation.js';
+import { parseAbsoluteUrl } from '../runtime/url.js';
+
+/** Protocol Unicode 17 White_Space, deliberately independent of JavaScript trim(). */
+export function containsNonWhitespace(value: string): boolean { return /[^\u0009-\u000d\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]/u.test(value); }
+const token = "[!#$%&'*+.^_`|~0-9A-Za-z-]+";
+const quoted = '"(?:[\\t\\x20\\x21\\x23-\\x5B\\x5D-\\x7E\\x80-\\xFF]|\\\\[\\t\\x20-\\x7E\\x80-\\xFF])*"';
+const mediaStart = new RegExp(`^${token}/${token}`);
+const mediaParameter = new RegExp(`[ \\t]*;[ \\t]*(?:(${token})=(${token}|${quoted}))?`, 'y');
+/** RFC 9110 grammar; repeated charset parameters must all specify UTF-8 for bodies. */
+export function validateMediaType(value: string, requireUtf8 = false): void {
+    if (typeof value !== 'string') throw new ProtocolError('invalid_media_type', 'Expected a media type.');
+    const start = mediaStart.exec(value);
+    if (!start) throw new ProtocolError('invalid_media_type', 'Invalid media type.');
+    let offset = start[0].length;
+    while (offset < value.length) {
+        mediaParameter.lastIndex = offset;
+        const parameter = mediaParameter.exec(value);
+        if (!parameter) throw new ProtocolError('invalid_media_type', 'Invalid media type parameter.');
+        if (requireUtf8 && parameter[1]?.toLowerCase() === 'charset') {
+            const raw = parameter[2]!;
+            const charset = raw.startsWith('"') ? raw.slice(1, -1).replace(/\\([\s\S])/g, '$1') : raw;
+            if (charset.toLowerCase() !== 'utf-8') throw new ProtocolError('invalid_charset', 'Message body charset must be UTF-8.');
+        }
+        offset = mediaParameter.lastIndex;
+    }
+}
+export interface ContentEncryption extends ExtensibleModel { readonly alg: string; readonly key: Uint8Array; readonly nonce: Uint8Array }
+export const contentEncryptionCodec = defineCodec<ContentEncryption>({ alg: { wire: 'alg', codec: text }, key: { wire: 'key', codec: bytes }, nonce: { wire: 'nonce', codec: bytes } });
+export function validateContentEncryption(value: ContentEncryption): void {
+    validateCompleteObject(contentEncryptionCodec.encode(value));
+    if (value.alg !== 'AES-256-GCM') throw new ProtocolError('unsupported_algorithm', 'Content encryption must use AES-256-GCM.');
+    requireLength(value.key, 32, 'Content key'); requireLength(value.nonce, 12, 'Content nonce');
+}
+export interface ContentReference extends ExtensibleModel {
+    readonly uri: string; readonly hash: string; readonly contentType: string; readonly size: number; readonly encryption?: ContentEncryption;
+}
+export const contentReferenceCodec = defineCodec<ContentReference>({ uri: { wire: 'uri', codec: text }, hash: { wire: 'hash', codec: text },
+    contentType: { wire: 'content_type', codec: text }, size: { wire: 'size', codec: integer }, encryption: { wire: 'encryption', codec: contentEncryptionCodec, optional: true } });
+export function contentHashBytes(hash: string): Uint8Array {
+    if (typeof hash !== 'string' || !hash.startsWith('sha256:')) throw new ProtocolError('invalid_hash', 'Expected a sha256 content hash.');
+    const bytes = decodeBase64Url(hash.slice(7)); requireLength(bytes, 32, 'Content hash'); return bytes;
+}
+export function validateContentReference(value: ContentReference): void {
+    validateCompleteObject(contentReferenceCodec.encode(value));
+    encodeUtf8(value.uri);
+    if (!/^https:\/\//i.test(value.uri) || /[\s\u0085\x00-\x1f\x7f-\x9f\\]/u.test(value.uri) || /%(?![0-9a-fA-F]{2})/.test(value.uri))
+        throw new ProtocolError('invalid_uri', 'Content requires a well-formed absolute HTTPS URI.');
+    try { if (!parseAbsoluteUrl(value.uri).hostname) throw new Error('Missing host'); }
+    catch (cause) { throw new ProtocolError('invalid_uri', 'Content requires a valid HTTPS host.', { cause }); }
+    contentHashBytes(value.hash); requireSafeInteger(value.size, 0); validateMediaType(value.contentType);
+    if (value.encryption) validateContentEncryption(value.encryption);
+    contentReferenceCodec.encode(value);
+}
+export function contentHashUri(value: ContentReference): string { contentHashBytes(value.hash); return `ni:///sha-256;${value.hash.slice(7)}`; }
+export function validateAttachments(attachments: readonly ContentReference[]): void {
+    const hashes = new Set<string>();
+    for (const reference of attachments) {
+        validateContentReference(reference);
+        if (hashes.has(reference.hash)) throw new ProtocolError('duplicate_attachment', 'Attachments cannot contain duplicate plaintext hashes.');
+        hashes.add(reference.hash);
+    }
+}
+export function resolveContentReference(uri: string, attachments: readonly ContentReference[]): ContentReference | undefined {
+    validateAttachments(attachments);
+    if (!/^ni:\/\/\//i.test(uri) || /[/?#]/.test(uri.slice(6))) return undefined;
+    const separator = uri.indexOf(';', 6); if (separator < 0) return undefined;
+    try {
+        if (decodeURIComponent(uri.slice(6, separator)) !== 'sha-256') return undefined;
+        const hash = `sha256:${decodeURIComponent(uri.slice(separator + 1))}`; contentHashBytes(hash);
+        return attachments.find(value => value.hash === hash);
+    } catch { return undefined; } // Malformed user-facing ni links are simply unresolved.
+}
+export function verifyContent(value: ContentReference, plaintext: Uint8Array): void {
+    if (plaintext.length !== value.size || !equalBytes(sha256(plaintext), contentHashBytes(value.hash)))
+        throw new ProtocolError('invalid_content', 'Plaintext does not match the content size and hash.');
+}
+export function contentEncryptionAad(value: ContentReference): Uint8Array {
+    if (!value.encryption) throw new ProtocolError('encryption_required', 'Content reference has no encryption parameters.');
+    validateContentReference(value);
+    return canonicalBytes({ $type: 'meshline.content.reference.aad', alg: value.encryption.alg, hash: value.hash, content_type: value.contentType, size: value.size });
+}
+/** Low-level helper; the caller supplies a fresh independent key and nonce for every attachment. */
+export function encryptContent(value: ContentReference, plaintext: Uint8Array): Uint8Array {
+    const aad = contentEncryptionAad(value); verifyContent(value, plaintext);
+    return encryptAes(value.encryption!.key, value.encryption!.nonce, plaintext, aad);
+}
+export function decryptContent(value: ContentReference, ciphertext: Uint8Array): Uint8Array {
+    const aad = contentEncryptionAad(value);
+    const plaintext = decryptAes(value.encryption!.key, value.encryption!.nonce, ciphertext, aad);
+    try { verifyContent(value, plaintext); return plaintext; } catch (error) { plaintext.fill(0); throw error; }
+}
+export interface MessageBody extends ExtensibleModel { readonly contentType: string; readonly text: string }
+export const messageBodyCodec = defineCodec<MessageBody>({ contentType: { wire: 'content_type', codec: text }, text: { wire: 'text', codec: text } });
+export function validateMessageBody(value: MessageBody): void {
+    validateCompleteObject(messageBodyCodec.encode(value));
+    validateMediaType(value.contentType, true); encodeUtf8(value.text);
+    if (!containsNonWhitespace(value.text)) throw new ProtocolError('invalid_body', 'Message body must contain non-whitespace text.');
+    messageBodyCodec.encode(value);
+}

package/src/models/device-state.ts

@@ -0,0 +1,18 @@
+import { ProtocolError } from '../errors.js';
+import { defineCodec, enumeration, integer, type ExtensibleModel } from '../protocol/codec.js';
+import { requireSafeInteger } from '../protocol/json.js';
+import { validateCompleteObject } from '../protocol/validation.js';
+
+export interface DeviceStatePublishResponse extends ExtensibleModel { readonly status: 'accepted' | 'staged'; readonly stagedUntil?: number }
+export const deviceStatePublishResponseCodec = defineCodec<DeviceStatePublishResponse>({
+    status: { wire: 'status', codec: enumeration('accepted', 'staged') }, stagedUntil: { wire: 'staged_until', codec: integer, optional: true },
+});
+export function validateDeviceStatePublishResponse(value: DeviceStatePublishResponse, now: number): void {
+    validateCompleteObject(deviceStatePublishResponseCodec.encode(value));
+    if (value.status === 'accepted') {
+        if (value.stagedUntil !== undefined) throw new ProtocolError('invalid_response', 'An accepted device state must omit staged_until.');
+    } else if (value.status === 'staged') {
+        requireSafeInteger(value.stagedUntil, 1);
+        if (value.stagedUntil <= now) throw new ProtocolError('invalid_response', 'The staged device state has already expired.');
+    } else throw new ProtocolError('invalid_response', 'Unknown device state publication status.');
+}

package/src/models/group-admission.ts

@@ -0,0 +1,110 @@
+import { ProtocolError } from '../errors.js';
+import { validateIdentifier } from '../identity/identifiers.js';
+import { validateAccountId } from '../identity/neo.js';
+import { array, defineCodec, dictionary, integer, text, type ExtensibleModel } from '../protocol/codec.js';
+import type { NetworkContext } from '../protocol/context.js';
+import { requireSafeInteger } from '../protocol/json.js';
+import { validateCompleteObject } from '../protocol/validation.js';
+import { contentHashBytes } from './content.js';
+import { groupApplicationApprovalCodec, groupApplicationCodec, groupInviteCodec, groupMemberRecoveryApprovalCodec, groupMemberRecoveryRequestCodec, validateGroupManagementPayload, verifyGroupApplication, verifyGroupInvite, verifyGroupMemberRecoveryRequest,
+    type GroupApplication, type GroupApplicationApproval, type GroupInvite, type GroupMemberRecoveryApproval, type GroupMemberRecoveryRequest } from './group-management.js';
+import { groupSecretBoxCodec, validateGroupSecretBox, type GroupSecretBox } from './groups.js';
+import { certificateId, deviceCertificateCodec, validateCertificate, type DeviceCertificate } from './identity.js';
+
+const groupId = { wire: 'group_id', codec: text } as const;
+const signerCertificate = { wire: 'signer_certificate', codec: deviceCertificateCodec } as const;
+const acceptedAt = { wire: 'accepted_at', codec: integer } as const;
+const next = { wire: 'next', codec: text, optional: true } as const;
+const certificates = { wire: 'certificates', codec: array(deviceCertificateCodec) } as const;
+function cursor(value: string): void { if (!/^[A-Za-z0-9._~-]+$/.test(value) || /[^A-Za-z0-9._~-]/.test(value)) throw new ProtocolError('invalid_cursor', 'Group list cursor must contain nonempty ASCII URL-safe text.'); }
+export interface GroupListQuery extends ExtensibleModel { readonly groupId: string; readonly cursor?: string; readonly limit?: number }
+export const groupListQueryCodec = defineCodec<GroupListQuery>({ groupId, cursor: { wire: 'cursor', codec: text, optional: true }, limit: { wire: 'limit', codec: integer, optional: true } });
+export function validateGroupListQuery(value: GroupListQuery): void { validateCompleteObject(groupListQueryCodec.encode(value)); validateIdentifier('group', value.groupId); if (value.cursor !== undefined) cursor(value.cursor); if (value.limit !== undefined) requireSafeInteger(value.limit, 1); }
+function page(count: number, nextCursor: string | undefined, query: GroupListQuery): void {
+    validateGroupListQuery(query); if (nextCursor !== undefined) cursor(nextCursor);
+    if (nextCursor !== undefined && (!count || nextCursor === query.cursor) || query.limit !== undefined && count > query.limit) throw new ProtocolError('invalid_pagination', 'Group list is empty with a continuation, repeats its cursor, or exceeds the requested limit.');
+}
+export interface GroupInviteQuery extends ExtensibleModel { readonly groupId: string; readonly inviteId: string }
+export const groupInviteQueryCodec = defineCodec<GroupInviteQuery>({ groupId, inviteId: { wire: 'invite_id', codec: text } });
+export function validateGroupInviteQuery(value: GroupInviteQuery): void { validateCompleteObject(groupInviteQueryCodec.encode(value)); validateIdentifier('group', value.groupId); validateIdentifier('invite', value.inviteId); }
+export interface GroupResolveQuery extends ExtensibleModel { readonly groupId: string; readonly inviteId?: string }
+export const groupResolveQueryCodec = defineCodec<GroupResolveQuery>({ groupId, inviteId: { wire: 'invite_id', codec: text, optional: true } });
+export function validateGroupResolveQuery(value: GroupResolveQuery): void { validateCompleteObject(groupResolveQueryCodec.encode(value)); validateIdentifier('group', value.groupId); if (value.inviteId !== undefined) validateIdentifier('invite', value.inviteId); }
+export interface GroupAccountsRequest extends ExtensibleModel { readonly groupId: string; readonly accounts: readonly string[] }
+export const groupAccountsRequestCodec = defineCodec<GroupAccountsRequest>({ groupId, accounts: { wire: 'accounts', codec: array(text) } });
+export function validateGroupAccountsRequest(value: GroupAccountsRequest): void {
+    validateCompleteObject(groupAccountsRequestCodec.encode(value)); validateIdentifier('group', value.groupId);
+    if (!value.accounts.length || new Set(value.accounts).size !== value.accounts.length) throw new ProtocolError('invalid_accounts', 'Group account list must be nonempty and unique.'); for (const account of value.accounts) validateAccountId(account);
+}
+export interface GroupInviteResolveResult extends ExtensibleModel { readonly invite: GroupInvite; readonly signerCertificate: DeviceCertificate; readonly uses: number }
+export const groupInviteResolveResultCodec = defineCodec<GroupInviteResolveResult>({ invite: { wire: 'invite', codec: groupInviteCodec }, signerCertificate, uses: { wire: 'uses', codec: integer } });
+export function validateGroupInviteResolveResult(value: GroupInviteResolveResult, query: GroupInviteQuery, context: NetworkContext, now: number): void {
+    validateCompleteObject(groupInviteResolveResultCodec.encode(value)); validateGroupInviteQuery(query); verifyGroupInvite(value.invite, value.signerCertificate, context, now); requireSafeInteger(value.uses, 0);
+    if (value.invite.groupId !== query.groupId || value.invite.inviteId !== query.inviteId) throw new ProtocolError('invalid_binding', 'Relay returned another group invitation.');
+    if (value.invite.invitee !== undefined && value.uses > 1 || value.invite.maxUses !== undefined && value.uses > value.invite.maxUses) throw new ProtocolError('invalid_uses', 'Invitation use count exceeds its limit.');
+}
+export interface GroupInviteEntry extends ExtensibleModel { readonly invite: GroupInvite; readonly signerDeviceId: string; readonly uses: number }
+export const groupInviteEntryCodec = defineCodec<GroupInviteEntry>({ invite: { wire: 'invite', codec: groupInviteCodec }, signerDeviceId: { wire: 'signer_device_id', codec: text }, uses: { wire: 'uses', codec: integer } });
+export interface GroupInvitePage extends ExtensibleModel { readonly invites: readonly GroupInviteEntry[]; readonly certificates: readonly DeviceCertificate[]; readonly next?: string }
+export const groupInvitePageCodec = defineCodec<GroupInvitePage>({ invites: { wire: 'invites', codec: array(groupInviteEntryCodec) }, certificates, next });
+export function validateGroupInvitePage(value: GroupInvitePage, query: GroupListQuery, context: NetworkContext, now: number): void {
+    validateCompleteObject(groupInvitePageCodec.encode(value)); page(value.invites.length, value.next, query);
+    const signers = new Map<string, DeviceCertificate>(); for (const certificate of value.certificates) { validateCertificate(certificate, context); const id = certificateId(certificate, context); if (signers.has(id)) throw new ProtocolError('duplicate_certificate', 'Invitation page repeats a signing device.'); signers.set(id, certificate); }
+    const ids = new Set<string>(); for (const entry of value.invites) {
+        validateIdentifier('device', entry.signerDeviceId); const signer = signers.get(entry.signerDeviceId); if (!signer) throw new ProtocolError('missing_certificate', 'Invitation signing certificate is missing.');
+        if (ids.has(entry.invite.inviteId)) throw new ProtocolError('duplicate_invite', 'Invitation page repeats an invitation.'); ids.add(entry.invite.inviteId);
+        validateGroupInviteResolveResult({ invite: entry.invite, signerCertificate: signer, uses: entry.uses }, { groupId: query.groupId, inviteId: entry.invite.inviteId }, context, now);
+    }
+}
+export interface GroupApplicationEntry extends ExtensibleModel { readonly application: GroupApplication; readonly signerCertificate: DeviceCertificate; readonly acceptedAt: number }
+export const groupApplicationEntryCodec = defineCodec<GroupApplicationEntry>({ application: { wire: 'application', codec: groupApplicationCodec }, signerCertificate, acceptedAt });
+export function validateGroupApplicationEntry(value: GroupApplicationEntry, expectedGroupId: string, context: NetworkContext): void {
+    validateCompleteObject(groupApplicationEntryCodec.encode(value)); validateIdentifier('group', expectedGroupId); requireSafeInteger(value.acceptedAt, 0); verifyGroupApplication(value.application, value.signerCertificate, context);
+    if (value.application.groupId !== expectedGroupId) throw new ProtocolError('invalid_binding', 'Application belongs to another group.');
+}
+export interface GroupApplicationPage extends ExtensibleModel { readonly applications: readonly GroupApplicationEntry[]; readonly next?: string }
+export const groupApplicationPageCodec = defineCodec<GroupApplicationPage>({ applications: { wire: 'applications', codec: array(groupApplicationEntryCodec) }, next });
+export function validateGroupApplicationPage(value: GroupApplicationPage, query: GroupListQuery, context: NetworkContext): void {
+    validateCompleteObject(groupApplicationPageCodec.encode(value)); page(value.applications.length, value.next, query); const accounts = new Set<string>();
+    for (const entry of value.applications) { validateGroupApplicationEntry(entry, query.groupId, context); if (accounts.has(entry.application.account)) throw new ProtocolError('duplicate_account', 'Application page repeats an account.'); accounts.add(entry.application.account); }
+}
+export interface GroupRecoverySubmitResult extends ExtensibleModel { readonly acceptedAt: number; readonly expiresAt: number }
+const recoveryInterval = { acceptedAt, expiresAt: { wire: 'expires_at', codec: integer } } as const;
+export const groupRecoverySubmitResultCodec = defineCodec<GroupRecoverySubmitResult>(recoveryInterval);
+export function validateGroupRecoverySubmitResult(value: GroupRecoverySubmitResult): void {
+    validateCompleteObject(groupRecoverySubmitResultCodec.encode(value)); requireSafeInteger(value.acceptedAt, 0); requireSafeInteger(value.expiresAt, 0);
+    if (value.expiresAt <= value.acceptedAt) throw new ProtocolError('invalid_expiry', 'Recovery acceptance interval must have a later expiry.');
+}
+export interface GroupRecoveryEntry extends ExtensibleModel, GroupRecoverySubmitResult { readonly request: GroupMemberRecoveryRequest; readonly signerCertificate: DeviceCertificate }
+export const groupRecoveryEntryCodec = defineCodec<GroupRecoveryEntry>({ request: { wire: 'request', codec: groupMemberRecoveryRequestCodec }, signerCertificate, ...recoveryInterval });
+export function validateGroupRecoveryEntry(value: GroupRecoveryEntry, expectedGroupId: string, context: NetworkContext): void {
+    validateCompleteObject(groupRecoveryEntryCodec.encode(value)); validateIdentifier('group', expectedGroupId); validateGroupRecoverySubmitResult({ acceptedAt: value.acceptedAt, expiresAt: value.expiresAt }); verifyGroupMemberRecoveryRequest(value.request, value.signerCertificate, context);
+    if (value.request.groupId !== expectedGroupId) throw new ProtocolError('invalid_binding', 'Recovery request belongs to another group.');
+}
+export interface GroupRecoveryPage extends ExtensibleModel { readonly requests: readonly GroupRecoveryEntry[]; readonly next?: string }
+export const groupRecoveryPageCodec = defineCodec<GroupRecoveryPage>({ requests: { wire: 'requests', codec: array(groupRecoveryEntryCodec) }, next });
+export function validateGroupRecoveryPage(value: GroupRecoveryPage, query: GroupListQuery, context: NetworkContext): void {
+    validateCompleteObject(groupRecoveryPageCodec.encode(value)); page(value.requests.length, value.next, query); const accounts = new Set<string>();
+    for (const entry of value.requests) { validateGroupRecoveryEntry(entry, query.groupId, context); if (accounts.has(entry.request.account)) throw new ProtocolError('duplicate_account', 'Recovery page repeats an account.'); accounts.add(entry.request.account); }
+}
+export interface GroupApplicationApproveRequest extends ExtensibleModel { readonly approval: GroupApplicationApproval; readonly clientSecretCommitment: string; readonly clientSecretBoxes: Readonly<Record<string, GroupSecretBox>> }
+export interface GroupRecoveryApproveRequest extends ExtensibleModel { readonly approval: GroupMemberRecoveryApproval; readonly clientSecretCommitment: string; readonly clientSecretBoxes: Readonly<Record<string, GroupSecretBox>> }
+const wrapping = { clientSecretCommitment: { wire: 'client_secret_commitment', codec: text }, clientSecretBoxes: { wire: 'client_secret_boxes', codec: dictionary(groupSecretBoxCodec) } } as const;
+export const groupApplicationApproveRequestCodec = defineCodec<GroupApplicationApproveRequest>({ approval: { wire: 'approval', codec: groupApplicationApprovalCodec }, ...wrapping });
+export const groupRecoveryApproveRequestCodec = defineCodec<GroupRecoveryApproveRequest>({ approval: { wire: 'approval', codec: groupMemberRecoveryApprovalCodec }, ...wrapping });
+function boxes(value: GroupApplicationApproveRequest | GroupRecoveryApproveRequest): void {
+    contentHashBytes(value.clientSecretCommitment);
+    if (Object.keys(value.clientSecretBoxes).length !== value.approval.members.length) throw new ProtocolError('invalid_recipients', 'Client secret boxes must match exactly the approved accounts.');
+    for (const member of value.approval.members) { if (!Object.hasOwn(value.clientSecretBoxes, member.account)) throw new ProtocolError('invalid_recipients', 'An approved account is missing its client secret box.'); validateGroupSecretBox(value.clientSecretBoxes[member.account]!); }
+}
+export function validateGroupApplicationApproveRequest(value: GroupApplicationApproveRequest): void { validateCompleteObject(groupApplicationApproveRequestCodec.encode(value)); validateGroupManagementPayload({ kind: 'applicationApproval', value: value.approval }); boxes(value); }
+export function validateGroupRecoveryApproveRequest(value: GroupRecoveryApproveRequest): void { validateCompleteObject(groupRecoveryApproveRequestCodec.encode(value)); validateGroupManagementPayload({ kind: 'memberRecoveryApproval', value: value.approval }); boxes(value); }
+export interface GroupSubscriptionRequest extends ExtensibleModel { readonly groupIds: readonly string[] }
+export const groupSubscriptionRequestCodec = defineCodec<GroupSubscriptionRequest>({ groupIds: { wire: 'group_ids', codec: array(text) } });
+export function validateGroupSubscriptionRequest(value: GroupSubscriptionRequest): void { validateCompleteObject(groupSubscriptionRequestCodec.encode(value)); if (new Set(value.groupIds).size !== value.groupIds.length) throw new ProtocolError('duplicate_group', 'Group subscription repeats a group.'); for (const id of value.groupIds) validateIdentifier('group', id); }
+export interface GroupChangedNotification extends ExtensibleModel { readonly groupId: string }
+export const groupChangedNotificationCodec = defineCodec<GroupChangedNotification>({ groupId });
+export function validateGroupChangedNotification(value: GroupChangedNotification): void { validateCompleteObject(groupChangedNotificationCodec.encode(value)); validateIdentifier('group', value.groupId); }
+export interface GroupTimelineChangedNotification extends GroupChangedNotification { readonly head: number }
+export const groupTimelineChangedNotificationCodec = defineCodec<GroupTimelineChangedNotification>({ groupId, head: { wire: 'head', codec: integer } });
+export function validateGroupTimelineChangedNotification(value: GroupTimelineChangedNotification): void { validateCompleteObject(groupTimelineChangedNotificationCodec.encode(value)); validateIdentifier('group', value.groupId); requireSafeInteger(value.head, 0); }

package/src/models/group-keys.ts

@@ -0,0 +1,34 @@
+import { ProtocolError } from '../errors.js';
+import { validateIdentifier } from '../identity/identifiers.js';
+import { validateAccountId } from '../identity/neo.js';
+import { array, boolean, defineCodec, dictionary, integer, text, type ExtensibleModel } from '../protocol/codec.js';
+import { requireSafeInteger } from '../protocol/json.js';
+import { validateCompleteObject } from '../protocol/validation.js';
+import { contentHashBytes } from './content.js';
+import { groupSecretBoxCodec, validateGroupSecretBox, type GroupSecretBox } from './groups.js';
+
+export interface GroupKeyEntry extends ExtensibleModel { readonly epoch: number; readonly clientSecretBox?: GroupSecretBox; readonly relaySecretBox: GroupSecretBox }
+export const groupKeyEntryCodec = defineCodec<GroupKeyEntry>({ epoch: { wire: 'epoch', codec: integer }, clientSecretBox: { wire: 'client_secret_box', codec: groupSecretBoxCodec, optional: true }, relaySecretBox: { wire: 'relay_secret_box', codec: groupSecretBoxCodec } });
+export function validateGroupKeyEntry(value: GroupKeyEntry): void { validateCompleteObject(groupKeyEntryCodec.encode(value)); requireSafeInteger(value.epoch, 0); if (value.clientSecretBox) validateGroupSecretBox(value.clientSecretBox); validateGroupSecretBox(value.relaySecretBox); }
+export interface GroupKeyPage extends ExtensibleModel { readonly keys: readonly GroupKeyEntry[]; readonly hasMore: boolean }
+export const groupKeyPageCodec = defineCodec<GroupKeyPage>({ keys: { wire: 'keys', codec: array(groupKeyEntryCodec) }, hasMore: { wire: 'has_more', codec: boolean } });
+export function validateGroupKeyPage(value: GroupKeyPage, after = -1): void {
+    validateCompleteObject(groupKeyPageCodec.encode(value)); requireSafeInteger(after, -1);
+    if (value.hasMore && !value.keys.length) throw new ProtocolError('invalid_pagination', 'An empty group key page cannot have more entries.');
+    if (value.keys.length && !value.keys[0]!.clientSecretBox) throw new ProtocolError('missing_secret_box', 'The first group key entry in each page requires a client secret box.');
+    for (const entry of value.keys) { validateGroupKeyEntry(entry); if (entry.epoch <= after) throw new ProtocolError('invalid_epoch', 'Group key epochs must increase after the requested cursor.'); after = entry.epoch; }
+}
+export interface GroupRotationPrepareRequest extends ExtensibleModel { readonly groupId: string; readonly baseCommitment: string; readonly clientSecretCommitment: string; readonly clientSecretBoxes: Readonly<Record<string, GroupSecretBox>> }
+export const groupRotationPrepareRequestCodec = defineCodec<GroupRotationPrepareRequest>({ groupId: { wire: 'group_id', codec: text }, baseCommitment: { wire: 'base_commitment', codec: text }, clientSecretCommitment: { wire: 'client_secret_commitment', codec: text }, clientSecretBoxes: { wire: 'client_secret_boxes', codec: dictionary(groupSecretBoxCodec) } });
+export function validateGroupRotationPrepareRequest(value: GroupRotationPrepareRequest): void {
+    validateCompleteObject(groupRotationPrepareRequestCodec.encode(value)); validateIdentifier('group', value.groupId); contentHashBytes(value.baseCommitment); contentHashBytes(value.clientSecretCommitment);
+    if (value.baseCommitment === value.clientSecretCommitment) throw new ProtocolError('unchanged_secret', 'Prepared client secret commitment must change.');
+    const boxes = Object.entries(value.clientSecretBoxes); if (!boxes.length) throw new ProtocolError('invalid_size', 'Rotation preparation requires at least one client secret box.');
+    for (const [account, box] of boxes) { validateAccountId(account); validateGroupSecretBox(box); }
+}
+export interface GroupRotationPrepareResult extends ExtensibleModel { readonly prepared: number; readonly expiresAt: number }
+export const groupRotationPrepareResultCodec = defineCodec<GroupRotationPrepareResult>({ prepared: { wire: 'prepared', codec: integer }, expiresAt: { wire: 'expires_at', codec: integer } });
+export function validateGroupRotationPrepareResult(value: GroupRotationPrepareResult, now: number): void {
+    validateCompleteObject(groupRotationPrepareResultCodec.encode(value)); requireSafeInteger(value.prepared, 0); requireSafeInteger(value.expiresAt, 0); requireSafeInteger(now, 0);
+    if (value.expiresAt <= now) throw new ProtocolError('expired_preparation', 'Group rotation preparation has expired.');
+}