/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Crypto, ImplementationError, Observable } from "@matter/general"; /** * Counter advance applied on every boot. Bounds the crash window: a value can only be reused (reusing its AES-CCM * nonce) if more than this many increments are lost unpersisted at crash. Must exceed the most Check-Ins one wake pass * can send — at most (fabrics × Permanent clients per fabric) — which stays far below this. The spec example uses 1000. * * @see {@link MatterSpecification.v161.Core} § 4.6.3 */ const BOOT_BUMP = 1000; /** * Runtime ICD check-in counter (ICDCounter attribute, quality C N). * * The owner constructs this from the persisted attribute value, persists {@link value} once, then persists every * {@link changed} emission. The persisted value is advanced by {@link BOOT_BUMP} on construction so a crash cannot * resume below an already-sent counter value (which would reuse its nonce) unless more than {@link BOOT_BUMP} * increments were lost unpersisted. * * uint32 wrap-around is harmless: clients apply mod-2³² offset arithmetic and refresh their keys before the offset * reaches 2³¹. * * @see {@link MatterSpecification.v161.Core} § 9.16.6.5 (ICDCounter attribute) * @see {@link MatterSpecification.v161.Core} § 4.6.3 (Check-In Counter — boot-bump persistence strategy) */ export class IcdCounter { #value: number; /** Emits the new counter value after every {@link increment} and {@link advance}. */ readonly changed = Observable<[value: number]>(); /** * Random initial counter value for a factory-reset device: a 28-bit DRBG value plus one (range 1 … 2²⁸). * Randomizing the start widens the counter space traversed before key refresh and avoids cross-device counter * correlation, since the counter is bound into the Check-In AES-CCM nonce together with the ICD key. * * @see {@link MatterSpecification.v161.Core} § 4.6.1.1 (Message Counter Initialization) * @see {@link MatterSpecification.v161.Core} § 4.6.3 (Check-In Counter — randomize on factory reset) */ static randomInitialValue(crypto: Crypto): number { return (crypto.randomUint32 >>> 4) + 1; } constructor(persistedValue: number) { this.#value = (persistedValue + BOOT_BUMP) >>> 0; } /** Current counter value. */ get value(): number { return this.#value; } /** * Advances the counter by one (uint32 wrap-around) and emits {@link changed}. * * @returns the new counter value. */ increment(): number { return this.advance(1); } /** * Advances the counter by `by` (uint32 wrap-around) and emits {@link changed}. * * For test event triggers that invalidate counter values only, as CHIP's `InvalidateHalfCheckInCounterValues` * and `InvalidateAllCheckInCounterValues` do: a large advance deliberately lets a counter value recur, which the * boot bump otherwise prevents. * * @returns the new counter value. */ advance(by: number): number { if (!Number.isInteger(by) || by < 0 || by > 0xffffffff) { throw new ImplementationError(`An ICD counter advances by an integer from 0 to 0xffffffff, not ${by}`); } this.#value = (this.#value + by) >>> 0; this.changed.emit(this.#value); return this.#value; } }