/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import type { DecodedPacket } from "#codec/MessageCodec.js"; import { FabricManager } from "#fabric/FabricManager.js"; import type { Subscription } from "#interaction/Subscription.js"; import { PeerAddress } from "#peer/PeerAddress.js"; import { PeerLossContext } from "#peer/PeerLossContext.js"; import { GroupSession } from "#session/GroupSession.js"; import { Diagnostic, BasicSet, Bytes, Channel, ClosedError, Construction, Crypto, Duration, Environment, Environmental, Observable, StorageContext, Timestamp, Transport } from "@matter/general"; import { CaseAuthenticatedTag, ClusterId, EndpointNumber, FabricId, FabricIndex, GroupId, NodeId } from "@matter/types"; import { Groupcast } from "@matter/types/clusters/groupcast"; import type { ExposedFabricInformation, Fabric } from "../fabric/Fabric.js"; import { PersistedMessageCounter } from "../protocol/MessageCounter.js"; import { NodeSession } from "./NodeSession.js"; import type { Session } from "./Session.js"; import { SessionParameters } from "./SessionParameters.js"; import { UnsecuredSession } from "./UnsecuredSession.js"; /** Resumption record without a fabric reference but relevant lookup data used internally in SessionManager */ interface InternalResumptionRecord { sharedSecret: Bytes; resumptionId: Bytes; fabricId: FabricId; fabricIndex: FabricIndex; peerNodeId: NodeId; sessionParameters: SessionParameters; caseAuthenticatedTags?: readonly CaseAuthenticatedTag[]; } /** Resumption record with Fabric reference. */ export interface ResumptionRecord extends Omit { fabric: Fabric; } export interface ActiveSessionInformation { name: string; nodeId: NodeId; peerNodeId: NodeId; fabric?: ExposedFabricInformation; isPeerActive: boolean; secure: boolean; lastInteractionTimestamp?: number; lastActiveTimestamp?: number; numberOfActiveSubscriptions: number; } /** * Metadata about a received group message, emitted via {@link SessionManager.onGroupMessage} for Groupcast testing. * Uses {@link Groupcast.GroupcastTestResult} directly so consumers can forward the value without mapping. */ export interface GroupMessageEventInfo { result: Groupcast.GroupcastTestResult; fabric?: Fabric; /** Authenticated group id. Only set when the message decoded successfully for a known fabric. */ groupId?: GroupId; /** * Group id taken from the unauthenticated wire header of a message that failed decode. Suitable to derive the * multicast destination address for reporting, but must not be reported as the authenticated GroupID. */ headerGroupId?: GroupId; sourceIp?: string; endpointId?: EndpointNumber; clusterId?: ClusterId; elementId?: number; /** Whether the ACL granted access for the dispatched command (only set for Success). */ accessAllowed?: boolean; } /** * Interfaces {@link SessionManager} with other components. */ export interface SessionManagerContext { fabrics: FabricManager; storage: StorageContext; /** * Where this manager's log messages come from, so a destination can attribute the ones it emits from a timer or * transport callback, which carries no call stack of its own. */ origin?: Diagnostic.Origin; /** * Parameter overrides. */ parameters?: SessionParameters.Config; /** * This is an arbitrary contextual object attached to sessions used for compatibility with legacy APIs. * * @deprecated Scheduled for removal in 0.19 with the legacy controller API. */ owner?: unknown; } /** Thrown into a session closed because its peer exceeded {@link MAX_SESSIONS_PER_PEER}. */ export declare class SessionEvictedError extends ClosedError { constructor(message?: string, options?: ErrorOptions); } /** * Thrown when communication terminates due to node shutdown. */ export declare class ShutdownError extends ClosedError { constructor(message?: string, options?: ErrorOptions); } /** * Manages Matter sessions associated with peer connections. */ export declare class SessionManager { #private; /** * Additive MRP retransmission margin for our own (sender-side) network. Derived from the * configured "own" network profile; defaults to 0 (treated as a low-latency local network). */ localAdditionalMrpDelay: Duration; /** * Fixed sender-side MRP backoff pad added after the exponential backoff (so it is not amplified). * Used to mirror an ICD server's fast-polling-interval grace; defaults to 0. */ localFixedMrpBackoff: Duration; constructor(context: SessionManagerContext); static [Environmental.create](env: Environment): SessionManager; get construction(): Construction; get context(): SessionManagerContext; get crypto(): Crypto; /** * The single node-global Group Encrypted Data Message Counter shared by all group sessions. * @see {@link MatterSpecification.v161.Core} § 4.6.1.3 */ get groupDataMessageCounter(): PersistedMessageCounter; /** * Active secure sessions. */ get sessions(): BasicSet; /** * Active unsecured sessions. */ get unsecuredSessions(): Map; /** * Our session parameters. These are the parameters we provide during session negotiation. The peer may specify * different parameters. */ get sessionParameters(): SessionParameters; /** * Change session parameters. * * Parameters values you omit in {@link parameters} will retain their current values. This only affects new * sessions. */ set sessionParameters(parameters: Partial); /** * Emits when there is a change to the subscription set. */ get subscriptionsChanged(): Observable<[session: NodeSession, subscription: Subscription], void>; /** * Emits when resubmission is necessary due to timeout or network error. */ get retry(): Observable<[session: Session, number: number], void>; /** * Emits for each received group message (success or failure). Observers remain inactive until at least one * listener attaches, so fabrics not under test incur no emission overhead. */ get onGroupMessage(): Observable<[info: GroupMessageEventInfo], void>; /** * Convenience function for accessing a fabric by address. */ fabricFor(address: FabricIndex | PeerAddress): Fabric; /** The fabric of {@link fabricIndex}, or undefined while it does not exist or is being removed. */ maybeFabricFor(fabricIndex: FabricIndex): Fabric | undefined; /** * @deprecated Scheduled for removal in 0.19 with the legacy controller API. */ get owner(): unknown; createUnsecuredSession(options: { channel: Channel; initiatorNodeId?: NodeId; sessionParameters?: SessionParameters.Config; isInitiator?: boolean; }): UnsecuredSession; createSecureSession(config: Omit & { crypto?: Crypto; }): Promise; /** * Deletes a resumption record for a given address. Returns true if the record was deleted, false if it did not * exist. */ deleteResumptionRecord(address: PeerAddress): Promise; /** * Deletes all resumption records for a given fabric. Returns true if any records were deleted, false if none * existed. */ deleteResumptionRecordsForFabric(fabric: Fabric): Promise; findOldestInactiveSession(): NodeSession; /** * Allocates a local ID for a new secure unicast session, PASE or CASE. The ID is never 0 because 0 identifies the * unsecured session. * * @see {@link MatterSpecification.v161.Core} § 4.4.1.3.4 * @see {@link MatterSpecification.v161.Core} § 4.13.2.4 */ getNextAvailableSessionId(): Promise; getSession(sessionId: number): NodeSession | undefined; getPaseSession(): NodeSession | undefined; forFabric(fabric: Fabric): NodeSession[]; sessionFor(peer: PeerAddress): NodeSession; maybeSessionFor(address: PeerAddress): NodeSession | undefined; sessionsFor(address: PeerAddress): NodeSession[]; sessionsForFabricIndex(fabricIndex: FabricIndex): NodeSession[]; /** * Removes all Peer sessions without first closing the subscriptions the peer holds on them; those end when the * sessions close. Our own subscriptions to the peer belong to the peer, not to a session, so a peer that persists * subscriptions can refresh them after its restart. * * @param asOf sessions created at or after this instant are kept; on the clock of {@link Time.nowUs} like * {@link Session.createdAt}, not a wall-clock time. Defaults to now. */ handlePeerShutdown(address: PeerAddress, asOf?: Timestamp): Promise; /** * Removes all Peer sessions and closes subscriptions. */ handlePeerLoss(address: PeerAddress, context: PeerLossContext): Promise; getUnsecuredSession(sourceNodeId?: NodeId): UnsecuredSession | undefined; /** * Obtain an outbound group session for a specific group. * * Returns the session for the current group epoch key. The source is this node and the peer is the group. */ groupSessionForAddress(address: PeerAddress, transports: Transport.Provider): Promise; /** * Obtain a Group session for an incoming packet. * * The session ID is determined by decrypting the packet with possible keys. * * Note that the resulting session is non-operational in the sense that attempting outbound communication will * result in an error. */ groupSessionFromPacket(packet: DecodedPacket, aad: Bytes, sourceIp?: string): { session: GroupSession; message: import("#codec/MessageCodec.js").DecodedMessage; key: AllowSharedBufferSource; }; /** Report a group message event (used by ExchangeManager for replay and InteractionServer for dispatch). */ emitGroupMessage(info: GroupMessageEventInfo): void; registerGroupSession(session: GroupSession): void; removeGroupSession(session: GroupSession): void; findResumptionRecordById(resumptionId: Bytes): ResumptionRecord | undefined; findResumptionRecordByAddress(address: PeerAddress): ResumptionRecord | undefined; saveResumptionRecord(resumptionRecord: ResumptionRecord): Promise; getActiveSessionInformation(): ActiveSessionInformation[]; close(): Promise; clear(): Promise; closeAllSessions(): Promise; /** * Compress range of IDs. This is intended for testing. */ compressIdRange(upperBound: number): void; } export {}; //# sourceMappingURL=SessionManager.d.ts.map