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

package/src/models/messages.ts

@@ -0,0 +1,139 @@
+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, enumeration, integer, text, type ExtensibleModel, type ValueCodec } from '../protocol/codec.js';
+import { signingInput, type NetworkContext } from '../protocol/context.js';
+import { encodeUtf8 } from '../protocol/encoding.js';
+import { canonicalJson, parseJson, requireObject, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import { validateCompleteObject } from '../protocol/validation.js';
+import { relayFailureCodec, type RelayFailure } from '../transport/relay-error.js';
+import { contentReferenceCodec, messageBodyCodec, validateAttachments, validateMessageBody, type ContentReference, type MessageBody } from './content.js';
+import { contactAuthorizationCodec, validateContactGrant, validateContactInvite, type ContactAuthorization } from './contacts.js';
+import { certificateId, deviceCertificateCodec, validateCertificate, type DeviceCertificate } from './identity.js';
+
+/** Complete wire business object. Unknown types may be stored but cannot authorize protocol state changes. */
+export const messagePayloadCodec: ValueCodec<JsonObject> = {
+    decode(value) {
+        const object = requireObject(value); validateCompleteObject(object);
+        if (typeof object['$type'] !== 'string') throw new ProtocolError('invalid_type', 'A message payload requires a string $type.');
+        return requireObject(parseJson(canonicalJson(object)));
+    },
+    encode(value) { return this.decode(value); },
+};
+
+export interface EncryptedPayload extends ExtensibleModel { readonly alg: string; readonly nonce: Uint8Array; readonly ciphertext: Uint8Array }
+export const encryptedPayloadCodec = defineCodec<EncryptedPayload>({ alg: { wire: 'alg', codec: text }, nonce: { wire: 'nonce', codec: bytes }, ciphertext: { wire: 'ciphertext', codec: bytes } });
+export function validateEncryptedPayload(value: EncryptedPayload): void {
+    validateCompleteObject(encryptedPayloadCodec.encode(value));
+    if (value.alg !== 'AES-256-GCM') throw new ProtocolError('unsupported_algorithm', 'Message payload encryption must use AES-256-GCM.');
+    requireLength(value.nonce, 12, 'Payload nonce');
+    if (value.ciphertext.length <= 16) throw new ProtocolError('invalid_ciphertext', 'Encrypted payload requires nonempty ciphertext and a GCM tag.');
+}
+export interface MessageEnvelope extends ExtensibleModel {
+    readonly messageId: string; readonly createdAt: number; readonly from: string; readonly fromDeviceId: string; readonly to: string;
+    readonly payload: EncryptedPayload; readonly deviceSignature: Uint8Array;
+}
+export const messageEnvelopeCodec = defineCodec<MessageEnvelope>({ messageId: { wire: 'message_id', codec: text }, createdAt: { wire: 'created_at', codec: integer },
+    from: { wire: 'from', codec: text }, fromDeviceId: { wire: 'from_device_id', codec: text }, to: { wire: 'to', codec: text },
+    payload: { wire: 'payload', codec: encryptedPayloadCodec }, deviceSignature: { wire: 'device_signature', codec: bytes } }, 'meshline.message.envelope');
+export const messageEnvelopeInput = (value: MessageEnvelope, context: NetworkContext): Uint8Array => signingInput(messageEnvelopeCodec.encode(value), context, ['device_signature']);
+export function validateMessageEnvelope(value: MessageEnvelope): void {
+    validateCompleteObject(messageEnvelopeCodec.encode(value));
+    validateIdentifier('message', value.messageId); validateIdentifier('device', value.fromDeviceId); requireSafeInteger(value.createdAt, 0);
+    validateAccountId(value.from); validateAccountId(value.to); requireLength(value.deviceSignature, 64, 'Envelope signature'); validateEncryptedPayload(value.payload);
+    if (encodeUtf8(messageEnvelopeCodec.stringify(value)).length > 262144) throw new ProtocolError('invalid_size', 'Message envelope exceeds 262144 canonical UTF-8 bytes.');
+}
+/** Historical signature integrity only. Current device authority is checked separately by the receiver's business workflow. */
+export function verifyMessageEnvelope(value: MessageEnvelope, sender: DeviceCertificate, context: NetworkContext): void {
+    validateMessageEnvelope(value); validateCertificate(sender, context);
+    if (sender.account !== value.from || certificateId(sender, context) !== value.fromDeviceId) throw new ProtocolError('invalid_identity', 'Envelope signing certificate belongs to another account or device.');
+    if (!verifyDevice(messageEnvelopeInput(value, context), value.deviceSignature, sender.signingPublicKey)) throw new ProtocolError('invalid_signature', 'Invalid message envelope signature.');
+}
+export interface MessageKeyBox extends ExtensibleModel { readonly deviceId: string; readonly alg: string; readonly enc: Uint8Array; readonly sealedKey: Uint8Array }
+export const messageKeyBoxCodec = defineCodec<MessageKeyBox>({ deviceId: { wire: 'device_id', codec: text }, alg: { wire: 'alg', codec: text }, enc: { wire: 'enc', codec: bytes }, sealedKey: { wire: 'sealed_key', codec: bytes } });
+export function validateMessageKeyBox(value: MessageKeyBox): void {
+    validateCompleteObject(messageKeyBoxCodec.encode(value)); validateIdentifier('device', value.deviceId);
+    if (value.alg !== 'X25519-HKDF-SHA256-AES256GCM') throw new ProtocolError('unsupported_algorithm', 'Unsupported message key box algorithm.');
+    requireLength(value.enc, 32, 'Ephemeral public key'); requireLength(value.sealedKey, 60, 'Sealed content key');
+}
+export function validateMessageKeyBoxes(values: readonly MessageKeyBox[]): void {
+    if (values.length < 1 || values.length > 8) throw new ProtocolError('invalid_size', 'Key box sets require between one and eight devices.');
+    const ids = new Set<string>();
+    for (const value of values) { validateMessageKeyBox(value); if (ids.has(value.deviceId)) throw new ProtocolError('duplicate_device', 'Key box set contains a duplicate device.'); ids.add(value.deviceId); }
+}
+export interface MessageSendRequest extends ExtensibleModel {
+    readonly envelope: MessageEnvelope; readonly senderBoxes?: readonly MessageKeyBox[]; readonly recipientBoxes: readonly MessageKeyBox[]; readonly authorization?: ContactAuthorization;
+}
+export const messageSendRequestCodec = defineCodec<MessageSendRequest>({ envelope: { wire: 'envelope', codec: messageEnvelopeCodec }, senderBoxes: { wire: 'sender_boxes', codec: array(messageKeyBoxCodec), optional: true },
+    recipientBoxes: { wire: 'recipient_boxes', codec: array(messageKeyBoxCodec) }, authorization: { wire: 'authorization', codec: contactAuthorizationCodec, optional: true } });
+export function validateMessageSendRequest(value: MessageSendRequest, now: number): void {
+    validateCompleteObject(messageSendRequestCodec.encode(value)); requireSafeInteger(now, 0);
+    validateMessageEnvelope(value.envelope); validateMessageKeyBoxes(value.recipientBoxes);
+    if (value.senderBoxes) validateMessageKeyBoxes(value.senderBoxes);
+    if (value.envelope.from === value.envelope.to && (value.senderBoxes !== undefined || value.authorization !== undefined))
+        throw new ProtocolError('invalid_self_delivery', 'Self messages must omit sender boxes and contact authorization.');
+    if (value.authorization) {
+        if ('grantor' in value.authorization) {
+            validateContactGrant(value.authorization, now);
+            if (value.authorization.grantor !== value.envelope.to || value.authorization.grantee !== value.envelope.from) throw new ProtocolError('invalid_authorization', 'Message grant has inconsistent account bindings.');
+        } else {
+            validateContactInvite(value.authorization, now);
+            if (value.authorization.inviter !== value.envelope.to) throw new ProtocolError('invalid_authorization', 'Message invitation belongs to another recipient.');
+        }
+    }
+}
+export interface DirectMessageReference extends ExtensibleModel { readonly from: string; readonly messageId: string }
+export const directMessageReferenceCodec = defineCodec<DirectMessageReference>({ from: { wire: 'from', codec: text }, messageId: { wire: 'message_id', codec: text } });
+export interface DirectMessage extends ExtensibleModel { readonly body?: MessageBody; readonly attachments?: readonly ContentReference[]; readonly replyTo?: DirectMessageReference }
+export const directMessageCodec = defineCodec<DirectMessage>({ body: { wire: 'body', codec: messageBodyCodec, optional: true }, attachments: { wire: 'attachments', codec: array(contentReferenceCodec), optional: true },
+    replyTo: { wire: 'reply_to', codec: directMessageReferenceCodec, optional: true } }, 'meshline.message.direct');
+export function validateDirectMessage(value: DirectMessage): void {
+    validateCompleteObject(directMessageCodec.encode(value));
+    if (value.body) validateMessageBody(value.body);
+    if (value.attachments) validateAttachments(value.attachments);
+    if (!value.body && !value.attachments?.length) throw new ProtocolError('invalid_message', 'A direct message requires a body or at least one attachment.');
+    if (value.replyTo) { validateAccountId(value.replyTo.from); validateIdentifier('message', value.replyTo.messageId); }
+}
+export interface MessageTimelineEntry extends ExtensibleModel { readonly sequence: number; readonly envelope: MessageEnvelope; readonly keyBox: MessageKeyBox; readonly acceptedAt: number }
+export const messageTimelineEntryCodec = defineCodec<MessageTimelineEntry>({ sequence: { wire: 'sequence', codec: integer }, envelope: { wire: 'envelope', codec: messageEnvelopeCodec }, keyBox: { wire: 'key_box', codec: messageKeyBoxCodec }, acceptedAt: { wire: 'accepted_at', codec: integer } });
+export interface MessageTimelinePage extends ExtensibleModel { readonly items: readonly MessageTimelineEntry[]; readonly certificates: readonly DeviceCertificate[]; readonly hasMore: boolean; readonly hasRetentionGap?: boolean }
+export const messageTimelinePageCodec = defineCodec<MessageTimelinePage>({ items: { wire: 'items', codec: array(messageTimelineEntryCodec) }, certificates: { wire: 'certificates', codec: array(deviceCertificateCodec) },
+    hasMore: { wire: 'has_more', codec: boolean }, hasRetentionGap: { wire: 'has_retention_gap', codec: boolean, optional: true } });
+/** Checks page ordering and certificate availability. Each entry still requires decryption and business validation before cursor commit. */
+export function validateMessageTimelinePage(value: MessageTimelinePage, context: NetworkContext, after = -1): void {
+    requireSafeInteger(after, -1); validateCompleteObject(messageTimelinePageCodec.encode(value));
+    if (value.hasMore && !value.items.length) throw new ProtocolError('invalid_pagination', 'An empty timeline page cannot have more items.');
+    const ids = new Map<string, string>();
+    for (const certificate of value.certificates) { validateCertificate(certificate, context); const id = certificateId(certificate, context);
+        if (ids.has(id)) throw new ProtocolError('duplicate_device', 'Timeline page has duplicate signing certificates.'); ids.set(id, certificate.account); }
+    for (const item of value.items) {
+        requireSafeInteger(item.sequence, 0); requireSafeInteger(item.acceptedAt, 0);
+        if (item.sequence <= after) throw new ProtocolError('invalid_sequence', 'Timeline sequences must increase strictly after the requested cursor.');
+        if (!ids.has(item.envelope.fromDeviceId)) throw new ProtocolError('missing_certificate', 'Timeline message has no signing certificate.');
+        if (ids.get(item.envelope.fromDeviceId) !== item.envelope.from) throw new ProtocolError('invalid_identity', 'Timeline signing certificate belongs to another account.');
+        after = item.sequence;
+    }
+}
+export interface MessageTimelineQuery extends ExtensibleModel { readonly after?: number; readonly limit?: number }
+export const messageTimelineQueryCodec = defineCodec<MessageTimelineQuery>({ after: { wire: 'after', codec: integer, optional: true }, limit: { wire: 'limit', codec: integer, optional: true } });
+export function validateMessageTimelineQuery(value: MessageTimelineQuery): void {
+    validateCompleteObject(messageTimelineQueryCodec.encode(value));
+    if (value.after !== undefined) requireSafeInteger(value.after, -1);
+    if (value.limit !== undefined) requireSafeInteger(value.limit, 1);
+}
+export interface MessageDeliveryQuery extends ExtensibleModel { readonly messageId: string }
+export const messageDeliveryQueryCodec = defineCodec<MessageDeliveryQuery>({ messageId: { wire: 'message_id', codec: text } });
+export type MessageDeliveryState = 'delivering' | 'target_accepted' | 'failed';
+export interface MessageDeliveryStatus extends ExtensibleModel { readonly status: MessageDeliveryState; readonly error?: RelayFailure; readonly acceptedAt: number }
+export const messageDeliveryStatusCodec = defineCodec<MessageDeliveryStatus>({ status: { wire: 'status', codec: enumeration('delivering', 'target_accepted', 'failed') }, error: { wire: 'error', codec: relayFailureCodec, optional: true }, acceptedAt: { wire: 'accepted_at', codec: integer } });
+export function validateMessageDeliveryStatus(value: MessageDeliveryStatus): void {
+    validateCompleteObject(messageDeliveryStatusCodec.encode(value)); requireSafeInteger(value.acceptedAt, 0);
+    if ((value.status === 'failed') !== (value.error !== undefined)) throw new ProtocolError('invalid_delivery', 'Only failed delivery results must contain an error.');
+}
+export interface DeviceStateChanged extends ExtensibleModel { readonly revision: number }
+export const deviceStateChangedCodec = defineCodec<DeviceStateChanged>({ revision: { wire: 'revision', codec: integer } }, 'meshline.device.state.changed');
+export function validateDeviceStateChanged(value: DeviceStateChanged): void { validateCompleteObject(deviceStateChangedCodec.encode(value)); requireSafeInteger(value.revision, 0); }
+export interface MessageTimelineChangedNotification extends ExtensibleModel { readonly head: number }
+export const messageTimelineChangedCodec = defineCodec<MessageTimelineChangedNotification>({ head: { wire: 'head', codec: integer } });
+export function validateMessageTimelineChanged(value: MessageTimelineChangedNotification): void { validateCompleteObject(messageTimelineChangedCodec.encode(value)); requireSafeInteger(value.head, 0); }

package/src/models/profile.ts

@@ -0,0 +1,46 @@
+import { requireLength, verifyDevice } from '../crypto/primitives.js';
+import { ProtocolError } from '../errors.js';
+import { validateAccountId } from '../identity/neo.js';
+import { boolean, bytes, defineCodec, integer, text, type ExtensibleModel } from '../protocol/codec.js';
+import { signingInput, type NetworkContext } from '../protocol/context.js';
+import { encodeUtf8 } from '../protocol/encoding.js';
+import { requireSafeInteger } from '../protocol/json.js';
+import { validateCompleteObject } from '../protocol/validation.js';
+import { containsNonWhitespace, contentReferenceCodec, validateContentReference, type ContentReference } from './content.js';
+import { deviceCertificateCodec, validateCertificate, type DeviceCertificate } from './identity.js';
+
+export interface AccountProfile extends ExtensibleModel {
+    readonly account: string; readonly nickname?: string; readonly avatar?: ContentReference; readonly bio?: string;
+    readonly publicDiscovery: boolean; readonly updatedAt: number; readonly deviceSignature: Uint8Array;
+}
+export const accountProfileCodec = defineCodec<AccountProfile>({
+    account: { wire: 'account', codec: text }, nickname: { wire: 'nickname', codec: text, optional: true },
+    avatar: { wire: 'avatar', codec: contentReferenceCodec, optional: true }, bio: { wire: 'bio', codec: text, optional: true },
+    publicDiscovery: { wire: 'public_discovery', codec: boolean }, updatedAt: { wire: 'updated_at', codec: integer }, deviceSignature: { wire: 'device_signature', codec: bytes },
+}, 'meshline.profile');
+export const profileInput = (value: AccountProfile, context: NetworkContext): Uint8Array => signingInput(accountProfileCodec.encode(value), context, ['device_signature']);
+export function validateProfile(value: AccountProfile): void {
+    validateCompleteObject(accountProfileCodec.encode(value));
+    validateAccountId(value.account); requireSafeInteger(value.updatedAt, 0); requireLength(value.deviceSignature, 64, 'Profile signature');
+    for (const [field, limit] of [[value.nickname, 256], [value.bio, 2048]] as const) {
+        if (field !== undefined && field !== '' && (!containsNonWhitespace(field) || encodeUtf8(field).length > limit))
+            throw new ProtocolError('invalid_profile_text', `Nonempty profile text must contain non-whitespace characters and fit ${limit} UTF-8 bytes.`);
+    }
+    if (value.avatar) {
+        validateContentReference(value.avatar);
+        if (!value.avatar.contentType.toLowerCase().startsWith('image/')) throw new ProtocolError('invalid_avatar', 'An avatar requires an image media type.');
+    }
+    if (encodeUtf8(accountProfileCodec.stringify(value)).length > 8192) throw new ProtocolError('invalid_size', 'Profile exceeds 8192 canonical JSON bytes.');
+}
+export interface ProfileResolveResult extends ExtensibleModel { readonly profile: AccountProfile; readonly signerCertificate: DeviceCertificate }
+export const profileResolveResultCodec = defineCodec<ProfileResolveResult>({
+    profile: { wire: 'profile', codec: accountProfileCodec }, signerCertificate: { wire: 'signer_certificate', codec: deviceCertificateCodec },
+});
+/** The certificate is evidence at publication acceptance, not a claim of current device authorization. */
+export function validateProfileResult(value: ProfileResolveResult, context: NetworkContext, account = value.profile.account): void {
+    validateCompleteObject(profileResolveResultCodec.encode(value));
+    validateProfile(value.profile); validateCertificate(value.signerCertificate, context);
+    if (value.profile.account !== account || value.signerCertificate.account !== account) throw new ProtocolError('invalid_identity', 'Profile or signer certificate belongs to another account.');
+    if (!verifyDevice(profileInput(value.profile, context), value.profile.deviceSignature, value.signerCertificate.signingPublicKey))
+        throw new ProtocolError('invalid_signature', 'Invalid profile device signature.');
+}

package/src/models/relay.ts

@@ -0,0 +1,151 @@
+import { multiaddr } from '@multiformats/multiaddr';
+import { bases } from 'multiformats/basics';
+import { base58btc } from 'multiformats/bases/base58';
+import { create as createDigest, decode as decodeDigest } from 'multiformats/hashes/digest';
+import { requireLength } from '../crypto/primitives.js';
+import { ProtocolError } from '../errors.js';
+import { validateRelayId, verifyRelay } from '../identity/neo.js';
+import { array, bytes, defineCodec, integer, text, type ExtensibleModel } from '../protocol/codec.js';
+import { NetworkContext, signingInput } from '../protocol/context.js';
+import { encodeUtf8, equalBytes } from '../protocol/encoding.js';
+import { requireSafeInteger } from '../protocol/json.js';
+import { webEndpoint } from '../transport/endpoint.js';
+
+export interface RelayDescriptor extends ExtensibleModel {
+    readonly relayId: string;
+    readonly publicKey: Uint8Array;
+    readonly endpoints: readonly string[];
+    readonly capabilities?: readonly string[];
+    readonly expiresAt: number;
+    readonly relaySignature: Uint8Array;
+}
+export const relayDescriptorCodec = defineCodec<RelayDescriptor>({
+    relayId: { wire: 'relay_id', codec: text }, publicKey: { wire: 'public_key', codec: bytes },
+    endpoints: { wire: 'endpoints', codec: array(text) }, capabilities: { wire: 'capabilities', codec: array(text), optional: true },
+    expiresAt: { wire: 'expires_at', codec: integer }, relaySignature: { wire: 'relay_signature', codec: bytes },
+}, 'meshline.relay.descriptor');
+
+export function relayDescriptorInput(descriptor: RelayDescriptor, context: NetworkContext): Uint8Array {
+    return signingInput(relayDescriptorCodec.encode(descriptor), context, ['relay_signature']);
+}
+
+/** Normalized multihash identity, independent of a peer ID's allowed base/CID spelling. */
+function peerIdentity(value: string): string {
+    let hashBytes: Uint8Array;
+    if (value.startsWith('Qm') || value.startsWith('1')) hashBytes = base58btc.decode('z' + value);
+    else {
+        const base = Object.values(bases).find(base => value.startsWith(base.prefix));
+        if (!base) throw new ProtocolError('invalid_peer', 'Unknown peer ID multibase.');
+        const cid = base.decode(value);
+        if (cid[0] !== 1 || cid[1] !== 0x72) throw new ProtocolError('invalid_peer', 'Peer IDs require CIDv1 libp2p-key.');
+        hashBytes = cid.subarray(2);
+    }
+    const digest = decodeDigest(hashBytes);
+    if (!(digest.code === 0x12 && digest.size === 32 || digest.code === 0 && digest.size > 0 && digest.size <= 42)
+        || !equalBytes(hashBytes, createDigest(digest.code, digest.digest).bytes))
+        throw new ProtocolError('invalid_peer', 'Invalid or noncanonical peer multihash.');
+    return base58btc.encode(hashBytes).slice(1);
+}
+
+export type RelayEndpoint = { readonly kind: 'https' | 'wss' | 'unknown' } | { readonly kind: 'libp2p-tcp'; readonly peerId: string };
+export function validateRelayEndpoint(endpoint: string): RelayEndpoint {
+    if (typeof endpoint !== 'string' || endpoint.length === 0) throw new ProtocolError('invalid_endpoint', 'Relay endpoints must be nonempty strings.');
+    const candidate = endpoint.trimStart();
+    if (/^(https|wss):/i.test(candidate)) { const url = webEndpoint(endpoint); return { kind: url.protocol === 'https:' ? 'https' : 'wss' }; }
+    if (!candidate.startsWith('/') || !candidate.includes('/tcp/') && !candidate.endsWith('/tcp')) return { kind: 'unknown' };
+    if (!endpoint.startsWith('/') || endpoint.endsWith('/') || endpoint.includes('//') || /[\s\p{Cc}]/u.test(endpoint))
+        throw new ProtocolError('invalid_endpoint', 'Malformed libp2p TCP endpoint.');
+    try {
+        const parts = endpoint.split('/');
+        if (parts.at(-2) !== 'p2p') throw new Error('Endpoint must end with a peer ID.');
+        const peerId = peerIdentity(parts.at(-1)!);
+        for (let i = 0; i < parts.length; i++) if (parts[i] === 'tcp' && !/^[0-9]+$/.test(parts[i + 1] ?? '')) throw new Error('Invalid TCP port.');
+        const address = multiaddr(endpoint.slice(0, endpoint.lastIndexOf('/p2p/')) + '/p2p/' + peerId);
+        // Parsing textual components alone is lazy; encoding validates IP and port values.
+        void address.bytes;
+        const components = address.getComponents();
+        if (components.length < 3 || components[1]!.name !== 'tcp' || Number(components[1]!.value) <= 0
+            || components.filter(item => item.name === 'tcp').length !== 1 || components.filter(item => item.name === 'p2p').length !== 1
+            || components.at(-1)!.name !== 'p2p') throw new Error('Expected host/TCP/.../peer endpoint.');
+        const host = components[0]!;
+        if (!['ip4', 'ip6', 'dns', 'dns4', 'dns6'].includes(host.name)) throw new Error('Invalid multiaddr host type.');
+        if (host.name.startsWith('dns')) {
+            const hostname = parseAbsoluteUrl(`https://${host.value}`).hostname;
+            if (hostname.startsWith('[') || /^[0-9.]+$/.test(hostname) || hostname.length > 255
+                || !hostname.replace(/\.$/, '').split('.').every(label => /^[a-z0-9_][a-z0-9_-]{0,62}$/i.test(label))) throw new Error('Invalid DNS host.');
+        }
+        return { kind: 'libp2p-tcp', peerId };
+    } catch (cause) { throw new ProtocolError('invalid_endpoint', 'Invalid libp2p TCP relay endpoint.', { cause }); }
+}
+
+export function validateRelayDescriptor(descriptor: RelayDescriptor, context: NetworkContext, now: number): void {
+    validateCompleteObject(relayDescriptorCodec.encode(descriptor));
+    requireSafeInteger(now, 0); requireSafeInteger(descriptor.expiresAt, 0);
+    validateRelayId(descriptor.relayId);
+    requireLength(descriptor.publicKey, 33, 'Relay public key'); requireLength(descriptor.relaySignature, 64, 'Relay signature');
+    if (descriptor.expiresAt <= now) throw new ProtocolError('expired_descriptor', 'The relay descriptor has expired.');
+    if (!Array.isArray(descriptor.endpoints) || descriptor.endpoints.length === 0) throw new ProtocolError('invalid_endpoint', 'Relay endpoints must be a nonempty array.');
+    const endpoints = new Set<string>();
+    let hasHttps = false;
+    let peer: string | undefined;
+    for (const endpoint of descriptor.endpoints) {
+        if (endpoints.has(endpoint)) throw new ProtocolError('duplicate_endpoint', 'Relay endpoints cannot contain duplicates.');
+        endpoints.add(endpoint);
+        const validated = validateRelayEndpoint(endpoint);
+        if (validated.kind === 'https') hasHttps = true;
+        if (validated.kind === 'libp2p-tcp') {
+            if (peer !== undefined && peer !== validated.peerId) throw new ProtocolError('invalid_peer', 'All libp2p TCP endpoints must identify the same peer.');
+            peer = validated.peerId;
+        }
+    }
+    if (!hasHttps || peer === undefined) throw new ProtocolError('missing_endpoint', 'A relay must advertise HTTPS and libp2p TCP endpoints.');
+    const capabilities = descriptor.capabilities ?? [];
+    if (!Array.isArray(capabilities) || capabilities.length > 64 || new Set(capabilities).size !== capabilities.length)
+        throw new ProtocolError('invalid_capabilities', 'Capabilities must be distinct and contain at most 64 entries.');
+    for (const value of capabilities) if (value.length === 0 || encodeUtf8(value).length > 128) throw new ProtocolError('invalid_capabilities', 'Capabilities must contain 1 to 128 UTF-8 bytes.');
+    if (!verifyRelay(descriptor.relayId, descriptor.publicKey, relayDescriptorInput(descriptor, context), descriptor.relaySignature))
+        throw new ProtocolError('invalid_signature', 'The descriptor signature does not identify this relay.');
+}
+
+export interface RelayLimits extends ExtensibleModel {
+    readonly messageRetention: number;
+    readonly channelTimelineRetention?: number;
+    readonly maxChannelSubscriptions?: number;
+    readonly groupMessageRetention?: number;
+    readonly maxGroupMembers?: number;
+    readonly maxGroupSubscriptions?: number;
+    readonly maxGroupInviteTtl?: number;
+}
+export const relayLimitsCodec = defineCodec<RelayLimits>({
+    messageRetention: { wire: 'message_retention', codec: integer },
+    channelTimelineRetention: { wire: 'channel_timeline_retention', codec: integer, optional: true },
+    maxChannelSubscriptions: { wire: 'max_channel_subscriptions', codec: integer, optional: true },
+    groupMessageRetention: { wire: 'group_message_retention', codec: integer, optional: true },
+    maxGroupMembers: { wire: 'max_group_members', codec: integer, optional: true },
+    maxGroupSubscriptions: { wire: 'max_group_subscriptions', codec: integer, optional: true },
+    maxGroupInviteTtl: { wire: 'max_group_invite_ttl', codec: integer, optional: true },
+});
+export interface RelayInfo extends ExtensibleModel { readonly relayId: string; readonly name: string; readonly serverTime: number; readonly limits: RelayLimits }
+export const relayInfoCodec = defineCodec<RelayInfo>({
+    relayId: { wire: 'relay_id', codec: text }, name: { wire: 'name', codec: text }, serverTime: { wire: 'server_time', codec: integer }, limits: { wire: 'limits', codec: relayLimitsCodec },
+});
+export function validateRelayInfo(info: RelayInfo, descriptor?: RelayDescriptor): void {
+    validateCompleteObject(relayInfoCodec.encode(info));
+    validateRelayId(info.relayId); requireSafeInteger(info.serverTime, 0);
+    if (info.name.trim().length === 0 || encodeUtf8(info.name).length > 256) throw new ProtocolError('invalid_name', 'Relay name must be nonblank and at most 256 UTF-8 bytes.');
+    requireSafeInteger(info.limits.messageRetention, 1);
+    for (const value of [info.limits.channelTimelineRetention, info.limits.groupMessageRetention, info.limits.maxGroupMembers, info.limits.maxGroupInviteTtl])
+        if (value !== undefined) requireSafeInteger(value, 1);
+    for (const value of [info.limits.maxChannelSubscriptions, info.limits.maxGroupSubscriptions]) if (value !== undefined) requireSafeInteger(value, 0);
+    if (descriptor) {
+        if (info.relayId !== descriptor.relayId) throw new ProtocolError('invalid_identity', 'Relay info belongs to a different relay.');
+        const sockets = descriptor.endpoints.some(endpoint => endpoint.startsWith('wss://'));
+        const limits = info.limits;
+        if (descriptor.capabilities?.includes('channel.host.v1') && (limits.channelTimelineRetention === undefined || sockets && limits.maxChannelSubscriptions === undefined)
+            || descriptor.capabilities?.includes('group.host.v1') && (limits.groupMessageRetention === undefined || limits.maxGroupMembers === undefined
+                || limits.maxGroupInviteTtl === undefined || sockets && limits.maxGroupSubscriptions === undefined))
+            throw new ProtocolError('missing_limits', 'Relay info omits limits required by its advertised capabilities.');
+    }
+}
+import { validateCompleteObject } from '../protocol/validation.js';
+import { parseAbsoluteUrl } from '../runtime/url.js';

package/src/protocol/codec.ts

@@ -0,0 +1,144 @@
+import { ProtocolError } from '../errors.js';
+import { decodeBase64Url, encodeBase64Url } from './encoding.js';
+import { canonicalJson, parseJson, requireObject, requireSafeInteger, type JsonObject, type JsonValue } from './json.js';
+
+/** Unknown wire fields remain distinct from the application's camelCase members. */
+export interface ExtensibleModel { readonly additionalProperties?: JsonObject }
+
+/** A model codec enforces wire representation; domain validators enforce authorization. */
+export interface ProtocolCodec<T> {
+    decode(value: JsonValue): T;
+    encode(value: T): JsonObject;
+    parse(input: string | Uint8Array): T;
+    stringify(value: T): string;
+}
+
+export interface ValueCodec<T> {
+    decode(value: JsonValue): T;
+    encode(value: T): JsonValue;
+}
+
+export const text: ValueCodec<string> = {
+    decode(value) {
+        if (typeof value !== 'string') throw new ProtocolError('invalid_field', 'Expected a string.');
+        return value;
+    },
+    encode(value) { return this.decode(value); },
+};
+
+export const integer: ValueCodec<number> = {
+    decode(value) { requireSafeInteger(value); return value; },
+    encode(value) { return this.decode(value); },
+};
+
+export const boolean: ValueCodec<boolean> = {
+    decode(value) {
+        if (typeof value !== 'boolean') throw new ProtocolError('invalid_field', 'Expected a boolean.');
+        return value;
+    },
+    encode(value) { return this.decode(value); },
+};
+
+export const bytes: ValueCodec<Uint8Array> = {
+    decode(value) { return decodeBase64Url(text.decode(value)); },
+    encode(value) {
+        if (!(value instanceof Uint8Array)) throw new ProtocolError('invalid_field', 'Expected a Uint8Array.');
+        return encodeBase64Url(value);
+    },
+};
+
+export function array<T>(item: ValueCodec<T>): ValueCodec<readonly T[]> {
+    return {
+        decode(value) {
+            if (!Array.isArray(value)) throw new ProtocolError('invalid_field', 'Expected an array.');
+            return value.map(element => item.decode(element));
+        },
+        encode(value) {
+            if (!Array.isArray(value)) throw new ProtocolError('invalid_field', 'Expected an array.');
+            return value.map(element => item.encode(element));
+        },
+    };
+}
+
+export function dictionary<T>(item: ValueCodec<T>): ValueCodec<Readonly<Record<string, T>>> {
+    return {
+        decode(value) {
+            const result: Record<string, T> = Object.create(null) as Record<string, T>;
+            for (const [key, field] of Object.entries(requireObject(value))) result[key] = item.decode(field);
+            return result;
+        },
+        encode(value) {
+            if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new ProtocolError('invalid_field', 'Expected a dictionary.');
+            const result: JsonObject = Object.create(null) as JsonObject;
+            for (const [key, field] of Object.entries(value)) result[key] = item.encode(field);
+            return result;
+        },
+    };
+}
+
+export function enumeration<const T extends string>(...values: T[]): ValueCodec<T> {
+    return {
+        decode(value) {
+            if (typeof value !== 'string' || !values.includes(value as T)) throw new ProtocolError('invalid_field', 'Unknown enum value.');
+            return value as T;
+        },
+        encode(value) { return this.decode(value); },
+    };
+}
+
+export interface Field<T> { readonly wire: string; readonly codec: ValueCodec<T>; readonly optional?: boolean; readonly nullable?: boolean }
+type Fields<T> = { [K in Exclude<keyof T, 'additionalProperties'>]-?: Field<Exclude<T[K], null | undefined>> };
+
+/** Creates an explicit mapping without guessing wire names or discarding signed extensions. */
+export function defineCodec<T extends ExtensibleModel>(fields: Fields<T>, type?: string): ProtocolCodec<T> {
+    const entries = Object.entries(fields) as Array<[string, Field<unknown>]>;
+    const wireNames = new Set(entries.map(([, field]) => field.wire));
+    if (type !== undefined) wireNames.add('$type');
+    if (wireNames.size !== entries.length + (type === undefined ? 0 : 1)) throw new Error('Duplicate codec field definition.');
+    const modelNames = new Set(entries.map(([name]) => name));
+    const codec: ProtocolCodec<T> = {
+        decode(value) {
+            const object = requireObject(value);
+            // Also enforces scalar, integer and depth rules for direct object inputs.
+            canonicalJson(object);
+            if (type !== undefined && object['$type'] !== type) throw new ProtocolError('invalid_type', `Expected ${type}.`);
+            const result: Record<string, unknown> = {};
+            for (const [name, field] of entries) {
+                if (!Object.hasOwn(object, field.wire)) {
+                    if (!field.optional) throw new ProtocolError('missing_field', `Missing ${field.wire}.`);
+                    continue;
+                }
+                const input = object[field.wire]!;
+                if (input === null && field.nullable) result[name] = null;
+                else result[name] = field.codec.decode(input);
+            }
+            const extras: JsonObject = Object.create(null) as JsonObject;
+            for (const [name, field] of Object.entries(object)) if (!wireNames.has(name)) extras[name] = field;
+            if (Object.keys(extras).length !== 0) result.additionalProperties = requireObject(parseJson(canonicalJson(extras)));
+            return result as T;
+        },
+        encode(value) {
+            if (value === null || typeof value !== 'object') throw new ProtocolError('invalid_model', 'Expected a model object.');
+            for (const name of Object.keys(value))
+                if (name !== 'additionalProperties' && !modelNames.has(name)) throw new ProtocolError('invalid_model', `Unknown model member ${name}; use additionalProperties for wire extensions.`);
+            const result: JsonObject = Object.create(null) as JsonObject;
+            if (type !== undefined) result['$type'] = type;
+            for (const [name, field] of entries) {
+                const input = (value as Record<string, unknown>)[name];
+                if (input === undefined && field.optional) continue;
+                if (input === undefined) throw new ProtocolError('missing_field', `Missing ${name}.`);
+                if (input === null && field.nullable) result[field.wire] = null;
+                else result[field.wire] = field.codec.encode(input);
+            }
+            for (const [name, field] of Object.entries(value.additionalProperties ?? {})) {
+                if (wireNames.has(name)) throw new ProtocolError('conflicting_extension', `Extension conflicts with ${name}.`);
+                result[name] = field;
+            }
+            // Copy extensions and validate the entire resulting tree without normalizing fields.
+            return requireObject(parseJson(canonicalJson(result)));
+        },
+        parse(input) { return this.decode(parseJson(input)); },
+        stringify(value) { return canonicalJson(this.encode(value)); },
+    };
+    return codec;
+}

package/src/protocol/context.ts

@@ -0,0 +1,39 @@
+import { ProtocolError } from '../errors.js';
+import { canonicalBytes, requireSafeInteger, type JsonObject } from './json.js';
+
+/** Trusted network identity; a remote document cannot supply this configuration. */
+export class NetworkContext {
+    constructor(readonly reference: number, readonly registry: string) {
+        requireSafeInteger(reference, 0);
+        if (reference > 0xffff_ffff || registry.length !== 42 || !/^0x[0-9a-f]{40}$/.test(registry))
+            throw new ProtocolError('invalid_context', 'Expected a Neo uint32 network reference and lowercase registry hash.');
+        Object.freeze(this);
+    }
+
+    static parse(value: string): NetworkContext {
+        const match = /^neo:(0|[1-9][0-9]{0,9}):(0x[0-9a-f]{40})$/.exec(value);
+        if (!match || match[0] !== value) throw new ProtocolError('invalid_context', 'Expected a canonical network context.');
+        return new NetworkContext(Number(match[1]), match[2]!);
+    }
+
+    toString(): string { return `neo:${this.reference}:${this.registry}`; }
+}
+
+/** Binds a complete object to the trusted network, excluding only named root fields. */
+export function signingInput(value: JsonObject, context: NetworkContext, excluded: readonly string[] = []): Uint8Array {
+    if (Object.hasOwn(value, '$context'))
+        throw new ProtocolError('invalid_context', 'A protocol object must not contain a root $context property.');
+    const result: JsonObject = Object.create(null) as JsonObject;
+    for (const [name, field] of Object.entries(value)) if (!excluded.includes(name)) result[name] = field;
+    result['$context'] = context.toString();
+    return canonicalBytes(result);
+}
+
+/** Advances a counter without overflow, approximation, or reuse of a previous value. */
+export function nextRevision(known: number, requested?: number): number {
+    requireSafeInteger(known, -1);
+    const result = requested ?? known + 1;
+    requireSafeInteger(result, 0);
+    if (result <= known) throw new ProtocolError('revision_exhausted', 'Revision must exceed every known revision.');
+    return result;
+}

package/src/protocol/encoding.ts

@@ -0,0 +1,106 @@
+import { ProtocolError } from '../errors.js';
+
+const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+/** Rejects unpaired UTF-16 surrogates without normalizing valid text. */
+export function validateUnicode(value: string): void {
+    for (let index = 0; index < value.length; index++) {
+        const unit = value.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = value.charCodeAt(++index);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                throw new ProtocolError('invalid_unicode', 'Unpaired high surrogate.');
+        } else if (unit >= 0xdc00 && unit <= 0xdfff) {
+            throw new ProtocolError('invalid_unicode', 'Unpaired low surrogate.');
+        }
+    }
+}
+
+/** Encodes Unicode scalar values as UTF-8 without silently replacing invalid text. */
+export function encodeUtf8(value: string): Uint8Array {
+    validateUnicode(value);
+    return new TextEncoder().encode(value);
+}
+
+/** Strict UTF-8 decoding, independent of platform TextDecoder error handling. */
+export function decodeUtf8(bytes: Uint8Array): string {
+    const chunks: string[] = [];
+    let chunk = '';
+    for (let index = 0; index < bytes.length;) {
+        const first = bytes[index++]!;
+        let scalar: number;
+        let count: number;
+        let minimum: number;
+        if (first <= 0x7f) { scalar = first; count = 0; minimum = 0; }
+        else if (first >= 0xc2 && first <= 0xdf) { scalar = first & 31; count = 1; minimum = 0x80; }
+        else if (first >= 0xe0 && first <= 0xef) { scalar = first & 15; count = 2; minimum = 0x800; }
+        else if (first >= 0xf0 && first <= 0xf4) { scalar = first & 7; count = 3; minimum = 0x10000; }
+        else throw new ProtocolError('invalid_utf8', 'Invalid UTF-8 leading byte.');
+        for (let part = 0; part < count; part++) {
+            const continuation = bytes[index++];
+            if (continuation === undefined || (continuation & 0xc0) !== 0x80)
+                throw new ProtocolError('invalid_utf8', 'Invalid or incomplete UTF-8 sequence.');
+            scalar = (scalar << 6) | (continuation & 63);
+        }
+        if (scalar < minimum || scalar > 0x10ffff || (scalar >= 0xd800 && scalar <= 0xdfff))
+            throw new ProtocolError('invalid_utf8', 'Noncanonical UTF-8 scalar.');
+        chunk += String.fromCodePoint(scalar);
+        if (chunk.length >= 4096) { chunks.push(chunk); chunk = ''; }
+    }
+    chunks.push(chunk);
+    return chunks.join('');
+}
+
+/** Encodes bytes as canonical unpadded base64url. */
+export function encodeBase64Url(bytes: Uint8Array): string {
+    const chunks: string[] = [];
+    let chunk = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index]!;
+        const second = bytes[index + 1];
+        const third = bytes[index + 2];
+        chunk += alphabet[first >>> 2]! + alphabet[((first & 3) << 4) | ((second ?? 0) >>> 4)]!;
+        if (second !== undefined) chunk += alphabet[((second & 15) << 2) | ((third ?? 0) >>> 6)]!;
+        if (third !== undefined) chunk += alphabet[third & 63]!;
+        if (chunk.length >= 4096) { chunks.push(chunk); chunk = ''; }
+    }
+    chunks.push(chunk);
+    return chunks.join('');
+}
+
+/** Decodes only canonical unpadded base64url, including zero trailing pad bits. */
+export function decodeBase64Url(value: string, expectedLength?: number): Uint8Array {
+    if (/[^A-Za-z0-9_-]/.test(value) || value.length % 4 === 1)
+        throw new ProtocolError('invalid_base64url', 'Expected canonical unpadded base64url.');
+    const tail = value.length === 0 ? 0 : alphabet.indexOf(value.at(-1)!);
+    if ((value.length % 4 === 2 && (tail & 15) !== 0) || (value.length % 4 === 3 && (tail & 3) !== 0))
+        throw new ProtocolError('invalid_base64url', 'Nonzero base64url padding bits.');
+    const result = new Uint8Array(Math.floor(value.length * 6 / 8));
+    if (expectedLength !== undefined && result.length !== expectedLength)
+        throw new ProtocolError('invalid_length', `Expected ${expectedLength} bytes.`);
+    let bits = 0;
+    let available = 0;
+    let offset = 0;
+    for (const character of value) {
+        bits = (bits << 6) | alphabet.indexOf(character);
+        available += 6;
+        if (available >= 8) { available -= 8; result[offset++] = (bits >>> available) & 255; }
+    }
+    return result;
+}
+
+/** Concatenates byte arrays without retaining references to the inputs. */
+export function concatBytes(...values: readonly Uint8Array[]): Uint8Array {
+    const result = new Uint8Array(values.reduce((size, value) => size + value.length, 0));
+    let offset = 0;
+    for (const value of values) { result.set(value, offset); offset += value.length; }
+    return result;
+}
+
+/** Compares byte values without an early exit on unequal content. */
+export function equalBytes(left: Uint8Array, right: Uint8Array): boolean {
+    if (left.length !== right.length) return false;
+    let difference = 0;
+    for (let index = 0; index < left.length; index++) difference |= left[index]! ^ right[index]!;
+    return difference === 0;
+}