@matter/protocol 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/session/InsecureSession.ts

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger, MatterFlowError } from "#general";
+import { NodeId } from "#types";
+import { DecodedMessage, DecodedPacket, Message, MessageCodec, Packet } from "../codec/MessageCodec.js";
+import { Fabric } from "../fabric/Fabric.js";
+import { MessageCounter } from "../protocol/MessageCounter.js";
+import { MessageReceptionStateUnencryptedWithRollover } from "../protocol/MessageReceptionState.js";
+import { NoAssociatedFabricError } from "./SecureSession.js";
+import { Session, SessionParameterOptions } from "./Session.js";
+import { SessionManager, UNICAST_UNSECURE_SESSION_ID } from "./SessionManager.js";
+
+const logger = Logger.get("InsecureSession");
+
+export class InsecureSession extends Session {
+    readonly #initiatorNodeId: NodeId;
+    readonly closingAfterExchangeFinished = false;
+    readonly supportsMRP = true;
+
+    constructor(args: {
+        manager?: SessionManager;
+        messageCounter: MessageCounter;
+        initiatorNodeId?: NodeId;
+        sessionParameters?: SessionParameterOptions;
+        isInitiator?: boolean;
+    }) {
+        const { initiatorNodeId, isInitiator } = args;
+        super({
+            ...args,
+            setActiveTimestamp: !isInitiator, // When we are the initiator we assume the node is in idle mode
+            messageReceptionState: new MessageReceptionStateUnencryptedWithRollover(),
+        });
+        this.#initiatorNodeId = initiatorNodeId ?? NodeId.randomOperationalNodeId();
+    }
+
+    get isSecure() {
+        return false;
+    }
+
+    get isPase() {
+        return false;
+    }
+
+    decode(packet: DecodedPacket): DecodedMessage {
+        return MessageCodec.decodePayload(packet);
+    }
+
+    encode(message: Message): Packet {
+        return MessageCodec.encodePayload(message);
+    }
+
+    get attestationChallengeKey(): Uint8Array {
+        throw new MatterFlowError("Not supported on an unsecure session");
+    }
+
+    setFabric(_fabric: Fabric): void {
+        throw new MatterFlowError("Not supported on an unsecure session");
+    }
+
+    get name() {
+        return `insecure/${this.#initiatorNodeId}`;
+    }
+
+    get id(): number {
+        return UNICAST_UNSECURE_SESSION_ID;
+    }
+
+    get peerSessionId(): number {
+        return UNICAST_UNSECURE_SESSION_ID;
+    }
+
+    get nodeId() {
+        return this.#initiatorNodeId;
+    }
+
+    get peerNodeId() {
+        return undefined;
+    }
+
+    get associatedFabric(): Fabric {
+        throw new NoAssociatedFabricError("Session needs to be a secure session");
+    }
+
+    async destroy() {
+        await this.end();
+    }
+
+    async end() {
+        logger.info(`End insecure session ${this.name}`);
+        this.manager?.insecureSessions.delete(this.nodeId);
+    }
+}

package/src/session/SecureSession.ts

@@ -0,0 +1,349 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    BasicSet,
+    Bytes,
+    CRYPTO_SYMMETRIC_KEY_LENGTH,
+    Crypto,
+    DataWriter,
+    Diagnostic,
+    Endian,
+    Logger,
+    MatterFlowError,
+} from "#general";
+import { Subscription } from "#interaction/Subscription.js";
+import { PeerAddress } from "#peer/PeerAddress.js";
+import { CaseAuthenticatedTag, FabricIndex, NodeId, StatusCode, StatusResponseError } from "#types";
+import { DecodedMessage, DecodedPacket, Message, MessageCodec, Packet } from "../codec/MessageCodec.js";
+import { Fabric } from "../fabric/Fabric.js";
+import { MessageCounter } from "../protocol/MessageCounter.js";
+import { MessageReceptionStateEncryptedWithoutRollover } from "../protocol/MessageReceptionState.js";
+import { Session, SessionParameterOptions } from "./Session.js";
+import { type SessionManager } from "./SessionManager.js";
+
+const logger = Logger.get("SecureSession");
+
+const SESSION_KEYS_INFO = Bytes.fromString("SessionKeys");
+const SESSION_RESUMPTION_KEYS_INFO = Bytes.fromString("SessionResumptionKeys");
+
+export class NoAssociatedFabricError extends StatusResponseError {
+    constructor(message: string) {
+        super(message, StatusCode.UnsupportedAccess);
+    }
+}
+
+export class SecureSession extends Session {
+    readonly #subscriptions = new BasicSet<Subscription>();
+    #closingAfterExchangeFinished = false;
+    #sendCloseMessageWhenClosing = true;
+    readonly #id: number;
+    #fabric: Fabric | undefined;
+    readonly #peerNodeId: NodeId;
+    readonly #peerSessionId: number;
+    readonly #decryptKey: Uint8Array;
+    readonly #encryptKey: Uint8Array;
+    readonly #attestationKey: Uint8Array;
+    #caseAuthenticatedTags: CaseAuthenticatedTag[];
+    #isClosing = false;
+    readonly supportsMRP = true;
+
+    static async create(args: {
+        manager?: SessionManager;
+        id: number;
+        fabric: Fabric | undefined;
+        peerNodeId: NodeId;
+        peerSessionId: number;
+        sharedSecret: Uint8Array;
+        salt: Uint8Array;
+        isInitiator: boolean;
+        isResumption: boolean;
+        peerSessionParameters?: SessionParameterOptions;
+        caseAuthenticatedTags?: CaseAuthenticatedTag[];
+    }) {
+        const {
+            manager,
+            id,
+            fabric,
+            peerNodeId,
+            peerSessionId,
+            sharedSecret,
+            salt,
+            isInitiator,
+            isResumption,
+            peerSessionParameters,
+            caseAuthenticatedTags,
+        } = args;
+        const keys = await Crypto.hkdf(
+            sharedSecret,
+            salt,
+            isResumption ? SESSION_RESUMPTION_KEYS_INFO : SESSION_KEYS_INFO,
+            CRYPTO_SYMMETRIC_KEY_LENGTH * 3,
+        );
+        const decryptKey = isInitiator ? keys.slice(16, 32) : keys.slice(0, 16);
+        const encryptKey = isInitiator ? keys.slice(0, 16) : keys.slice(16, 32);
+        const attestationKey = keys.slice(32, 48);
+        return new SecureSession({
+            manager,
+            id,
+            fabric,
+            peerNodeId,
+            peerSessionId,
+            decryptKey,
+            encryptKey,
+            attestationKey,
+            sessionParameters: peerSessionParameters,
+            isInitiator,
+            caseAuthenticatedTags,
+        });
+    }
+
+    constructor(args: {
+        manager?: SessionManager;
+        id: number;
+        fabric: Fabric | undefined;
+        peerNodeId: NodeId;
+        peerSessionId: number;
+        decryptKey: Uint8Array;
+        encryptKey: Uint8Array;
+        attestationKey: Uint8Array;
+        sessionParameters?: SessionParameterOptions;
+        caseAuthenticatedTags?: CaseAuthenticatedTag[];
+        isInitiator: boolean;
+    }) {
+        super({
+            ...args,
+            setActiveTimestamp: true, // We always set the active timestamp for Secure sessions
+            // Can be changed to a PersistedMessageCounter if we implement session storage
+            messageCounter: new MessageCounter(() => {
+                // Secure Session Message Counter
+                // Expire/End the session before the counter rolls over
+                this.end(true, true).catch(error => logger.error(`Error while closing session: ${error}`));
+            }),
+            messageReceptionState: new MessageReceptionStateEncryptedWithoutRollover(),
+        });
+        const {
+            manager,
+            id,
+            fabric,
+            peerNodeId,
+            peerSessionId,
+            decryptKey,
+            encryptKey,
+            attestationKey,
+            caseAuthenticatedTags,
+        } = args;
+
+        this.#id = id;
+        this.#fabric = fabric;
+        this.#peerNodeId = peerNodeId;
+        this.#peerSessionId = peerSessionId;
+        this.#decryptKey = decryptKey;
+        this.#encryptKey = encryptKey;
+        this.#attestationKey = attestationKey;
+        this.#caseAuthenticatedTags = caseAuthenticatedTags ?? [];
+
+        manager?.sessions.add(this);
+        fabric?.addSession(this);
+
+        logger.debug(
+            `Created secure ${this.isPase ? "PASE" : "CASE"} session for fabric index ${fabric?.fabricIndex}`,
+            this.name,
+            Diagnostic.dict({
+                idleIntervalMs: this.idleIntervalMs,
+                activeIntervalMs: this.activeIntervalMs,
+                activeThresholdMs: this.activeThresholdMs,
+                dataModelRevision: this.dataModelRevision,
+                interactionModelRevision: this.interactionModelRevision,
+                specificationVersion: this.specificationVersion,
+                maxPathsPerInvoke: this.maxPathsPerInvoke,
+                caseAuthenticatedTags: this.#caseAuthenticatedTags,
+            }),
+        );
+    }
+
+    get caseAuthenticatedTags() {
+        return this.#caseAuthenticatedTags;
+    }
+
+    get closingAfterExchangeFinished() {
+        return this.#closingAfterExchangeFinished;
+    }
+
+    get sendCloseMessageWhenClosing() {
+        return this.#sendCloseMessageWhenClosing;
+    }
+
+    get isSecure(): boolean {
+        return true;
+    }
+
+    get isPase(): boolean {
+        return this.#peerNodeId === NodeId.UNSPECIFIED_NODE_ID;
+    }
+
+    get subscriptions() {
+        return this.#subscriptions;
+    }
+
+    get isClosing() {
+        return this.#isClosing;
+    }
+
+    async close(closeAfterExchangeFinished?: boolean) {
+        if (closeAfterExchangeFinished === undefined) {
+            closeAfterExchangeFinished = this.isPeerActive(); // We delay session close if the peer is actively communicating with us
+        }
+        await this.end(true, closeAfterExchangeFinished);
+    }
+
+    decode({ header, applicationPayload, messageExtension }: DecodedPacket, aad: Uint8Array): DecodedMessage {
+        if (header.hasMessageExtensions) {
+            logger.info(
+                `Message extensions are not supported. Ignoring ${messageExtension ? Bytes.toHex(messageExtension) : undefined}`,
+            );
+        }
+        const nonce = this.generateNonce(header.securityFlags, header.messageId, this.#peerNodeId);
+        const message = MessageCodec.decodePayload({
+            header,
+            applicationPayload: Crypto.decrypt(this.#decryptKey, applicationPayload, nonce, aad),
+        });
+
+        if (message.payloadHeader.hasSecuredExtension) {
+            logger.info(
+                `Secured extensions are not supported. Ignoring ${message.securityExtension ? Bytes.toHex(message.securityExtension) : undefined}`,
+            );
+        }
+
+        return message;
+    }
+
+    encode(message: Message): Packet {
+        message.packetHeader.sessionId = this.#peerSessionId;
+        const { header, applicationPayload } = MessageCodec.encodePayload(message);
+        const headerBytes = MessageCodec.encodePacketHeader(message.packetHeader);
+        const securityFlags = headerBytes[3];
+        const sessionNodeId = this.isPase
+            ? NodeId.UNSPECIFIED_NODE_ID
+            : (this.#fabric?.nodeId ?? NodeId.UNSPECIFIED_NODE_ID);
+        const nonce = this.generateNonce(securityFlags, header.messageId, sessionNodeId);
+        return { header, applicationPayload: Crypto.encrypt(this.#encryptKey, applicationPayload, nonce, headerBytes) };
+    }
+
+    get attestationChallengeKey(): Uint8Array {
+        return this.#attestationKey;
+    }
+
+    get fabric() {
+        return this.#fabric;
+    }
+
+    addAssociatedFabric(fabric: Fabric) {
+        if (this.#fabric !== undefined) {
+            throw new MatterFlowError("Session already has an associated Fabric. Cannot change this.");
+        }
+        this.#fabric = fabric;
+    }
+
+    get id() {
+        return this.#id;
+    }
+
+    get name() {
+        return `secure/${this.#id}`;
+    }
+
+    get peerSessionId(): number {
+        return this.#peerSessionId;
+    }
+
+    get nodeId() {
+        return this.#fabric?.nodeId ?? NodeId.UNSPECIFIED_NODE_ID;
+    }
+
+    get peerNodeId() {
+        return this.#peerNodeId;
+    }
+
+    get associatedFabric(): Fabric {
+        if (this.#fabric === undefined) {
+            throw new NoAssociatedFabricError(
+                `${this.isPase ? "PASE " : ""}Session needs to have an associated Fabric for fabric sensitive data handling.`,
+            );
+        }
+        return this.#fabric;
+    }
+
+    async clearSubscriptions(flushSubscriptions = false) {
+        const subscriptions = [...this.#subscriptions]; // get all values because subscriptions will remove themselves when cancelled
+        for (const subscription of subscriptions) {
+            await subscription.close(flushSubscriptions);
+        }
+    }
+
+    /** Ends a session. Outstanding subscription data will be flushed before the session is destroyed. */
+    async end(sendClose: boolean, closeAfterExchangeFinished = false) {
+        await this.clearSubscriptions(true);
+        await this.destroy(sendClose, closeAfterExchangeFinished);
+    }
+
+    /** Destroys a session. Outstanding subscription data will be discarded. */
+    async destroy(sendClose = false, closeAfterExchangeFinished = true) {
+        await this.clearSubscriptions(false);
+        this.#fabric?.removeSession(this);
+        if (!sendClose) {
+            this.#sendCloseMessageWhenClosing = false;
+        }
+
+        if (closeAfterExchangeFinished) {
+            logger.info(`Register Session ${this.name} to close when exchange is ended.`);
+            this.#closingAfterExchangeFinished = true;
+        } else {
+            this.#isClosing = true;
+            logger.info(`End ${this.isPase ? "PASE" : "CASE"} session ${this.name}`);
+            this.manager?.sessions.delete(this);
+
+            // Wait for the exchange to finish closing
+            if (this.closer) {
+                await this.closer;
+            }
+        }
+    }
+
+    /**
+     * The peer node's address.
+     */
+    get peerAddress() {
+        return PeerAddress({
+            fabricIndex: this.#fabric?.fabricIndex ?? FabricIndex.NO_FABRIC,
+            nodeId: this.#peerNodeId,
+        });
+    }
+
+    /**
+     * Indicates whether a peer matches a specific address.
+     */
+    peerIs(address: PeerAddress) {
+        return (
+            (this.#fabric?.fabricIndex ?? FabricIndex.NO_FABRIC) === address.fabricIndex &&
+            this.#peerNodeId === address.nodeId
+        );
+    }
+
+    private generateNonce(securityFlags: number, messageId: number, nodeId: NodeId) {
+        const writer = new DataWriter(Endian.Little);
+        writer.writeUInt8(securityFlags);
+        writer.writeUInt32(messageId);
+        writer.writeUInt64(nodeId);
+        return writer.toByteArray();
+    }
+}
+
+export function assertSecureSession(session?: Session, errorText?: string): asserts session is SecureSession {
+    if (!session?.isSecure) {
+        throw new MatterFlowError(errorText ?? "Insecure session in secure context");
+    }
+}

package/src/session/Session.ts

@@ -0,0 +1,188 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Time } from "#general";
+import { NodeId } from "#types";
+import { DecodedMessage, DecodedPacket, Message, Packet } from "../codec/MessageCodec.js";
+import { Fabric } from "../fabric/Fabric.js";
+import { MessageCounter } from "../protocol/MessageCounter.js";
+import { MessageReceptionState } from "../protocol/MessageReceptionState.js";
+import { type SessionManager } from "./SessionManager.js";
+
+/**
+ * Minimum amount of time between sender retries when the destination node is Active. This SHALL be greater than or
+ * equal to the maximum amount of time a node may be non-responsive to incoming messages when Active.
+ */
+export const SESSION_ACTIVE_INTERVAL_MS = 300;
+
+/**
+ * Minimum amount of time between sender retries when the destination node is Idle. This SHALL be greater than or equal
+ * to the maximum amount of time a node may be non-responsive to incoming messages when Idle.
+ */
+export const SESSION_IDLE_INTERVAL_MS = 500;
+
+/** Minimum amount of time the node SHOULD stay active after network activity. */
+export const SESSION_ACTIVE_THRESHOLD_MS = 4000;
+
+/** Fallback value for Data Model Revision when not provided in Session parameters. We use Matter 1.2 as assumption. */
+export const FALLBACK_DATAMODEL_REVISION = 17;
+
+/** Fallback value for Interaction Model Revision when not provided in Session parameters. We use Matter 1.2 as assumption. */
+export const FALLBACK_INTERACTIONMODEL_REVISION = 11;
+
+/**
+ * Fallback value for Specification Version when not provided in Session parameters. We use 0 as assumption which is
+ * "before 1.3".
+ */
+export const FALLBACK_SPECIFICATION_VERSION = 0;
+
+/**
+ * Fallback value for the maximum number of paths that can be included in a single invoke message when not provided in
+ * Session parameters.
+ */
+export const FALLBACK_MAX_PATHS_PER_INVOKE = 1;
+
+export interface SessionParameters {
+    idleIntervalMs: number;
+    activeIntervalMs: number;
+    activeThresholdMs: number;
+    dataModelRevision: number;
+    interactionModelRevision: number;
+    specificationVersion: number;
+    maxPathsPerInvoke: number;
+}
+
+export type SessionParameterOptions = Partial<SessionParameters>;
+
+export abstract class Session {
+    abstract get name(): string;
+    abstract get closingAfterExchangeFinished(): boolean;
+    #manager?: SessionManager;
+    timestamp = Time.nowMs();
+    activeTimestamp = 0;
+    protected readonly idleIntervalMs: number;
+    protected readonly activeIntervalMs: number;
+    protected readonly activeThresholdMs: number;
+    protected readonly dataModelRevision: number;
+    protected readonly interactionModelRevision: number;
+    protected readonly specificationVersion: number;
+    protected readonly maxPathsPerInvoke: number;
+    protected readonly messageCounter: MessageCounter;
+    protected readonly messageReceptionState: MessageReceptionState;
+
+    /**
+     * If the ExchangeManager performs async work to clean up a session it sets this promise.  This is because
+     * historically we didn't return from destroy() until ExchangeManager was complete.  Not sure if this is entirely
+     * necessary but it makes sense so this allows us to maintain the old behavior.
+     */
+    closer?: Promise<void>;
+
+    constructor(args: {
+        manager?: SessionManager;
+        messageCounter: MessageCounter;
+        messageReceptionState: MessageReceptionState;
+        sessionParameters?: SessionParameterOptions;
+        setActiveTimestamp: boolean;
+    }) {
+        const {
+            manager,
+            messageCounter,
+            messageReceptionState,
+            sessionParameters: {
+                idleIntervalMs = SESSION_IDLE_INTERVAL_MS,
+                activeIntervalMs = SESSION_ACTIVE_INTERVAL_MS,
+                activeThresholdMs = SESSION_ACTIVE_THRESHOLD_MS,
+                dataModelRevision = FALLBACK_DATAMODEL_REVISION,
+                interactionModelRevision = FALLBACK_INTERACTIONMODEL_REVISION,
+                specificationVersion = FALLBACK_SPECIFICATION_VERSION,
+                maxPathsPerInvoke = FALLBACK_MAX_PATHS_PER_INVOKE,
+            } = {},
+            setActiveTimestamp,
+        } = args;
+        this.#manager = manager;
+        this.messageCounter = messageCounter;
+        this.messageReceptionState = messageReceptionState;
+        this.idleIntervalMs = idleIntervalMs;
+        this.activeIntervalMs = activeIntervalMs;
+        this.activeThresholdMs = activeThresholdMs;
+        this.dataModelRevision = dataModelRevision;
+        this.interactionModelRevision = interactionModelRevision;
+        this.specificationVersion = specificationVersion;
+        this.maxPathsPerInvoke = maxPathsPerInvoke;
+        if (setActiveTimestamp) {
+            this.activeTimestamp = this.timestamp;
+        }
+    }
+
+    notifyActivity(messageReceived: boolean) {
+        this.timestamp = Time.nowMs();
+        if (messageReceived) {
+            // only update active timestamp if we received a message
+            this.activeTimestamp = this.timestamp;
+        }
+    }
+
+    isPeerActive(): boolean {
+        return Time.nowMs() - this.activeTimestamp < this.activeThresholdMs;
+    }
+
+    getIncrementedMessageCounter() {
+        return this.messageCounter.getIncrementedCounter();
+    }
+
+    updateMessageCounter(messageCounter: number, _sourceNodeId?: NodeId) {
+        this.messageReceptionState.updateMessageCounter(messageCounter);
+    }
+
+    /**
+     * The peer's session parameters.
+     */
+    get parameters(): SessionParameters {
+        const {
+            idleIntervalMs,
+            activeIntervalMs,
+            activeThresholdMs,
+            dataModelRevision,
+            interactionModelRevision,
+            specificationVersion,
+            maxPathsPerInvoke,
+        } = this;
+        return {
+            idleIntervalMs,
+            activeIntervalMs,
+            activeThresholdMs,
+            dataModelRevision,
+            interactionModelRevision,
+            specificationVersion,
+            maxPathsPerInvoke,
+        };
+    }
+
+    abstract isSecure: boolean;
+    abstract isPase: boolean;
+    abstract id: number;
+    abstract peerSessionId: number;
+    abstract nodeId: NodeId | undefined;
+    abstract peerNodeId: NodeId | undefined;
+    abstract associatedFabric: Fabric;
+    abstract supportsMRP: boolean; // TODO: always false for Group Sessions
+
+    abstract decode(packet: DecodedPacket, aad?: Uint8Array): DecodedMessage;
+    abstract encode(message: Message): Packet;
+    abstract end(sendClose: boolean): Promise<void>;
+    abstract destroy(sendClose?: boolean, closeAfterExchangeFinished?: boolean): Promise<void>;
+
+    protected get manager() {
+        return this.#manager;
+    }
+
+    /**
+     * @deprecated
+     */
+    get owner() {
+        return this.#manager?.owner;
+    }
+}