import { useCallback, useRef, useSyncExternalStore } from "react"; import { Capacitor } from "@capacitor/core"; import { Preferences } from "@capacitor/preferences"; import { v4 as uuidv4 } from "uuid"; import { credentialKeyForRecord, credentialStore, normalizeDeviceKey, type StoredCredentials, } from "@/lib/crypto/credentials"; import { formatDeviceEndpoint, isValidHost, parseDeviceEndpoint, replaceDeviceEndpointHost, type DeviceEndpointScheme, type ParsedDeviceEndpoint, } from "@/lib/devices/endpoint"; import { logger } from "@/lib/logger"; export const DEVICE_REGISTRY_KEY = "deviceRegistryV2"; const LEGACY_ADDRESS_KEY = "deviceAddress"; const LEGACY_HISTORY_KEY = "deviceHistory"; const SCHEMA_VERSION = 2; export type DeviceEndpointSource = "manual" | "mdns"; export interface DeviceEndpoint { endpointId: string; scheme: DeviceEndpointScheme; host: string; port: number; source: DeviceEndpointSource; lastSeenAt?: number; /** * Addresses the last mDNS advertisement for this endpoint resolved to. * * The endpoint keeps its `.local` hostname as the canonical identity — that * is what survives the device changing IP — but iOS WebSockets do not * reliably resolve `.local` themselves, so the socket dials one of these * instead when they are known. */ resolvedAddresses?: string[]; } /** * How to find a Core over Bluetooth LE. Kept beside `endpoints` rather than as * an endpoint kind so app versions without Bluetooth still read the record. */ export interface DeviceBluetoothIdentity { /** Core's device id, as its Bluetooth Info and `device.endpoints` report. */ deviceId: string; /** The phone's last handle for the peripheral; it can change. */ peripheralId?: string; /** The advertised Bluetooth name. */ name?: string; lastSeenAt?: number; } /** The LAN addresses Core last reported for itself via `device.endpoints`. */ export interface DeviceReportedEndpoints { addresses: string[]; port: number; at: number; } export interface DeviceRecord { recordId: string; discoveryId?: string; /** Empty only for a Core known solely over Bluetooth (`ble` is then set). */ endpoints: DeviceEndpoint[]; /** `""` when `endpoints` is empty. */ preferredEndpointId: string; ble?: DeviceBluetoothIdentity; /** * Addresses Core reported itself; used as extra Wi-Fi candidates but never * shown or edited as the user's own endpoints. */ reportedEndpoints?: DeviceReportedEndpoints; /** * A pre-V2 credential key this record may still hold its pairing under. * * Credentials used to be keyed by address, which is why this exists at all: * every record created from an address the user had already used needs one * lookup at the old key before the canonical `record:` key exists. It is * cleared by `markConnected` the moment the peer authenticates with it, so a * record carries it at most until its first encrypted connection. */ legacyCredentialKey?: string; name?: string; nameIsCustom?: boolean; platform?: string; version?: string; lastConnectedAt?: number; } export interface DeviceRegistryV2 { schemaVersion: 2; activeRecordId: string | null; records: Record; } export interface DeviceRegistrySnapshot extends DeviceRegistryV2 { hydrated: boolean; hydrationError: string | null; } interface LegacyHistoryEntry { address: string; name?: string; nameIsCustom?: boolean; platform?: string; version?: string; lastConnectedAt?: number; } export interface DiscoveredDeviceRegistration { discoveryId?: string; hostname?: string; addresses: string[]; port: number; name?: string; platform?: string; version?: string; } /** Metadata learned from the device itself, never from the user. */ export interface DiscoveredDeviceMetadata { name?: string; platform?: string; version?: string; } function emptySnapshot(): DeviceRegistrySnapshot { return { schemaVersion: SCHEMA_VERSION, activeRecordId: null, records: {}, hydrated: false, hydrationError: null, }; } function normalizeDiscoveryId(value: string | undefined): string | undefined { const normalized = value?.trim().toLowerCase(); return normalized || undefined; } function unique(values: readonly string[]): string[] { return [...new Set(values)]; } /** * Set equality, not sequence equality. Both sides are deduped, so matching * lengths plus containment is enough. An mDNS re-announcement is free to list * the same addresses in a different order, and treating that as a change would * rewrite the record and republish the registry for nothing. */ function sameAddressSet( left: readonly string[], right: readonly string[], ): boolean { if (left.length !== right.length) return false; const existing = new Set(left); return right.every((address) => existing.has(address)); } function discoveryIdsConflict(left: DeviceRecord, right: DeviceRecord) { const leftId = normalizeDiscoveryId(left.discoveryId); const rightId = normalizeDiscoveryId(right.discoveryId); return Boolean(leftId && rightId && leftId !== rightId); } function mergeEndpoint( existing: DeviceEndpoint, incoming: DeviceEndpoint, ): DeviceEndpoint { const resolvedAddresses = unique([ ...(existing.resolvedAddresses ?? []), ...(incoming.resolvedAddresses ?? []), ]); const lastSeenAt = Math.max( existing.lastSeenAt ?? 0, incoming.lastSeenAt ?? 0, ); return { ...existing, source: existing.source === "mdns" || incoming.source === "mdns" ? "mdns" : "manual", ...(resolvedAddresses.length > 0 ? { resolvedAddresses } : {}), ...(lastSeenAt > 0 ? { lastSeenAt } : {}), }; } /** A merged record's preferred endpoint must be one it actually holds. */ function preferredAfterMerge(first: DeviceRecord, second: DeviceRecord) { if (first.endpoints.length > 0) return first.preferredEndpointId; return second.preferredEndpointId; } function mergeBluetoothIdentity( left: DeviceBluetoothIdentity | undefined, right: DeviceBluetoothIdentity | undefined, ): DeviceBluetoothIdentity { if (!left) return right!; if (!right) return left; const newer = (right.lastSeenAt ?? 0) > (left.lastSeenAt ?? 0) ? right : left; const older = newer === left ? right : left; return { ...older, ...newer }; } function sameBluetoothIdentity( left: DeviceBluetoothIdentity | undefined, right: DeviceBluetoothIdentity | undefined, ): boolean { return ( left?.deviceId === right?.deviceId && left?.peripheralId === right?.peripheralId && left?.name === right?.name ); } function endpointFromParsed( endpoint: ParsedDeviceEndpoint, source: DeviceEndpointSource, details: Pick = {}, ): DeviceEndpoint { return { endpointId: endpoint.endpointId, scheme: endpoint.scheme, host: endpoint.host, port: endpoint.port, source, ...(details.lastSeenAt !== undefined ? { lastSeenAt: details.lastSeenAt } : {}), ...(details.resolvedAddresses ? { resolvedAddresses: unique(details.resolvedAddresses) } : {}), }; } /** * The endpoint a record connects through, falling back to the first one when * `preferredEndpointId` no longer names an endpoint the record holds. * * Both public accessors go through here so they can never disagree about which * endpoint is preferred — resolving it twice once dropped `resolvedAddresses` * in exactly the case the fallback exists for. */ function preferredEndpointFor( record: DeviceRecord | null | undefined, ): DeviceEndpoint | null { if (!record) return null; return ( record.endpoints.find( (endpoint) => endpoint.endpointId === record.preferredEndpointId, ) ?? record.endpoints[0] ?? null ); } export function parsedEndpointForRecord( record: DeviceRecord | null | undefined, ): ParsedDeviceEndpoint | null { const preferred = preferredEndpointFor(record); if (!preferred) return null; const result = parseDeviceEndpoint(preferred.endpointId); return result.ok ? result.endpoint : null; } /** * Connection candidates for a record, preferred route first. mDNS hostnames * are replaced by their resolved addresses because iOS WebSockets do not * reliably resolve `.local`; merged manual aliases remain later fallbacks. */ export function resolvedEndpointsForRecord( record: DeviceRecord | null | undefined, ): ParsedDeviceEndpoint[] { const preferred = preferredEndpointFor(record); if (!record || !preferred) return []; const ordered = [ preferred, ...record.endpoints.filter( (endpoint) => endpoint.endpointId !== preferred.endpointId, ), ]; const endpointIds = unique( ordered.flatMap((endpoint) => { const parsed = parseDeviceEndpoint(endpoint.endpointId); if (!parsed.ok) return []; const resolved = (endpoint.resolvedAddresses ?? []).map( (address) => replaceDeviceEndpointHost(parsed.endpoint, address).endpointId, ); return resolved.length > 0 ? [...resolved, parsed.endpoint.endpointId] : [parsed.endpoint.endpointId]; }), ); return endpointIds .map((endpointId) => parseDeviceEndpoint(endpointId)) .filter((result) => result.ok) .map((result) => result.endpoint); } export function resolvedEndpointForRecord( record: DeviceRecord | null | undefined, ): ParsedDeviceEndpoint | null { return resolvedEndpointsForRecord(record)[0] ?? null; } /** * WebSocket URLs Core reported for itself that the record's own endpoints do * not already cover. They are later fallbacks, never the preferred route. */ export function reportedWebSocketUrlsForRecord( record: DeviceRecord | null | undefined, ): string[] { const reported = record?.reportedEndpoints; if (!reported) return []; const known = new Set( resolvedEndpointsForRecord(record).map((endpoint) => endpoint.wsUrl), ); return unique( reported.addresses .filter((address) => isValidHost(address)) .map( (address) => formatDeviceEndpoint(address, reported.port, "ws").wsUrl, ), ).filter((url) => !known.has(url)); } /** The active record's display address, or `""` before hydration. */ export function activeAddressOf(snapshot: DeviceRegistrySnapshot): string { const record = snapshot.activeRecordId ? snapshot.records[snapshot.activeRecordId] : null; return parsedEndpointForRecord(record)?.address ?? ""; } function validEndpoint(value: unknown): value is DeviceEndpoint { if (typeof value !== "object" || value === null) return false; const endpoint = value as Partial; if ( typeof endpoint.endpointId !== "string" || (endpoint.scheme !== "ws" && endpoint.scheme !== "wss") || typeof endpoint.host !== "string" || typeof endpoint.port !== "number" || (endpoint.source !== "manual" && endpoint.source !== "mdns") ) { return false; } const parsed = parseDeviceEndpoint(endpoint.endpointId); return ( parsed.ok && parsed.endpoint.scheme === endpoint.scheme && parsed.endpoint.host === endpoint.host && parsed.endpoint.port === endpoint.port && (endpoint.resolvedAddresses === undefined || (Array.isArray(endpoint.resolvedAddresses) && endpoint.resolvedAddresses.every( (address) => typeof address === "string", ))) ); } function validBluetoothIdentity( value: unknown, ): value is DeviceBluetoothIdentity { if (typeof value !== "object" || value === null) return false; const ble = value as Partial; return ( typeof ble.deviceId === "string" && ble.deviceId.trim() !== "" && (ble.peripheralId === undefined || typeof ble.peripheralId === "string") && (ble.name === undefined || typeof ble.name === "string") && (ble.lastSeenAt === undefined || typeof ble.lastSeenAt === "number") ); } function validReportedEndpoints( value: unknown, ): value is DeviceReportedEndpoints { if (typeof value !== "object" || value === null) return false; const reported = value as Partial; return ( Array.isArray(reported.addresses) && reported.addresses.every( (address) => typeof address === "string" && isValidHost(address), ) && typeof reported.port === "number" && Number.isInteger(reported.port) && reported.port > 0 && reported.port <= 65535 && typeof reported.at === "number" ); } function validRecord(key: string, value: unknown): value is DeviceRecord { if (typeof value !== "object" || value === null) return false; const record = value as Partial; if (record.ble !== undefined && !validBluetoothIdentity(record.ble)) { return false; } if ( record.reportedEndpoints !== undefined && !validReportedEndpoints(record.reportedEndpoints) ) { return false; } const bluetoothOnly = Array.isArray(record.endpoints) && record.endpoints.length === 0 && record.ble !== undefined; return ( record.recordId === key && Array.isArray(record.endpoints) && (record.endpoints.length > 0 || bluetoothOnly) && record.endpoints.every(validEndpoint) && typeof record.preferredEndpointId === "string" && (bluetoothOnly || record.endpoints.some( (endpoint) => endpoint.endpointId === record.preferredEndpointId, )) && (record.legacyCredentialKey === undefined || typeof record.legacyCredentialKey === "string") ); } /** * Returns null only when the stored blob is structurally unusable. Individual * records that no longer validate are dropped so one bad record cannot cost the * user every other device. */ export function parseDeviceRegistry(value: unknown): DeviceRegistryV2 | null { if (typeof value !== "object" || value === null) return null; const registry = value as Partial; if ( registry.schemaVersion !== SCHEMA_VERSION || (registry.activeRecordId !== null && typeof registry.activeRecordId !== "string") || typeof registry.records !== "object" || registry.records === null ) { return null; } const records: Record = {}; const dropped: string[] = []; for (const [key, record] of Object.entries(registry.records)) { if (validRecord(key, record)) { records[key] = record; } else { dropped.push(key); } } if (dropped.length > 0) { logger.error( "Dropped unreadable device records", new Error(`Dropped ${dropped.length} device record(s)`), { category: "storage", action: "parseDeviceRegistry", severity: "warning", }, ); } const activeRecordId = registry.activeRecordId !== null && records[registry.activeRecordId] !== undefined ? registry.activeRecordId : null; return { schemaVersion: SCHEMA_VERSION, activeRecordId, records }; } function legacyHistoryEntries(value: string | null): LegacyHistoryEntry[] { if (!value) return []; try { const parsed: unknown = JSON.parse(value); if (!Array.isArray(parsed)) return []; return parsed.filter( (entry): entry is LegacyHistoryEntry => typeof entry === "object" && entry !== null && typeof (entry as LegacyHistoryEntry).address === "string", ); } catch { return []; } } function createRecord( endpoint: ParsedDeviceEndpoint, source: DeviceEndpointSource, meta: Partial = {}, legacyCredentialKey = normalizeDeviceKey(endpoint.address), ): DeviceRecord { return { recordId: uuidv4(), endpoints: [endpointFromParsed(endpoint, source)], preferredEndpointId: endpoint.endpointId, ...(legacyCredentialKey ? { legacyCredentialKey } : {}), ...(meta.name ? { name: meta.name } : {}), ...(meta.nameIsCustom !== undefined ? { nameIsCustom: meta.nameIsCustom } : {}), ...(meta.platform ? { platform: meta.platform } : {}), ...(meta.version ? { version: meta.version } : {}), ...(meta.lastConnectedAt !== undefined ? { lastConnectedAt: meta.lastConnectedAt } : {}), }; } /** * Build the V2 registry from the pre-V2 `deviceAddress` + `deviceHistory` keys. * * Runs exactly once per install: `hydrate` persists the result and deletes both * legacy keys, so nothing here is reachable on any later launch. Each history * entry becomes one record carrying the address-derived credential key it was * paired under, which is what lets the upgrade keep existing pairings. */ function importLegacyRegistry( legacyAddress: string | null, historyValue: string | null, ): DeviceRegistryV2 { const records: Record = {}; const endpointToRecord = new Map(); for (const entry of legacyHistoryEntries(historyValue)) { const parsed = parseDeviceEndpoint(entry.address); if (!parsed.ok) continue; const existingId = endpointToRecord.get(parsed.endpoint.endpointId); if (existingId) { const existing = records[existingId]; if (!existing) continue; // Duplicate addresses in the legacy list are a merge, not a second // device: later entries fill in metadata the first one lacked. records[existingId] = { ...existing, ...(entry.name ? { name: entry.name } : {}), ...(entry.nameIsCustom !== undefined ? { nameIsCustom: entry.nameIsCustom } : {}), ...(entry.platform ? { platform: entry.platform } : {}), ...(entry.version ? { version: entry.version } : {}), ...(entry.lastConnectedAt !== undefined ? { lastConnectedAt: entry.lastConnectedAt } : {}), }; continue; } // The credential key is derived from the address exactly as the pre-V2 code // derived it, so imported keys match what is actually in secure storage. const record = createRecord( parsed.endpoint, "manual", entry, normalizeDeviceKey(entry.address), ); records[record.recordId] = record; endpointToRecord.set(parsed.endpoint.endpointId, record.recordId); } let activeRecordId: string | null = null; const parsedActive = parseDeviceEndpoint(legacyAddress ?? ""); if (parsedActive.ok) { activeRecordId = endpointToRecord.get(parsedActive.endpoint.endpointId) ?? null; if (!activeRecordId) { // Connected to a device that was never written to history. const record = createRecord( parsedActive.endpoint, "manual", {}, normalizeDeviceKey(legacyAddress ?? ""), ); records[record.recordId] = record; activeRecordId = record.recordId; } } return { schemaVersion: SCHEMA_VERSION, activeRecordId, records }; } /** * The pre-V2 active address wrote through to raw localStorage as well as to * Preferences, so read both before concluding there was no active device. */ function legacyLocalAddress(): string | null { try { return globalThis.localStorage?.getItem(LEGACY_ADDRESS_KEY) ?? null; } catch { return null; } } /** * The address a browser session should adopt when it has no stored devices. * * The web build is served *by* Core, so the page origin is the device. Seeding * it as a real record at hydrate — rather than falling back to the hostname at * every read site — is what lets everything downstream assume a record exists. */ function webFallbackRegistry(): DeviceRegistryV2 | null { if (Capacitor.isNativePlatform()) return null; const parsed = parseDeviceEndpoint(globalThis.location?.hostname ?? ""); if (!parsed.ok) return null; const record = createRecord(parsed.endpoint, "manual"); return { schemaVersion: SCHEMA_VERSION, activeRecordId: record.recordId, records: { [record.recordId]: record }, }; } class DeviceRegistryRepository { private snapshot = emptySnapshot(); private readonly listeners = new Set<() => void>(); private hydrationPromise: Promise | null = null; private writeChain: Promise = Promise.resolve(); private commitChain: Promise = Promise.resolve(); private pendingCommits = 0; getSnapshot = (): DeviceRegistrySnapshot => this.snapshot; subscribe = (listener: () => void): (() => void) => { this.listeners.add(listener); return () => this.listeners.delete(listener); }; private publish(next: DeviceRegistrySnapshot): void { this.snapshot = next; this.listeners.forEach((listener) => listener()); } private persist(registry: DeviceRegistryV2): Promise { const serialized = JSON.stringify(registry); const write = async () => { await Preferences.set({ key: DEVICE_REGISTRY_KEY, value: serialized }); }; const next = this.writeChain.then(write, write); this.writeChain = next.catch((error) => { logger.error("Failed to persist device registry", error, { category: "storage", action: "persistDeviceRegistry", severity: "error", }); }); return next; } /** * Drop the pre-V2 keys once their contents are safely in the registry blob. * This is what makes the legacy read genuinely one-shot — while these survive, * a registry that ever had to be rebuilt would re-import addresses the user * has since deleted. * * Never throws: the import already succeeded by this point, and failing to * tidy up is not a reason to declare hydration failed. */ private async clearLegacyState(): Promise { try { globalThis.localStorage?.removeItem(LEGACY_ADDRESS_KEY); globalThis.localStorage?.removeItem(LEGACY_HISTORY_KEY); } catch { // Storage access can be unavailable in private browser contexts. } try { await Promise.all([ Preferences.remove({ key: LEGACY_ADDRESS_KEY }), Preferences.remove({ key: LEGACY_HISTORY_KEY }), ]); } catch (error) { logger.error("Failed to clear legacy device keys", error, { category: "storage", action: "clearLegacyDeviceState", severity: "warning", }); } } private applyCommit( update: (registry: DeviceRegistryV2) => DeviceRegistryV2 | null, ): Promise { const execute = async () => { if (!this.snapshot.hydrated) { const error = new Error( "Device registry was never read successfully; refusing to overwrite stored devices", ); logger.error("Refused device registry write before hydration", error, { category: "storage", action: "commitDeviceRegistry", severity: "error", }); throw error; } const previous = this.snapshot; const next = update({ schemaVersion: SCHEMA_VERSION, activeRecordId: previous.activeRecordId, records: previous.records, }); if (next === null) return; const published: DeviceRegistrySnapshot = { ...next, hydrated: true, hydrationError: null, }; this.publish(published); try { await this.persist(next); } catch (error) { this.publish(previous); throw error; } }; return execute(); } private enqueueMutation(operation: () => Promise): Promise { // Start the first mutation synchronously, but do not let a newer mutation // observe or publish state until its predecessor settles. Credential // ownership decisions use the same queue as durable registry writes. const startsImmediately = this.pendingCommits === 0; this.pendingCommits++; const result = startsImmediately ? operation() : this.commitChain.then(operation, operation); this.commitChain = result.then( () => { this.pendingCommits--; }, () => { this.pendingCommits--; }, ); return result; } private commit( update: (registry: DeviceRegistryV2) => DeviceRegistryV2 | null, ): Promise { return this.enqueueMutation(() => this.applyCommit(update)); } hydrate(): Promise { if (this.snapshot.hydrated) return Promise.resolve(); if (this.hydrationPromise) return this.hydrationPromise; this.hydrationPromise = (async () => { try { const [registryValue, legacyAddress, legacyHistory] = await Promise.all( [ Preferences.get({ key: DEVICE_REGISTRY_KEY }), Preferences.get({ key: LEGACY_ADDRESS_KEY }), Preferences.get({ key: LEGACY_HISTORY_KEY }), ], ); let registry: DeviceRegistryV2 | null = null; if (registryValue.value) { try { registry = parseDeviceRegistry(JSON.parse(registryValue.value)); } catch { registry = null; } if (!registry) { // A stored blob we cannot read is not the same as a first run. // Re-importing legacy state here would overwrite whatever is // actually on disk, so surface it and leave the blob untouched. logger.error( "Stored device registry is unreadable", new Error("Unreadable device registry"), { category: "storage", action: "hydrateDeviceRegistry", severity: "error", }, ); this.publish({ ...emptySnapshot(), hydrated: false, hydrationError: "registry_unreadable", }); return; } } if (!registry) { const imported = importLegacyRegistry( legacyAddress.value ?? legacyLocalAddress(), legacyHistory.value, ); registry = Object.keys(imported.records).length > 0 ? imported : (webFallbackRegistry() ?? imported); await this.persist(registry); } if ( legacyAddress.value !== null || legacyHistory.value !== null || legacyLocalAddress() !== null ) { await this.clearLegacyState(); } this.publish({ ...registry, hydrated: true, hydrationError: null }); } catch (error) { logger.error("Failed to hydrate device registry", error, { category: "storage", action: "hydrateDeviceRegistry", severity: "error", }); // Stay unhydrated so the next mutator retries the read. Marking a // failed read as hydrated would let commit() persist an empty registry // over the stored one. this.publish({ ...emptySnapshot(), hydrated: false, hydrationError: "hydrate_failed", }); } })().finally(() => { this.hydrationPromise = null; }); return this.hydrationPromise; } activeRecord(): DeviceRecord | null { return this.snapshot.activeRecordId ? (this.snapshot.records[this.snapshot.activeRecordId] ?? null) : null; } activeEndpoint(): ParsedDeviceEndpoint | null { return parsedEndpointForRecord(this.activeRecord()); } /** Make the record at `address` active, creating it if it is new. */ async selectAddress(address: string): Promise { await this.hydrate(); const parsed = parseDeviceEndpoint(address); if (!parsed.ok) return null; let selected: DeviceRecord | null = null; await this.commit((registry) => { const existing = Object.values(registry.records).find((record) => record.endpoints.some( (endpoint) => endpoint.endpointId === parsed.endpoint.endpointId, ), ); const record = existing ?? createRecord( parsed.endpoint, "manual", {}, // Keyed off the address the user actually typed, not the canonical // form, so a pairing stored by an older build is still found. normalizeDeviceKey(address), ); selected = record; if (existing && registry.activeRecordId === record.recordId) return null; return { ...registry, activeRecordId: record.recordId, records: existing ? registry.records : { ...registry.records, [record.recordId]: record }, }; }); return selected; } /** Make the record for an mDNS announcement active, creating it if it is new. */ async selectDiscovered( device: DiscoveredDeviceRegistration, ): Promise { await this.hydrate(); const hostname = device.hostname?.replace(/\.+$/, "").toLowerCase(); const connectionHost = hostname || device.addresses[0]; if (!connectionHost) return null; const parsed = parseDeviceEndpoint( `${connectionHost.includes(":") ? `[${connectionHost}]` : connectionHost}:${device.port}`, ); if (!parsed.ok) return null; const discoveryId = normalizeDiscoveryId(device.discoveryId); const resolvedAddresses = unique(device.addresses); let selected: DeviceRecord | null = null; await this.commit((registry) => { // A stable service id wins. Without one, only the exact advertised // hostname can reuse a record; an IP is never identity because DHCP can // hand it to another device. const records = Object.values(registry.records); const byDiscoveryId = discoveryId ? records.find((record) => record.discoveryId === discoveryId) : undefined; const byExactHostname = hostname ? records.find( (record) => (!discoveryId || !record.discoveryId || normalizeDiscoveryId(record.discoveryId) === discoveryId) && record.endpoints.some( (endpoint) => endpoint.endpointId === parsed.endpoint.endpointId, ), ) : undefined; const existing = byDiscoveryId ?? byExactHostname; const effectiveDiscoveryId = discoveryId ?? existing?.discoveryId; const existingEndpoint = existing?.endpoints.find( (endpoint) => endpoint.endpointId === parsed.endpoint.endpointId, ); const unchanged = existing !== undefined && existing.discoveryId === effectiveDiscoveryId && existing.preferredEndpointId === parsed.endpoint.endpointId && existingEndpoint?.source === "mdns" && sameAddressSet( existingEndpoint.resolvedAddresses ?? [], resolvedAddresses, ) && (!device.name || existing.nameIsCustom === true || existing.name === device.name) && (!device.platform || existing.platform === device.platform) && (!device.version || existing.version === device.version); if (unchanged) { selected = existing; return registry.activeRecordId === existing.recordId ? null : { ...registry, activeRecordId: existing.recordId }; } const discoveredEndpoint = endpointFromParsed(parsed.endpoint, "mdns", { lastSeenAt: Date.now(), resolvedAddresses, }); const base = existing ?? // Before the registry, picking a device from a scan saved it by IP even // when it advertised a hostname. A new record connects by hostname, so // the advertised address is where any existing pairing still lives. createRecord( parsed.endpoint, "mdns", {}, device.addresses[0] ? normalizeDeviceKey(`${device.addresses[0]}:${device.port}`) : normalizeDeviceKey(parsed.endpoint.address), ); const record: DeviceRecord = { ...base, ...(discoveryId ? { discoveryId } : {}), endpoints: [ ...base.endpoints.filter( (endpoint) => endpoint.endpointId !== discoveredEndpoint.endpointId, ), discoveredEndpoint, ], preferredEndpointId: discoveredEndpoint.endpointId, ...(device.name && !base.nameIsCustom ? { name: device.name } : {}), ...(device.platform ? { platform: device.platform } : {}), ...(device.version ? { version: device.version } : {}), }; selected = record; return { ...registry, activeRecordId: record.recordId, records: { ...registry.records, [record.recordId]: record }, }; }); return selected; } /** * Record a successful connection, and absorb the duplicate record that a * proven credential key identifies. * * `provenLegacyKey` is only ever supplied after the peer has authenticated * with the credentials stored under it, which is the one unforgeable signal * that two records are the same physical device. Matching on a shared address * instead would be wrong: DHCP hands leases around, so the device answering at * an address today need not be the one that answered yesterday. * * `migrationSettled` is the caller's report that no pre-V2 key can still hold * this record's pairing — either it was promoted to the canonical key, or * there was never anything under it. Only then is the pointer dropped. */ async markConnected( recordId: string, options: { provenLegacyKey?: string; migrationSettled?: boolean } = {}, ): Promise { await this.hydrate(); await this.commit((registry) => { const target = registry.records[recordId]; if (!target) return null; const provenKey = options.provenLegacyKey; const absorbed = provenKey ? Object.values(registry.records).filter( (record) => record.recordId !== recordId && record.legacyCredentialKey === provenKey, ) : []; const endpoints = new Map( target.endpoints.map((endpoint) => [endpoint.endpointId, endpoint]), ); for (const source of absorbed) { for (const endpoint of source.endpoints) { if (!endpoints.has(endpoint.endpointId)) { endpoints.set(endpoint.endpointId, endpoint); } } } const donor = absorbed[0]; const merged: DeviceRecord = { ...target, endpoints: [...endpoints.values()], lastConnectedAt: Date.now(), name: target.name ?? donor?.name, nameIsCustom: target.nameIsCustom ?? donor?.nameIsCustom, platform: target.platform ?? donor?.platform, version: target.version ?? donor?.version, }; if (options.migrationSettled) { delete merged.legacyCredentialKey; } const records = { ...registry.records, [recordId]: merged }; for (const source of absorbed) delete records[source.recordId]; return { ...registry, activeRecordId: recordId, records }; }); } /** * Apply metadata the device reported about itself. Never touches a name the * user chose, and treats blank values as "no information" rather than as an * instruction to clear a good one. */ async applyDiscoveredMetadata( recordId: string, metadata: DiscoveredDeviceMetadata, ): Promise { await this.hydrate(); await this.commit((registry) => { const record = registry.records[recordId]; if (!record) return null; const next: DeviceRecord = { ...record, ...(metadata.name && !record.nameIsCustom ? { name: metadata.name } : {}), ...(metadata.platform ? { platform: metadata.platform } : {}), ...(metadata.version ? { version: metadata.version } : {}), }; if ( next.name === record.name && next.platform === record.platform && next.version === record.version ) { return null; } return { ...registry, records: { ...registry.records, [recordId]: next }, }; }); } /** * Record the addresses an mDNS advertisement resolved this record's preferred * endpoint to, so the socket can dial one instead of a `.local` hostname. * * Deliberately narrower than `selectDiscovered`: this only annotates the * record the caller names, where `selectDiscovered` matches an announcement * against the whole registry and may create a record or switch the active * one. A background browse running behind a live connection must never do * either of those things. */ async noteResolvedAddresses( recordId: string, addresses: readonly string[], ): Promise { await this.hydrate(); const resolved = unique(addresses.filter((address) => address.length > 0)); if (resolved.length === 0) return; await this.commit((registry) => { const record = registry.records[recordId]; const preferred = preferredEndpointFor(record); if ( !record || !preferred || sameAddressSet(preferred.resolvedAddresses ?? [], resolved) ) { // mDNS re-announces constantly; only a genuine change is worth a write. return null; } const next: DeviceRecord = { ...record, endpoints: record.endpoints.map((endpoint) => endpoint.endpointId === preferred.endpointId ? { ...endpoint, resolvedAddresses: resolved } : endpoint, ), }; return { ...registry, records: { ...registry.records, [recordId]: next }, }; }); } /** * Combine two records after the user confirms they name the same device. * Credential preparation happens first so a failed keychain write cannot * strand the surviving record without the source record's pairing. */ async mergeRecords( targetRecordId: string, sourceRecordId: string, options: { beforeCommit?: () => void; provenCredentials?: StoredCredentials; } = {}, ): Promise { await this.hydrate(); let target = this.snapshot.records[targetRecordId]; let source = this.snapshot.records[sourceRecordId]; if (!target || !source || targetRecordId === sourceRecordId) { throw new Error("Device records are unavailable for merge"); } if (discoveryIdsConflict(target, source)) { throw new Error("Devices with different discovery IDs cannot be merged"); } const legacyKeys = [ target.legacyCredentialKey, source.legacyCredentialKey, ].filter((key): key is string => key !== undefined); const credentialCleanupKeys = await credentialStore.prepareRecordMerge( targetRecordId, sourceRecordId, legacyKeys, options.provenCredentials, ); // Keychain access crosses an async boundary. Re-read before constructing // the commit so metadata or endpoint updates that landed meanwhile are not // overwritten by the older snapshot captured above. target = this.snapshot.records[targetRecordId]; source = this.snapshot.records[sourceRecordId]; if (!target || !source || discoveryIdsConflict(target, source)) { throw new Error("Device records changed while preparing the merge"); } const endpoints = new Map( target.endpoints.map((endpoint) => [endpoint.endpointId, endpoint]), ); for (const endpoint of source.endpoints) { const existing = endpoints.get(endpoint.endpointId); endpoints.set( endpoint.endpointId, existing ? mergeEndpoint(existing, endpoint) : endpoint, ); } const activeRecordIdAtMerge = this.snapshot.activeRecordId; const sourceWasActive = activeRecordIdAtMerge === sourceRecordId; const sourceIsNewer = (source.lastConnectedAt ?? 0) > (target.lastConnectedAt ?? 0); const newest = sourceIsNewer ? source : target; const oldest = sourceIsNewer ? target : source; const customNameOwner = target.nameIsCustom ? target : source.nameIsCustom ? source : null; const name = customNameOwner?.name ?? newest.name ?? oldest.name; const lastConnectedAt = Math.max( target.lastConnectedAt ?? 0, source.lastConnectedAt ?? 0, ); const merged: DeviceRecord = { ...target, ...((target.discoveryId ?? source.discoveryId) ? { discoveryId: target.discoveryId ?? source.discoveryId } : {}), endpoints: [...endpoints.values()], preferredEndpointId: preferredAfterMerge( sourceWasActive ? source : target, sourceWasActive ? target : source, ), ...((target.ble ?? source.ble) ? { ble: mergeBluetoothIdentity(target.ble, source.ble) } : {}), ...((newest.reportedEndpoints ?? oldest.reportedEndpoints) ? { reportedEndpoints: newest.reportedEndpoints ?? oldest.reportedEndpoints, } : {}), ...(name ? { name } : {}), nameIsCustom: customNameOwner !== null, ...((newest.platform ?? oldest.platform) ? { platform: newest.platform ?? oldest.platform } : {}), ...((newest.version ?? oldest.version) ? { version: newest.version ?? oldest.version } : {}), ...(lastConnectedAt > 0 ? { lastConnectedAt } : {}), }; delete merged.legacyCredentialKey; // Callers use this last synchronous boundary to destroy an active source // transport. Nothing awaited after it can fail before the merged snapshot // is published, so a preparation error never disconnects an intact record. options.beforeCommit?.(); await this.commit((registry) => { if ( registry.records[targetRecordId] !== target || registry.records[sourceRecordId] !== source || registry.activeRecordId !== activeRecordIdAtMerge ) { throw new Error("Device records changed while preparing the merge"); } const records = { ...registry.records, [targetRecordId]: merged }; delete records[sourceRecordId]; return { ...registry, activeRecordId: sourceWasActive ? targetRecordId : registry.activeRecordId, records, }; }); const referencedLegacyKeys = new Set( Object.values(this.snapshot.records) .map((record) => record.legacyCredentialKey) .filter((key): key is string => key !== undefined), ); const cleanupResults = await Promise.allSettled( credentialCleanupKeys .filter((key) => !referencedLegacyKeys.has(key)) .map((key) => credentialStore.delete(key)), ); for (const result of cleanupResults) { if (result.status === "rejected") { logger.error( "Failed to clean merged device credentials", result.reason, { category: "storage", action: "mergeDeviceCredentials", severity: "error", }, ); } } return merged; } /** * Select the Core the user picked from the nearby Bluetooth list. A record * that already knows this Core (by its device id) gains the Bluetooth * identity; otherwise a Bluetooth-only record is created. */ async selectBluetooth(identity: { deviceId: string; peripheralId: string; name?: string; }): Promise { await this.hydrate(); const deviceId = normalizeDiscoveryId(identity.deviceId); if (!deviceId) return null; let selected: DeviceRecord | null = null; await this.commit((registry) => { const now = Date.now(); const name = identity.name?.trim() || undefined; const existing = Object.values(registry.records).find( (record) => normalizeDiscoveryId(record.discoveryId) === deviceId || normalizeDiscoveryId(record.ble?.deviceId) === deviceId, ); const ble: DeviceBluetoothIdentity = { ...(existing?.ble ?? {}), deviceId: identity.deviceId.trim(), peripheralId: identity.peripheralId, ...(name ? { name } : {}), lastSeenAt: now, }; const record: DeviceRecord = existing ? { ...existing, ...(existing.discoveryId ? {} : { discoveryId: deviceId }), ble, } : { recordId: uuidv4(), discoveryId: deviceId, endpoints: [], preferredEndpointId: "", ble, ...(name ? { name } : {}), }; selected = record; return { ...registry, activeRecordId: record.recordId, records: { ...registry.records, [record.recordId]: record }, }; }); return selected; } /** Remember how Bluetooth last found this record's Core. */ async noteBluetoothIdentity( recordId: string, identity: { coreDeviceId: string; peripheralId: string }, ): Promise { await this.hydrate(); const deviceId = normalizeDiscoveryId(identity.coreDeviceId); if (!deviceId) return; await this.commit((registry) => { const record = registry.records[recordId]; if (!record) return null; // A record already tied to another Core never adopts this one. const known = normalizeDiscoveryId(record.discoveryId); if (known && known !== deviceId) return null; const ble: DeviceBluetoothIdentity = { ...(record.ble ?? {}), deviceId: identity.coreDeviceId.trim(), peripheralId: identity.peripheralId, lastSeenAt: Date.now(), }; if (known && sameBluetoothIdentity(record.ble, ble)) return null; return { ...registry, records: { ...registry.records, [recordId]: { ...record, discoveryId: known ?? deviceId, ble }, }, }; }); } /** * Store what Core reported about where it can be reached. A Core serving * Bluetooth becomes reachable over it as a fallback. */ async applyDeviceEndpoints( recordId: string, endpoints: { deviceId: string; name?: string; addresses: readonly string[]; port: number; ble: boolean; }, ): Promise { await this.hydrate(); const deviceId = normalizeDiscoveryId(endpoints.deviceId); if (!deviceId) return; await this.commit((registry) => { const record = registry.records[recordId]; if (!record) return null; const known = normalizeDiscoveryId(record.discoveryId); if (known && known !== deviceId) { logger.warn("Core reported a different device id than its record"); return null; } const addresses = unique( endpoints.addresses.filter((address) => isValidHost(address)), ); const reportedChanged = !record.reportedEndpoints || record.reportedEndpoints.port !== endpoints.port || !sameAddressSet(record.reportedEndpoints.addresses, addresses); const learnsBluetooth = endpoints.ble && normalizeDiscoveryId(record.ble?.deviceId) !== deviceId; const name = endpoints.name?.trim(); const learnsName = !!name && !record.nameIsCustom && record.name !== name; if (known && !reportedChanged && !learnsBluetooth && !learnsName) { return null; } const next: DeviceRecord = { ...record, discoveryId: known ?? deviceId, reportedEndpoints: reportedChanged ? { addresses, port: endpoints.port, at: Date.now() } : record.reportedEndpoints!, ...(learnsBluetooth ? { ble: { deviceId: endpoints.deviceId.trim() } } : {}), ...(learnsName ? { name } : {}), }; return { ...registry, records: { ...registry.records, [recordId]: next }, }; }); } /** Set or clear the user's own name for a record. Blank clears it. */ async setCustomName(recordId: string, name: string): Promise { await this.hydrate(); const trimmed = name.trim(); await this.commit((registry) => { const record = registry.records[recordId]; if (!record) return null; const next: DeviceRecord = { ...record }; if (trimmed) { next.name = trimmed; next.nameIsCustom = true; } else { delete next.name; next.nameIsCustom = false; } return { ...registry, records: { ...registry.records, [recordId]: next }, }; }); } /** * Forget a device, taking its stored pairing with it. * * Deleting the credentials here rather than at the call site is deliberate: * the registry is the only thing that knows whether a surviving record still * claims the same pre-V2 key, and a record the user did not ask to forget must * not be silently unpaired. */ async removeRecord(recordId: string): Promise { await this.hydrate(); if (!this.snapshot.records[recordId]) return null; // Delete the record-specific key first. Other registry mutations may land // during this native-storage await, so shared legacy ownership is checked // again only after entering the registry mutation queue below. try { await credentialStore.delete(credentialKeyForRecord(recordId)); } catch (error) { logger.error("Failed to delete forgotten device credentials", error, { category: "storage", action: "deleteDeviceCredentials", severity: "error", recordId, }); throw error; } return this.enqueueMutation(async () => { const removed = this.snapshot.records[recordId] ?? null; if (!removed) return null; const legacyKey = removed.legacyCredentialKey; const legacyKeyHasAnotherOwner = legacyKey !== undefined && Object.values(this.snapshot.records).some( (record) => record.recordId !== recordId && record.legacyCredentialKey === legacyKey, ); // Hold the registry mutation queue across the shared-key decision and // deletion so no new claimant can appear between them. if (legacyKey && !legacyKeyHasAnotherOwner) { try { await credentialStore.delete(legacyKey); } catch (error) { logger.error("Failed to delete forgotten device credentials", error, { category: "storage", action: "deleteDeviceCredentials", severity: "error", recordId, }); throw error; } } // Secrets are gone before the durable registry record. Secure-storage // failure leaves the record as a retry path; registry failure leaves a // visible record that can be paired again rather than an orphan secret. await this.applyCommit((registry) => { const records = { ...registry.records }; delete records[recordId]; return { ...registry, activeRecordId: registry.activeRecordId === recordId ? null : registry.activeRecordId, records, }; }); return removed; }); } async setActiveRecord(recordId: string | null): Promise { await this.hydrate(); await this.commit((registry) => { if (recordId !== null && !registry.records[recordId]) return null; if (registry.activeRecordId === recordId) return null; return { ...registry, activeRecordId: recordId }; }); } resetForTests(): void { this.snapshot = emptySnapshot(); this.hydrationPromise = null; this.writeChain = Promise.resolve(); this.commitChain = Promise.resolve(); this.pendingCommits = 0; this.listeners.clear(); } /** * Test-only: adopt a registry state as though storage had just been read. * * Listeners survive, so a test can install a different set of devices while * components are mounted and they will re-render exactly as they would after a * real write. */ installForTests(registry: DeviceRegistryV2): void { this.hydrationPromise = null; this.publish({ ...registry, hydrated: true, hydrationError: null }); } } export const deviceRegistry = new DeviceRegistryRepository(); /** * Subscribe to a slice of the registry. * * The selector runs *inside* the snapshot getter rather than on its result. * `publish` allocates a fresh snapshot on every commit, so selecting afterwards * gives useSyncExternalStore nothing to compare but snapshot identity — every * registry write would re-render every consumer, and `ConnectionProvider` holds * several subscriptions at the root of the tree. Selecting first lets React bail * out when the slice is unchanged, which is what a metadata-only write produces * for almost every consumer. * * The per-snapshot cache is not an optimization: React calls the getter more * than once per render and requires a stable result, so a selector that builds a * new value would otherwise never settle. It is held in a ref rather than a memo * closure because `react-hooks/immutability` forbids reassigning a closure * variable after render. */ export function useDeviceRegistry( selector: (snapshot: DeviceRegistrySnapshot) => T, ): T { const cache = useRef<{ snapshot: DeviceRegistrySnapshot; selector: (snapshot: DeviceRegistrySnapshot) => T; value: T; } | null>(null); const getSelection = useCallback((): T => { const snapshot = deviceRegistry.getSnapshot(); const cached = cache.current; if ( cached && cached.snapshot === snapshot && cached.selector === selector ) { return cached.value; } const value = selector(snapshot); cache.current = { snapshot, selector, value }; return value; }, [selector]); return useSyncExternalStore( deviceRegistry.subscribe, getSelection, getSelection, ); } export function __resetDeviceRegistryForTests(): void { deviceRegistry.resetForTests(); }