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

package/src/transport/pool.ts

@@ -0,0 +1,115 @@
+import { createAbortController } from '../runtime/abort.js';
+import { ProtocolError } from '../errors.js';
+import { validateAccountId, validateRelayId } from '../identity/neo.js';
+import type { RelayRegistry } from '../interactions.js';
+import { certificateId } from '../models/identity.js';
+import type { NetworkContext } from '../protocol/context.js';
+import { awaitWithSignal, throwIfAborted } from '../runtime/clock.js';
+import { EventHub, type EventListener } from '../runtime/events.js';
+import { RelayClient, type RelayTransportOptions } from './client.js';
+import { RelayAuthenticator, type AuthenticationIdentity } from './session.js';
+
+export interface RelayClientPoolOptions extends RelayTransportOptions { readonly context: NetworkContext; readonly accountId: string }
+export interface RelayPoolEvents { readonly poolChanged: readonly RelayClient[]; readonly relayChanged: RelayClient; readonly errorOccurred: unknown }
+interface Entry { client: RelayClient; ready: Promise<void>; mode: 'account' | 'device' | undefined; retired: boolean }
+
+/** Owns account/device sessions separately; a pool binds to one network, account and device. */
+export class RelayClientPool {
+    readonly #events = new EventHub<RelayPoolEvents>();
+    readonly #entries = new Map<string, Entry[]>();
+    readonly #retirements = new Set<Promise<void>>();
+    readonly #lifetime = createAbortController();
+    readonly #options: RelayClientPoolOptions;
+    #deviceId: string | undefined;
+    #disposal: Promise<void> | undefined;
+    #lastError: unknown;
+    readonly context: NetworkContext;
+    readonly accountId: string;
+    constructor(options: RelayClientPoolOptions, readonly registry: RelayRegistry) {
+        validateAccountId(options.accountId);
+        if (options.context.toString() !== registry.context.toString()) throw new ProtocolError('invalid_context', 'Registry and client network contexts differ.');
+        this.context = options.context; this.accountId = options.accountId; this.#options = { ...options };
+    }
+    get clients(): readonly RelayClient[] { return Object.freeze([...this.#entries.values()].flatMap(entries => entries.map(entry => entry.client))); }
+    /** Last application observer failure; transport failures remain on each relay client's state. */
+    get lastError(): unknown { return this.#lastError; }
+    on<K extends keyof RelayPoolEvents>(event: K, listener: EventListener<RelayPoolEvents[K]>): () => void { return this.#events.on(event, listener); }
+    #notify<K extends Exclude<keyof RelayPoolEvents, 'errorOccurred'>>(event: K, value: RelayPoolEvents[K]): void {
+        this.#events.notify(event, value, error => {
+            this.#lastError = error;
+            this.#events.notify('errorOccurred', error, observerError => {
+                this.#lastError = new AggregateError([error, observerError], 'Pool observer and error observer failed.');
+            });
+        });
+    }
+
+    async get(relayId: string, identity?: AuthenticationIdentity, signal?: AbortSignal): Promise<RelayClient> {
+        throwIfAborted(signal); throwIfAborted(this.#lifetime.signal); validateRelayId(relayId);
+        if (this.registry.context.toString() !== this.context.toString()) throw new ProtocolError('context_changed', 'Registry network context changed.');
+        if (identity) {
+            const account = identity.mode === 'account' ? identity.signer.accountId : identity.signer.certificate.account;
+            if (account !== this.accountId) throw new ProtocolError('invalid_identity', 'Signer belongs to another account.');
+            if (identity.mode === 'device') {
+                const device = certificateId(identity.signer.certificate, this.context);
+                if (this.#deviceId !== undefined && this.#deviceId !== device) throw new ProtocolError('invalid_identity', 'Pool is already bound to another device.');
+                this.#deviceId = device;
+            }
+        }
+        let entries = this.#entries.get(relayId);
+        let entry = identity ? entries?.find(entry => entry.mode === identity.mode) : entries?.[0];
+        if (!entry) {
+            const authenticator = identity === undefined ? undefined : new RelayAuthenticator(relayId, this.context, identity, this.#options.clock);
+            const client = new RelayClient(relayId, this.registry, this.#options, authenticator);
+            entry = { client, mode: identity?.mode, retired: false, ready: Promise.resolve() };
+            if (!entries) { entries = []; this.#entries.set(relayId, entries); }
+            entries.push(entry);
+            const captured = entry;
+            client.on('stateChanged', () => this.#notify('relayChanged', client));
+            client.on('faulted', () => { this.#retire(captured); });
+            // Publish only after the readiness promise is installed, so a callback
+            // acquiring the same relay waits for this authentication too.
+            entry.ready = Promise.resolve().then(async () => {
+                this.#notify('poolChanged', this.clients);
+                if (authenticator) await client.authenticate(this.#lifetime.signal);
+            });
+            entry.ready.then(() => undefined, () => { this.#retire(captured); });
+        }
+        await awaitWithSignal(entry.ready, signal);
+        throwIfAborted(this.#lifetime.signal); throwIfAborted(signal);
+        if (entry.retired) throw new ProtocolError('retired_client', 'Relay client was retired while being acquired.');
+        return entry.client;
+    }
+
+    #retire(entry: Entry): void {
+        if (entry.retired) return;
+        entry.retired = true;
+        const entries = this.#entries.get(entry.client.relayId)!;
+        entries.splice(entries.indexOf(entry), 1);
+        if (entries.length === 0) this.#entries.delete(entry.client.relayId);
+        const cleanup = (async () => { await entry.client.dispose(); this.#notify('poolChanged', this.clients); })();
+        this.#retirements.add(cleanup);
+        // Keep failed retirements for dispose/invalidate to surface; successful ones need no retained task.
+        cleanup.then(() => this.#retirements.delete(cleanup), () => undefined);
+    }
+
+    /** Device registration/key changes require new device sessions; account sessions remain independent. */
+    async invalidateDevice(): Promise<void> {
+        throwIfAborted(this.#lifetime.signal);
+        for (const entries of [...this.#entries.values()]) for (const entry of [...entries]) if (entry.mode === 'device') this.#retire(entry);
+        this.#deviceId = undefined;
+        await this.#finishRetirements();
+    }
+    async #finishRetirements(): Promise<void> {
+        const jobs = [...this.#retirements]; const results = await Promise.allSettled(jobs);
+        for (const job of jobs) this.#retirements.delete(job);
+        const errors = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map(result => result.reason);
+        if (errors.length) throw new AggregateError(errors, 'Relay client retirement failed.');
+    }
+    dispose(): Promise<void> {
+        return this.#disposal ??= (async () => {
+            this.#lifetime.abort(new DOMException('Relay client pool was disposed.', 'AbortError'));
+            for (const entries of [...this.#entries.values()]) for (const entry of [...entries]) this.#retire(entry);
+            try { await this.#finishRetirements(); } finally { this.#events.clear(); }
+        })();
+    }
+}

package/src/transport/relay-error.ts

@@ -0,0 +1,46 @@
+import { ProtocolError } from '../errors.js';
+import { defineCodec, text, type ExtensibleModel } from '../protocol/codec.js';
+import { requireObject, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+
+export interface RelayFailure extends ExtensibleModel { readonly code: string; readonly message: string; readonly data?: JsonObject }
+export const relayFailureCodec = defineCodec<RelayFailure>({
+    code: { wire: 'code', codec: text }, message: { wire: 'message', codec: text },
+    data: { wire: 'data', codec: { decode: requireObject, encode: requireObject }, optional: true },
+});
+
+export const rpcErrorCodes: Readonly<Record<string, number>> = Object.freeze({
+    bad_request: -32602, method_not_found: -32601, internal_error: -32603, unauthorized: -32001, forbidden: -32003,
+    invalid_signature: -32004, device_unknown: -32005, clock_skew: -32006, not_found: -32010, state_conflict: -32011,
+    stale_state: -32012, invalid_state: -32013, message_expired: -32014, request_too_large: -32015, target_not_local: -32020,
+    route_stale: -32021, route_not_found: -32022, bad_gateway: -32023, rate_limited: -32030, temporarily_unavailable: -32031,
+});
+const definitiveCodes = new Set(Object.keys(rpcErrorCodes).filter(code => !['internal_error', 'bad_gateway', 'temporarily_unavailable'].includes(code)));
+
+export function retryAfter(failure: RelayFailure): number | undefined {
+    if (failure.code !== 'rate_limited' || failure.data?.retry_after === undefined) return undefined;
+    requireSafeInteger(failure.data.retry_after, 0);
+    return failure.data.retry_after;
+}
+
+/** Only isDefinitiveRejection proves that a business operation was not accepted. */
+export class RelayError extends Error {
+    override readonly name = 'RelayError';
+    readonly failure: RelayFailure;
+    constructor(failure: RelayFailure, readonly httpStatus?: number, readonly rpcCode?: number) {
+        super(failure.message);
+        this.failure = relayFailureCodec.decode(relayFailureCodec.encode(failure));
+        retryAfter(this.failure);
+    }
+    get code(): string { return this.failure.code; }
+    get retryAfter(): number | undefined { return retryAfter(this.failure); }
+    get isDefinitiveRejection(): boolean { return definitiveCodes.has(this.code); }
+}
+
+export function validateRetryAfterHeader(failure: RelayFailure, status: number, header: string | null): void {
+    if (failure.code !== 'rate_limited') return;
+    const seconds = retryAfter(failure);
+    if (header !== null && (seconds === undefined || !/^[0-9]+$/.test(header) || /\s/.test(header)
+        || !Number.isSafeInteger(Number(header)) || Number(header) !== seconds)
+        || status === 429 && seconds !== undefined && header === null)
+        throw new ProtocolError('invalid_retry_after', 'Retry-After must match the error retry_after value.');
+}

package/src/transport/rpc.ts

@@ -0,0 +1,56 @@
+import { ProtocolError } from '../errors.js';
+import { encodeUtf8 } from '../protocol/encoding.js';
+import { canonicalJson, parseJson, requireObject, requireSafeInteger, type JsonObject, type JsonValue } from '../protocol/json.js';
+import { validateMethodName } from './endpoint.js';
+import { RelayError, rpcErrorCodes } from './relay-error.js';
+
+export const maxSocketMessageBytes = 1_048_576;
+export type RpcId = string | number;
+export interface RpcNotification { readonly method: string; readonly params?: JsonObject }
+export interface RpcFailure { readonly code: number; readonly message: string; readonly data?: JsonObject }
+export type RpcMessage = { readonly kind: 'notification'; readonly notification: RpcNotification }
+    | { readonly kind: 'success'; readonly id: RpcId; readonly result: JsonValue }
+    | { readonly kind: 'failure'; readonly id: RpcId | null; readonly error: RpcFailure };
+
+function requireId(value: JsonValue | undefined): RpcId {
+    if (typeof value === 'number') { requireSafeInteger(value); return value; }
+    if (typeof value !== 'string' || encodeUtf8(value).length > 128) throw new ProtocolError('invalid_rpc_id', 'RPC IDs must be safe integers or strings of at most 128 UTF-8 bytes.');
+    return value;
+}
+
+export function encodeRpcRequest(id: RpcId, method: string, params?: JsonObject): string {
+    requireId(id);
+    validateMethodName(method);
+    const value: JsonObject = { jsonrpc: '2.0', id, method, ...(params === undefined ? {} : { params: requireObject(params) }) };
+    const text = canonicalJson(value);
+    if (encodeUtf8(text).length > maxSocketMessageBytes) throw new ProtocolError('request_too_large', 'A WebSocket request cannot exceed 1 MiB.');
+    return text;
+}
+
+/** Parses the whole message before ignoring unknown JSON-RPC wrapper extensions. */
+export function decodeRpcMessage(text: string): RpcMessage {
+    if (encodeUtf8(text).length > maxSocketMessageBytes) throw new ProtocolError('message_too_large', 'A WebSocket message cannot exceed 1 MiB.');
+    const value = requireObject(parseJson(text));
+    if (value.jsonrpc !== '2.0') throw new ProtocolError('invalid_rpc', 'Expected JSON-RPC 2.0.');
+    const has = (key: string): boolean => Object.hasOwn(value, key);
+    if (!has('id')) {
+        if (typeof value.method !== 'string' || value.method.length === 0)
+            throw new ProtocolError('invalid_rpc', 'A notification must have a method and no id.');
+        // Future method names are retained. Dispatchers may ignore notifications they do not know.
+        return { kind: 'notification', notification: { method: value.method, ...(has('params') ? { params: requireObject(value.params!) } : {}) } };
+    }
+    if (has('result') === has('error')) throw new ProtocolError('invalid_rpc', 'A response must contain exactly one of result or error.');
+    if (has('result')) return { kind: 'success', id: requireId(value.id), result: value.result! };
+    const error = requireObject(value.error!);
+    requireSafeInteger(error.code);
+    if (typeof error.message !== 'string') throw new ProtocolError('invalid_rpc', 'An RPC error must have a string message.');
+    return { kind: 'failure', id: value.id === null ? null : requireId(value.id),
+        error: { code: error.code, message: error.message, ...(Object.hasOwn(error, 'data') ? { data: requireObject(error.data!) } : {}) } };
+}
+
+export function rpcFailureError(error: RpcFailure): RelayError | ProtocolError {
+    const code = Object.keys(rpcErrorCodes).find(key => rpcErrorCodes[key] === error.code);
+    return code === undefined
+        ? new ProtocolError('unknown_rpc_error', `Unmapped JSON-RPC error ${error.code}: ${error.message}`)
+        : new RelayError({ code, message: error.message, ...(error.data === undefined ? {} : { data: error.data }) }, undefined, error.code);
+}

package/src/transport/session.ts

@@ -0,0 +1,154 @@
+import { createAbortController } from '../runtime/abort.js';
+import { verifyAccount, verifyDevice } from '../crypto/primitives.js';
+import { ProtocolError } from '../errors.js';
+import { matchesAccount, validateRelayId } from '../identity/neo.js';
+import type { AccountSigner, DeviceSigner } from '../interactions.js';
+import {
+    accountAuthenticationCodec, accountAuthenticationInput, authenticationChallengeCodec, deviceAuthenticationCodec,
+    deviceAuthenticationInput, sessionCredentialsCodec, validateChallenge, validateSession,
+    type AccountAuthenticationRequest, type DeviceAuthenticationRequest, type SessionCredentials, type SessionMode,
+} from '../models/authentication.js';
+import { certificateId, deviceCertificateCodec, validateCertificate } from '../models/identity.js';
+import { NetworkContext } from '../protocol/context.js';
+import { equalBytes } from '../protocol/encoding.js';
+import type { JsonObject, JsonValue } from '../protocol/json.js';
+import { abortScope, awaitWithSignal, systemClock, throwIfAborted, type RuntimeClock } from '../runtime/clock.js';
+import { relayOrigin } from './endpoint.js';
+import type { HttpRelayTransport } from './http.js';
+
+export type AuthenticationIdentity = { readonly mode: 'account'; readonly signer: AccountSigner } | { readonly mode: 'device'; readonly signer: DeviceSigner };
+export type AuthenticationSender = (method: string, parameters: JsonObject, signal?: AbortSignal) => Promise<JsonValue | undefined>;
+
+/** Keeps bearer credentials out of ordinary object enumeration and diagnostic serialization. */
+export class RelaySession {
+    readonly #credentials: SessionCredentials;
+    readonly #clock: RuntimeClock;
+    readonly #started: number;
+    readonly #lifetimeMilliseconds: number;
+    constructor(credentials: SessionCredentials, readonly origin: string, challengeCreatedAt: number, started: number, clock: RuntimeClock) {
+        this.#credentials = sessionCredentialsCodec.decode(sessionCredentialsCodec.encode(credentials));
+        this.#started = started;
+        this.#clock = clock;
+        this.#lifetimeMilliseconds = (credentials.expiresAt - challengeCreatedAt - 1) * 1000;
+    }
+    get mode(): SessionMode { return this.#credentials.mode; }
+    get lifetimeSeconds(): number { return this.#lifetimeMilliseconds / 1000; }
+    get remainingSeconds(): number { return (this.#lifetimeMilliseconds - (this.#clock.monotonicMilliseconds() - this.#started)) / 1000; }
+    /** Return only for sending a request to origin. Do not log or persist. */
+    getToken(endpoint: string): string {
+        if (relayOrigin(endpoint) !== this.origin) throw new ProtocolError('invalid_origin', 'A session cannot be sent to a different origin.');
+        if (this.remainingSeconds <= 0) throw new ProtocolError('expired_session', 'The relay session has expired.');
+        return this.#credentials.token;
+    }
+}
+
+/** Captures immutable identity at binding time; certificate renewal for the same device is allowed. */
+export class RelayAuthenticator {
+    readonly #identity: AuthenticationIdentity;
+    readonly #publicKey: Uint8Array | undefined;
+    readonly accountId: string;
+    readonly deviceId: string | undefined;
+    readonly mode: SessionMode;
+    constructor(readonly relayId: string, readonly context: NetworkContext, identity: AuthenticationIdentity, readonly clock: RuntimeClock = systemClock) {
+        validateRelayId(relayId);
+        this.#identity = { ...identity };
+        this.mode = identity.mode;
+        if (identity.mode === 'account') {
+            this.accountId = identity.signer.accountId;
+            this.#publicKey = identity.signer.publicKey.slice();
+            if (!matchesAccount(this.accountId, this.#publicKey)) throw new ProtocolError('invalid_identity', 'The signer public key does not identify its account.');
+        } else {
+            const certificate = identity.signer.certificate;
+            validateCertificate(certificate, context);
+            this.accountId = certificate.account;
+            this.deviceId = certificateId(certificate, context);
+        }
+    }
+
+    assertIdentity(): void {
+        const identity = this.#identity;
+        if (identity.mode === 'account') {
+            if (identity.signer.accountId !== this.accountId || !equalBytes(identity.signer.publicKey, this.#publicKey!))
+                throw new ProtocolError('identity_changed', 'The account signer identity has changed.');
+        } else {
+            const certificate = identity.signer.certificate;
+            if (certificate.account !== this.accountId || certificateId(certificate, this.context) !== this.deviceId)
+                throw new ProtocolError('identity_changed', 'The device signer identity has changed.');
+        }
+    }
+
+    async authenticate(endpoint: string, send: AuthenticationSender, signal?: AbortSignal): Promise<RelaySession> {
+        throwIfAborted(signal);
+        this.assertIdentity();
+        const origin = relayOrigin(endpoint);
+        // Clone before awaits: a mutable application object must not change the signed proof in flight.
+        const identity = this.#identity;
+        const certificate = identity.mode === 'device' ? deviceCertificateCodec.decode(deviceCertificateCodec.encode(identity.signer.certificate)) : undefined;
+        if (certificate) validateCertificate(certificate, this.context);
+        const started = this.clock.monotonicMilliseconds();
+        const challengeWire = await send('auth.challenge', { account: this.accountId }, signal);
+        if (challengeWire === undefined) throw new ProtocolError('missing_result', 'Authentication challenge has no result.');
+        const challenge = authenticationChallengeCodec.decode(challengeWire);
+        validateChallenge(challenge);
+        this.assertIdentity();
+        let method: string;
+        let proof: JsonObject;
+        if (identity.mode === 'device') {
+            const request: DeviceAuthenticationRequest = { nonce: challenge.nonce, timestamp: this.clock.nowSeconds(), signerCertificate: certificate!, deviceSignature: new Uint8Array(64) };
+            const input = deviceAuthenticationInput(request, this.relayId, endpoint, this.context);
+            const signature = await identity.signer.sign(input.slice(), signal);
+            if (!verifyDevice(input, signature, certificate!.signingPublicKey)) throw new ProtocolError('invalid_signature', 'The device signer returned an invalid signature.');
+            proof = deviceAuthenticationCodec.encode({ ...request, deviceSignature: signature });
+            method = 'auth.device.verify';
+        } else {
+            const request: AccountAuthenticationRequest = { nonce: challenge.nonce, accountPublicKey: this.#publicKey!.slice(), accountSignature: new Uint8Array(64) };
+            const input = accountAuthenticationInput(request, this.accountId, this.relayId, endpoint, this.context);
+            const signature = await identity.signer.sign(input.slice(), signal);
+            if (!verifyAccount(input, signature, this.#publicKey!)) throw new ProtocolError('invalid_signature', 'The account signer returned an invalid signature.');
+            proof = accountAuthenticationCodec.encode({ ...request, accountSignature: signature });
+            method = 'auth.account.verify';
+        }
+        throwIfAborted(signal);
+        this.assertIdentity();
+        if (this.clock.monotonicMilliseconds() - started >= (challenge.expiresAt - challenge.createdAt) * 1000)
+            throw new ProtocolError('expired_challenge', 'The challenge expired before the proof could be submitted.');
+        const sessionWire = await send(method, proof, signal);
+        throwIfAborted(signal);
+        this.assertIdentity();
+        if (sessionWire === undefined) throw new ProtocolError('missing_result', 'Authentication verification has no result.');
+        const credentials = sessionCredentialsCodec.decode(sessionWire);
+        validateSession(credentials);
+        const session = new RelaySession(credentials, origin, challenge.createdAt, started, this.clock);
+        if (session.mode !== this.mode || session.remainingSeconds <= 0) throw new ProtocolError('invalid_session', 'Relay returned an expired session or a different authentication mode.');
+        return session;
+    }
+}
+
+/** Shares only authentication work. Canceling a waiter never cancels another caller's refresh. */
+export class HttpRelaySessions {
+    readonly #lifetime = createAbortController();
+    #session: RelaySession | undefined;
+    #pending: { origin: string; promise: Promise<RelaySession> } | undefined;
+    constructor(readonly authenticator: RelayAuthenticator, readonly transport: HttpRelayTransport) {}
+
+    get(endpoint: string, signal?: AbortSignal): Promise<RelaySession> {
+        throwIfAborted(signal);
+        throwIfAborted(this.#lifetime.signal);
+        this.authenticator.assertIdentity();
+        const origin = relayOrigin(endpoint);
+        if (this.#session?.origin === origin && this.#session.remainingSeconds > Math.min(5, this.#session.lifetimeSeconds * 0.2)) return Promise.resolve(this.#session);
+        if (this.#pending?.origin === origin) return awaitWithSignal(this.#pending.promise, signal);
+        const scope = abortScope([this.#lifetime.signal]);
+        const pending = { origin, promise: this.authenticator.authenticate(endpoint,
+            (name, parameters, token) => this.transport.request(endpoint, 'POST', name, parameters, undefined, token), scope.signal) };
+        this.#pending = pending;
+        pending.promise.then(session => {
+            scope.dispose();
+            if (this.#pending === pending) { this.#session = session; this.#pending = undefined; }
+        }, () => { scope.dispose(); if (this.#pending === pending) this.#pending = undefined; });
+        return awaitWithSignal(pending.promise, signal);
+    }
+
+    invalidate(session?: RelaySession): void { if (session === undefined || this.#session === session) this.#session = undefined; }
+    dispose(): void { this.#session = undefined; this.#pending = undefined; this.#lifetime.abort(new DOMException('Relay sessions were disposed.', 'AbortError')); }
+}

package/src/transport/socket.ts

@@ -0,0 +1,248 @@
+import { createAbortController, abortReason } from '../runtime/abort.js';
+import { systemRandom, type RandomSource } from '../crypto/primitives.js';
+import { ProtocolError } from '../errors.js';
+import { sessionCredentialsCodec, validateSession, type SessionMode } from '../models/authentication.js';
+import { encodeBase64Url } from '../protocol/encoding.js';
+import type { JsonObject, JsonValue } from '../protocol/json.js';
+import { abortScope, awaitWithSignal, systemClock, throwIfAborted, type RuntimeClock } from '../runtime/clock.js';
+import { webEndpoint } from './endpoint.js';
+import { RelayBackoff } from './http.js';
+import { RelayError } from './relay-error.js';
+import { decodeRpcMessage, encodeRpcRequest, rpcFailureError, type RpcId, type RpcMessage, type RpcNotification } from './rpc.js';
+
+export interface RelaySocketEvents {
+    open: undefined;
+    message: unknown;
+    error: Error;
+    close: { readonly code: number; readonly reason: string };
+}
+
+/** Platform socket adapters normalize events and report the actual close code they can send. */
+export interface RelaySocket {
+    readonly readyState: number;
+    readonly bufferedAmount: number;
+    send(text: string): void;
+    close(code: number, reason: string): number;
+    on<K extends keyof RelaySocketEvents>(event: K, listener: (value: RelaySocketEvents[K]) => void): () => void;
+}
+export type RelaySocketFactory = (endpoint: string) => RelaySocket;
+
+/** Browsers only allow 1000 or application codes in close(); 3003/3009 report the corresponding local rejection. */
+export const browserSocketFactory: RelaySocketFactory = endpoint => {
+    const socket = new WebSocket(endpoint);
+    socket.binaryType = 'arraybuffer';
+    return {
+        get readyState() { return socket.readyState; },
+        get bufferedAmount() { return socket.bufferedAmount; },
+        send(text) { socket.send(text); },
+        close(code, reason) { const actual = code === 1000 ? code : 3000 + code - 1000; socket.close(actual, reason); return actual; },
+        on(event, listener) {
+            const handler = (value: Event): void => {
+                const normalized = event === 'open' ? undefined : event === 'message' ? (value as MessageEvent<unknown>).data
+                    : event === 'close' ? { code: (value as CloseEvent).code, reason: (value as CloseEvent).reason }
+                        : new Error('The browser WebSocket failed; inspect the browser network diagnostics.');
+                listener(normalized as RelaySocketEvents[typeof event]);
+            };
+            socket.addEventListener(event, handler);
+            return () => socket.removeEventListener(event, handler);
+        },
+    };
+};
+
+export interface SocketFailure { readonly error: unknown; readonly requestedCloseCode: number; readonly sentCloseCode: number | undefined }
+interface Pending { readonly method: string; resolve(message: Exclude<RpcMessage, { kind: 'notification' }>): void; reject(error: unknown): void }
+export interface RpcConnectionOptions {
+    readonly socketFactory?: RelaySocketFactory;
+    readonly clock?: RuntimeClock;
+    readonly random?: RandomSource;
+    readonly backoff?: RelayBackoff;
+    readonly requestTimeoutMilliseconds?: number;
+}
+
+/** One connection only. Pool/session owners handle reconnect, renewal and notification catch-up. */
+export class RpcConnection {
+    readonly #factory: RelaySocketFactory;
+    readonly #clock: RuntimeClock;
+    readonly #random: RandomSource;
+    readonly #backoff: RelayBackoff;
+    readonly #timeout: number;
+    readonly #lifetime = createAbortController();
+    readonly #pending = new Map<RpcId, Pending>();
+    readonly #queue: RpcNotification[] = [];
+    readonly #waiters: { resolve(value: RpcNotification): void; reject(error: unknown): void }[] = [];
+    #socket: RelaySocket | undefined;
+    #opening: Promise<void> | undefined;
+    #rejectOpening: ((error: unknown) => void) | undefined;
+    #mode: SessionMode | undefined;
+    #sequence = 0;
+    #requestPrefix: string | undefined;
+    #failure: SocketFailure | undefined;
+    #resolveClosed!: (failure: SocketFailure) => void;
+    #unlisten: (() => void)[] = [];
+    readonly closed = new Promise<SocketFailure>(resolve => { this.#resolveClosed = resolve; });
+
+    constructor(readonly endpoint: string, options: RpcConnectionOptions = {}) {
+        webEndpoint(endpoint, 'wss:');
+        this.#factory = options.socketFactory ?? browserSocketFactory;
+        this.#clock = options.clock ?? systemClock;
+        this.#random = options.random ?? systemRandom;
+        this.#backoff = options.backoff ?? new RelayBackoff(this.#clock);
+        this.#timeout = options.requestTimeoutMilliseconds ?? 60000;
+        if (!Number.isSafeInteger(this.#timeout) || this.#timeout < 1 || this.#timeout > 2_147_483_647) throw new RangeError('Invalid socket timeout.');
+    }
+
+    get failure(): SocketFailure | undefined { return this.#failure; }
+    get establishedMode(): SessionMode | undefined { return this.#mode; }
+
+    connect(signal?: AbortSignal): Promise<void> {
+        throwIfAborted(signal);
+        throwIfAborted(this.#lifetime.signal);
+        if (this.#opening) return awaitWithSignal(this.#opening, signal);
+        this.#requestPrefix = encodeBase64Url(this.#random.bytes(16));
+        const scope = abortScope([this.#lifetime.signal], this.#timeout);
+        this.#opening = new Promise<void>((resolve, reject) => {
+            this.#rejectOpening = reject;
+            let socket: RelaySocket;
+            try { socket = this.#factory(this.endpoint); this.#socket = socket; }
+            catch (error) { this.#stop(error); reject(error); return; }
+            const onAbort = (): void => { this.#stop(abortReason(scope.signal)); reject(abortReason(scope.signal)); };
+            scope.signal.addEventListener('abort', onAbort, { once: true });
+            this.#unlisten.push(() => scope.signal.removeEventListener('abort', onAbort));
+            this.#unlisten.push(socket.on('open', () => {
+                if (this.#failure) return;
+                scope.dispose(); scope.signal.removeEventListener('abort', onAbort); this.#rejectOpening = undefined; resolve();
+            }));
+            this.#unlisten.push(socket.on('message', value => this.#receive(value)));
+            this.#unlisten.push(socket.on('error', cause => {
+                const error = new ProtocolError('socket_error', 'The relay WebSocket transport failed.', { cause });
+                this.#stop(error); reject(error);
+            }));
+            this.#unlisten.push(socket.on('close', event => {
+                const error = new ProtocolError('socket_closed', `Relay closed the WebSocket (${event.code}): ${event.reason}`);
+                this.#stop(error); reject(error);
+                this.#detach();
+            }));
+        });
+        // Both branches handle cleanup; the original rejection remains visible to every waiter.
+        this.#opening.then(() => scope.dispose(), () => scope.dispose());
+        return awaitWithSignal(this.#opening, signal);
+    }
+
+    async request(method: string, parameters?: JsonObject, signal?: AbortSignal): Promise<JsonValue> {
+        throwIfAborted(signal);
+        throwIfAborted(this.#lifetime.signal);
+        const scope = abortScope([signal, this.#lifetime.signal], this.#timeout);
+        let id: string | undefined;
+        let sent = false;
+        const authentication = method === 'auth.account.verify' || method === 'auth.device.verify';
+        try {
+            await this.connect(scope.signal);
+            await this.#backoff.wait(scope.signal);
+            if (this.#sequence === Number.MAX_SAFE_INTEGER) throw new ProtocolError('counter_overflow', 'Socket request sequence is exhausted.');
+            id = `${this.#requestPrefix}:${++this.#sequence}`;
+            const text = encodeRpcRequest(id, method, parameters);
+            while (this.#socket!.bufferedAmount > 1_048_576) await this.#clock.delay(10, scope.signal);
+            throwIfAborted(scope.signal);
+            if (this.#socket!.readyState !== 1) throw new ProtocolError('socket_closed', 'WebSocket is not open.');
+            const response = new Promise<Exclude<RpcMessage, { kind: 'notification' }>>((resolve, reject) => this.#pending.set(id!, { method, resolve, reject }));
+            // Register a rejection handler before send, which may synchronously emit an error.
+            const completion = awaitWithSignal(response, scope.signal);
+            try { this.#socket!.send(text); sent = true; }
+            catch (error) { this.#stop(error); }
+            const message = await completion;
+            if (message.kind === 'failure') {
+                const error = rpcFailureError(message.error);
+                if (error instanceof RelayError) {
+                    this.#backoff.apply(error.failure);
+                    if (error.code === 'unauthorized') this.#stop(error);
+                }
+                throw error;
+            }
+            return message.result;
+        } catch (error) {
+            if (authentication && sent && scope.signal.aborted) this.#stop(error);
+            throw error;
+        } finally { if (id !== undefined) this.#pending.delete(id); scope.dispose(); }
+    }
+
+    /** A single consumer normally drains this into the client notification dispatcher. */
+    nextNotification(signal?: AbortSignal): Promise<RpcNotification> {
+        throwIfAborted(signal);
+        throwIfAborted(this.#lifetime.signal);
+        const queued = this.#queue.shift();
+        if (queued) return Promise.resolve(queued);
+        return new Promise<RpcNotification>((resolve, reject) => {
+            const waiter = { resolve: (value: RpcNotification) => { signal?.removeEventListener('abort', onAbort); resolve(value); },
+                reject: (error: unknown) => { signal?.removeEventListener('abort', onAbort); reject(error); } };
+            const onAbort = (): void => {
+                const index = this.#waiters.indexOf(waiter);
+                if (index >= 0) this.#waiters.splice(index, 1);
+                waiter.reject(abortReason(signal!));
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            this.#waiters.push(waiter);
+        });
+    }
+
+    #receive(value: unknown): void {
+        if (this.#failure) return;
+        try {
+            if (typeof value !== 'string') { this.#stop(new ProtocolError('binary_message', 'Relay WebSocket messages must use text.'), 1003); return; }
+            const message = decodeRpcMessage(value);
+            if (message.kind === 'notification') {
+                if (this.#mode !== 'device') throw new ProtocolError('unauthorized_notification', 'Only an authenticated device connection can receive notifications.');
+                const waiting = this.#waiters.shift();
+                if (waiting) waiting.resolve(message.notification);
+                else {
+                    if (this.#queue.length >= 256) throw new ProtocolError('notification_overflow', 'Notification queue is full; reconnect and synchronize to recover missed updates.');
+                    this.#queue.push(message.notification);
+                }
+                return;
+            }
+            if (message.id === null) throw new ProtocolError('uncorrelated_response', 'Relay response has no correlatable request ID.');
+            const pending = this.#pending.get(message.id);
+            // Late responses to canceled requests remain valid frames but have no waiting caller.
+            if (!pending) return;
+            if (message.kind === 'success' && (pending.method === 'auth.account.verify' || pending.method === 'auth.device.verify')) {
+                const credentials = sessionCredentialsCodec.decode(message.result);
+                validateSession(credentials);
+                const mode = pending.method === 'auth.account.verify' ? 'account' : 'device';
+                if (credentials.mode !== mode || this.#mode !== undefined && this.#mode !== mode) throw new ProtocolError('invalid_session', 'The relay changed the socket session mode.');
+                // Set before resolving so a same-tick notification cannot race authentication.
+                this.#mode = mode;
+            }
+            this.#pending.delete(message.id);
+            pending.resolve(message);
+        } catch (error) { this.#stop(error, error instanceof ProtocolError && error.code === 'message_too_large' ? 1009 : 1000); }
+    }
+
+    #stop(error: unknown, code = 1000): void {
+        if (this.#failure) return;
+        // Set before abort: abort handlers can reenter stop.
+        this.#failure = { error, requestedCloseCode: code, sentCloseCode: undefined };
+        this.#rejectOpening?.(error);
+        this.#rejectOpening = undefined;
+        this.#lifetime.abort(error);
+        for (const pending of this.#pending.values()) pending.reject(error);
+        this.#pending.clear();
+        for (const waiter of this.#waiters.splice(0)) waiter.reject(error);
+        this.#queue.length = 0;
+        try {
+            if (this.#socket && this.#socket.readyState < 2) {
+                const sentCloseCode = this.#socket.close(code, code === 1003 ? 'Only text messages are supported.' : code === 1009 ? 'Message exceeds 1 MiB.' : 'Meshline connection ended.');
+                this.#failure = { error, requestedCloseCode: code, sentCloseCode };
+            }
+        } catch (closeError) { this.#failure = { error: new AggregateError([error, closeError], 'Socket failure and close failure.'), requestedCloseCode: code, sentCloseCode: undefined }; }
+        if (!this.#socket || this.#socket.readyState === 3) this.#detach();
+        this.#resolveClosed(this.#failure);
+    }
+
+    #detach(): void {
+        for (const unlisten of this.#unlisten) unlisten();
+        this.#unlisten = [];
+    }
+
+    dispose(): void { this.#stop(new DOMException('The RPC connection was disposed.', 'AbortError')); }
+    /** Retires this exact connection when authentication or subscription outcome is uncertain. */
+    fail(error: unknown): void { this.#stop(error); }
+}