/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Bytes } from "@matter/general"; import { type BasicTlvEntry, BasicTlv } from "./BasicTlvCodec.js"; import { ThreadDatasetError } from "./errors.js"; import { MeshCopTlvType } from "./meshcopTlvTypes.js"; import { SecurityPolicy } from "./SecurityPolicy.js"; export { ThreadDatasetError } from "./errors.js"; /** * Decoded Thread Operational Dataset. * * Each named accessor mirrors a MeshCoP TLV defined in {@link MeshCopTlvType}. * Unknown TLVs survive a decode/encode round-trip via {@link unknownTlvs}. * * Datasets returned by {@link OperationalDataset.decode} also carry hidden * replay state so {@link OperationalDataset.encode} can reproduce the source * bytes verbatim when no field has been mutated — preserving non-canonical * encodings (legacy 1-byte CHANNEL forms, vendor-specific orderings) emitted * by real Border Routers. */ export interface OperationalDataset { channel?: number; panId?: number; extPanId?: Bytes; networkName?: string; pskc?: Bytes; networkKey?: Bytes; meshLocalPrefix?: Bytes; securityPolicy?: SecurityPolicy; activeTimestamp?: Bytes; pendingTimestamp?: Bytes; delayTimer?: number; channelMask?: Bytes; unknownTlvs: Array<{ type: number; value: Bytes }>; raw: Bytes; } export namespace OperationalDataset { /** * Decodes a Thread Operational Dataset from either raw bytes or a hex string. * * Accepts a whitespace-tolerant hex string (whitespace is stripped before * parsing) or pre-parsed `Bytes` (e.g. a `Uint8Array`) of MeshCoP TLV bytes. Unknown TLVs survive the * round-trip via {@link OperationalDataset.unknownTlvs}. Throws on malformed * input (bad hex or TLV structure violations). */ export function decode(input: Bytes | string): OperationalDataset { const blob = typeof input === "string" ? Bytes.of(Bytes.fromHex(input.replace(/\s+/g, ""))) : Bytes.of(input); const entries = BasicTlv.walk(blob); const unknownTlvs = new Array<{ type: number; value: Bytes }>(); const originalTlvs = entries.map(e => ({ type: e.type, value: Bytes.of(e.value).slice() })); const ds: OperationalDataset = { unknownTlvs, raw: blob.slice(), }; ORIGINAL_TLVS.set(ds, originalTlvs); for (const entry of entries) { applyKnownTlvToDataset(ds, entry, unknownTlvs); } return ds; } /** * Encode a Thread Operational Dataset to MeshCoP TLV bytes. * * Datasets produced by {@link decode} are re-encoded with replay fidelity: * unmodified known TLVs reproduce their original bytes (preserving non-canonical * encodings from real Border Routers), while mutated fields are re-encoded * canonically. Datasets constructed directly (without a prior `decode`) are * always encoded in canonical form. * * @param ds - Dataset to encode; may be a decoded or manually constructed object. * @returns MeshCoP TLV byte sequence. */ export function encode(ds: OperationalDataset): Bytes { const originals = ORIGINAL_TLVS.get(ds); if (originals !== undefined) { return encodeWithReplay(ds, originals); } return Bytes.of(BasicTlv.encode(canonicalEntries(ds))); } /** * Return a copy of the dataset with `pskc` and `networkKey` cleared. * * Safe to log or expose via the public API — secret material is removed * while all other fields (channel, network name, timestamps, etc.) are retained. * * @param ds - Source dataset; not mutated. * @returns Shallow copy with secret fields set to `undefined`. */ export function redact(ds: OperationalDataset): OperationalDataset { return { ...ds, pskc: undefined, networkKey: undefined }; } } /** * Replay state for {@link OperationalDataset.encode}. Held off-interface so the * public type stays a plain dataset shape; the entry is reclaimed automatically * when the dataset is garbage-collected. */ const ORIGINAL_TLVS = new WeakMap>(); function applyKnownTlvToDataset( ds: OperationalDataset, entry: BasicTlvEntry, unknownTlvs: Array<{ type: number; value: Bytes }>, ): void { const value = Bytes.of(entry.value); switch (entry.type) { case MeshCopTlvType.CHANNEL: ds.channel = decodeChannel(value); break; case MeshCopTlvType.PANID: if (value.length !== 2) { throw new ThreadDatasetError(`PANID TLV must be 2 bytes, got ${value.length}`); } ds.panId = (value[0] << 8) | value[1]; break; case MeshCopTlvType.EXTPANID: if (value.length !== 8) { throw new ThreadDatasetError(`EXTPANID TLV must be 8 bytes, got ${value.length}`); } ds.extPanId = value.slice(); break; case MeshCopTlvType.NETWORK_NAME: ds.networkName = new TextDecoder("utf-8").decode(value); break; case MeshCopTlvType.PSKC: ds.pskc = value.slice(); break; case MeshCopTlvType.NETWORK_KEY: if (value.length !== 16) { throw new ThreadDatasetError(`NETWORK_KEY TLV must be 16 bytes, got ${value.length}`); } ds.networkKey = value.slice(); break; case MeshCopTlvType.MESH_LOCAL_PREFIX: if (value.length !== 8) { throw new ThreadDatasetError(`MESH_LOCAL_PREFIX TLV must be 8 bytes, got ${value.length}`); } ds.meshLocalPrefix = value.slice(); break; case MeshCopTlvType.SECURITY_POLICY: ds.securityPolicy = SecurityPolicy.decode(value); break; case MeshCopTlvType.ACTIVE_TIMESTAMP: if (value.length !== 8) { throw new ThreadDatasetError(`ACTIVE_TIMESTAMP TLV must be 8 bytes, got ${value.length}`); } ds.activeTimestamp = value.slice(); break; case MeshCopTlvType.PENDING_TIMESTAMP: if (value.length !== 8) { throw new ThreadDatasetError(`PENDING_TIMESTAMP TLV must be 8 bytes, got ${value.length}`); } ds.pendingTimestamp = value.slice(); break; case MeshCopTlvType.DELAY_TIMER: if (value.length !== 4) { throw new ThreadDatasetError(`DELAY_TIMER TLV must be 4 bytes, got ${value.length}`); } ds.delayTimer = (value[0] << 24) | (value[1] << 16) | (value[2] << 8) | value[3]; break; case MeshCopTlvType.CHANNEL_MASK: ds.channelMask = value.slice(); break; default: unknownTlvs.push({ type: entry.type, value: value.slice() }); break; } } function encodeWithReplay(ds: OperationalDataset, originals: ReadonlyArray): Bytes { const seenKnownTypes = new Set(); const unknownCursor = new Map(); const out = new Array(); const scratch: OperationalDataset = { unknownTlvs: [], raw: EMPTY_BYTES }; for (const original of originals) { const known = KNOWN_TLV_HANDLERS.get(original.type); if (known !== undefined) { seenKnownTypes.add(original.type); const canonical = known.encodeCurrent(ds); if (canonical === undefined) continue; // Compare named values rather than bytes so non-canonical encodings (e.g. the // legacy 1-byte CHANNEL form) replay unchanged when the caller hasn't mutated. applyKnownTlvToDataset(scratch, original, scratch.unknownTlvs); if (known.equalsCurrent(ds, scratch)) { out.push({ type: original.type, value: original.value }); } else { out.push({ type: original.type, value: canonical }); } continue; } const start = unknownCursor.get(original.type) ?? 0; const matchIdx = ds.unknownTlvs.findIndex( (u, i) => i >= start && u.type === original.type && Bytes.areEqual(u.value, original.value), ); if (matchIdx === -1) continue; unknownCursor.set(original.type, matchIdx + 1); out.push({ type: original.type, value: original.value }); } for (const known of KNOWN_TLV_HANDLERS.values()) { if (seenKnownTypes.has(known.type)) continue; const canonical = known.encodeCurrent(ds); if (canonical === undefined) continue; out.push({ type: known.type, value: canonical }); } return Bytes.of(BasicTlv.encode(out)); } const EMPTY_BYTES = new Uint8Array(); function canonicalEntries(ds: OperationalDataset): BasicTlvEntry[] { const out = new Array(); for (const known of KNOWN_TLV_HANDLERS.values()) { const canonical = known.encodeCurrent(ds); if (canonical === undefined) continue; out.push({ type: known.type, value: canonical }); } for (const u of ds.unknownTlvs) { out.push({ type: u.type, value: Bytes.of(u.value).slice() }); } return out; } /** * Each handler erases its field type behind a closure so the heterogeneous * registry can live in a single Map without per-field casts at the call site. */ interface KnownTlvHandler { type: number; /** Returns the canonical encoding of the named accessor, or undefined when unset. */ encodeCurrent(ds: OperationalDataset): Bytes | undefined; /** Whether ds[field] structurally equals other[field]. Used for replay decisions. */ equalsCurrent(ds: OperationalDataset, other: OperationalDataset): boolean; } function handler( type: number, field: K, encodeValue: (value: OperationalDataset[K] & {}) => Bytes, equals: (a: OperationalDataset[K] & {}, b: OperationalDataset[K] & {}) => boolean, ): KnownTlvHandler { return { type, encodeCurrent(ds) { const value = ds[field]; if (value === undefined) return undefined; return encodeValue(value); }, equalsCurrent(ds, other) { const a = ds[field]; const b = other[field]; if (a === undefined || b === undefined) return a === b; return equals(a, b); }, }; } const eqNumber = (a: number, b: number): boolean => a === b; const eqString = (a: string, b: string): boolean => a === b; const eqBytes = (a: Bytes, b: Bytes): boolean => Bytes.areEqual(a, b); const eqSecurityPolicy = (a: SecurityPolicy, b: SecurityPolicy): boolean => a.rotationTime === b.rotationTime && a.flags === b.flags; const KNOWN_TLV_HANDLERS: Map = (() => { const list: KnownTlvHandler[] = [ handler( MeshCopTlvType.CHANNEL, "channel", value => new Uint8Array([0x00, (value >> 8) & 0xff, value & 0xff]), eqNumber, ), handler(MeshCopTlvType.PANID, "panId", value => new Uint8Array([(value >> 8) & 0xff, value & 0xff]), eqNumber), handler(MeshCopTlvType.EXTPANID, "extPanId", value => value, eqBytes), handler(MeshCopTlvType.NETWORK_NAME, "networkName", value => new TextEncoder().encode(value), eqString), handler(MeshCopTlvType.PSKC, "pskc", value => value, eqBytes), handler(MeshCopTlvType.NETWORK_KEY, "networkKey", value => value, eqBytes), handler(MeshCopTlvType.MESH_LOCAL_PREFIX, "meshLocalPrefix", value => value, eqBytes), handler( MeshCopTlvType.SECURITY_POLICY, "securityPolicy", value => SecurityPolicy.encode(value), eqSecurityPolicy, ), handler(MeshCopTlvType.ACTIVE_TIMESTAMP, "activeTimestamp", value => value, eqBytes), handler(MeshCopTlvType.PENDING_TIMESTAMP, "pendingTimestamp", value => value, eqBytes), handler( MeshCopTlvType.DELAY_TIMER, "delayTimer", value => new Uint8Array([(value >> 24) & 0xff, (value >> 16) & 0xff, (value >> 8) & 0xff, value & 0xff]), eqNumber, ), handler(MeshCopTlvType.CHANNEL_MASK, "channelMask", value => value, eqBytes), ]; list.sort((a, b) => a.type - b.type); const map = new Map(); for (const h of list) map.set(h.type, h); return map; })(); /** * Real-world OpenThread datasets sometimes encode CHANNEL as a single byte * (the channel number directly) instead of the spec-conformant 3-byte form * (channel-page:1 + channel:2). Both forms are accepted on decode. */ function decodeChannel(value: Uint8Array): number { if (value.length === 1) { return value[0]; } if (value.length === 3) { return (value[1] << 8) | value[2]; } throw new ThreadDatasetError(`CHANNEL TLV must be 1 or 3 bytes, got ${value.length}`); }