node

type Aggregator struct {
	// contains filtered or unexported fields
}

type Attestation struct {
	// Chain is the DAC, its key and the PAI; nil is the CSA test chain.
	Chain *attestation.Chain
	// CertificationDeclaration is the CMS-signed CD; nil is the CSA test
	// CD for the vendor and product.
	CertificationDeclaration []byte
}

type BasicInformation struct {
	VendorName   string
	ProductName  string
	ProductLabel string
	NodeLabel    string // mandatory
	SerialNumber string
	// UniqueID pins BasicInformation.UniqueID (quality F, Matter
	// §11.1.5.13) to a value the host persisted itself; at most 32 UTF-8
	// bytes. Empty, the facade pins it: the first boot of a store derives
	// one (mattercore.DeriveUniqueID over the vendor, product, NodeLabel
	// and SerialNumber) and keeps it under store.SettingUniqueID, every
	// later boot serves the stored value — matter.js creates uniqueId
	// once when the state has none and persists it
	// (BasicInformationServer.ts:89-91), so a later edit to NodeLabel does
	// not re-identify the node under a controller's cache. A boot with
	// bootid rotation enabled serves a per-boot value and pins nothing, so
	// the next boot without rotation serves the value pinned before it (a
	// stored value flagged by the deprecated store.SettingUniqueIDRotated
	// is re-derived and pinned once instead).
	// Leave the field empty unless the host owns the node's identity: a
	// value here replaces the facade's pin, silently.
	UniqueID              string
	HardwareVersion       uint16
	HardwareVersionString string
	SoftwareVersion       uint32
	SoftwareVersionString string
}

type Client struct {
	// Enabled builds the client stack; the zero value runs the node
	// without one ([Node.Peers] is nil, a node Binding entry is dropped).
	Enabled bool
	// Listen is the client socket's bind address; empty is an ephemeral
	// port on every address ("[::]:0", "0.0.0.0:0" with
	// Network.PreferIPv4). The client stack initiates from its own socket:
	// an initiator's source port is free, and the peer answers the source
	// it saw.
	Listen string
	// Names is the DNS-SD cache the peers' operational records are looked
	// up in; nil opens one on the mDNS groups (discovery.Open), which the
	// node closes on Stop. A Names the host supplies stays the host's.
	Names *discovery.Names
}

type CommissionerControlConfig struct {
	// Approver approves requests. Required.
	Approver mattercore.CommissioningApprover
	// Commissioner commissions an approved client's node. Required.
	Commissioner mattercore.ReverseCommissioner
	// SupportedDeviceCategories is the attribute; a fabric-synchronising
	// bridge states FabricSynchronization.
	SupportedDeviceCategories commctrldef.SupportedDeviceCategoryBitmap
	// ApprovalTimeout and ApprovalValidity are
	// mattercore.CommissionerControlConfig's.
	ApprovalTimeout, ApprovalValidity time.Duration
}

type Commissioning struct {
	// Passcode is the setup passcode; it must pass setup.IsValidSetupPIN.
	Passcode uint32
	// Discriminator is the 12-bit commissioning discriminator.
	Discriminator uint16
	// PBKDFIterations is the SPAKE2+ PBKDF2 iteration count, within
	// [spake2.IterationsMin, spake2.IterationsMax].
	PBKDFIterations int
	// Salt is the SPAKE2+ salt, spake2.PBKDFMinSaltSize to
	// spake2.PBKDFMaxSaltSize bytes.
	Salt []byte
	// LocationCapability is GeneralCommissioning's LocationCapability
	// (Matter §11.10.5.3), the regulatory locations the node supports and
	// SetRegulatoryConfig admits (GeneralCommissioningServer.ts:172-191):
	// mattercore.RegulatoryIndoor (the zero value, the facade's default),
	// RegulatoryOutdoor or RegulatoryIndoorOutdoor.
	LocationCapability uint8
}

type Config struct {
	// Network mirrors matter.js `network` (NetworkServer.ts:202-222).
	Network Network
	// Commissioning mirrors matter.js `commissioning`
	// (CommissioningServer.ts:400-410).
	Commissioning Commissioning
	// ProductDescription mirrors matter.js `productDescription`
	// (ProductDescriptionServer.ts:70-90): the identity the commissionable
	// advertisement carries.
	ProductDescription ProductDescription
	// BasicInformation mirrors matter.js `basicInformation`
	// (examples/device-bridge-onoff/src/BridgedDevicesNode.ts:29-65).
	BasicInformation BasicInformation
	// Store is where the node keeps its fabrics, credentials, ACL, groups,
	// subscriptions, settings and endpoint numbers.
	Store Store
	// Advertiser publishes the node over DNS-SD; nil is mdns.NewNoop(),
	// as bridge.New treats a nil advertiser. [Node.Stop] closes it.
	Advertiser mdns.Advertiser
	// DeviceTypeValidation is the bridge's device-type judgement mode
	// (bridge.SetDeviceTypeValidation); the zero value is matter.js's
	// warn mode.
	DeviceTypeValidation endpoint.DeviceTypeValidationMode
	// Attestation is the device attestation material; the zero value is
	// the CSA test chain and test Certification Declaration for the
	// configured vendor and product (attestation.BuildTestChain,
	// attestation.BuildTestCertificationDeclaration) — pairable with every
	// commissioner's test PAA, and not shippable.
	Attestation Attestation
	// OTA mounts the OTA Software Update Requestor on the root when set;
	// nil leaves it out (and the OtaRequestor device type with it).
	OTA *OtaConfig
	// OTAProvider serves OTA images: the OTA Software Update Provider on an
	// endpoint of device type OtaProvider beside the Aggregator, its images
	// over BDX (ADR 0021). nil, or no ImageSource, mounts none. With
	// Topology set the node builds the provider ([Node.OTAProvider]) and
	// the host mounts it.
	OTAProvider *OTAProviderConfig
	// CommissionerControl mounts the CommissionerControl server on the
	// Aggregator (ADR 0020 stage 6); nil mounts none. The reference daemon
	// mounts none.
	CommissionerControl *CommissionerControlConfig
	// FixedLabels is the root FixedLabel list; nil serves an empty list.
	FixedLabels []fixedlabeldef.LabelStruct
	// Locales are the root LocalizationConfiguration's SupportedLocales,
	// the first of them its ActiveLocale; nil is en-US alone. matter.js
	// detects the active locale and lists it alone when the host states
	// neither (LocalizationConfigurationServer.ts:14-21 initialize); a host
	// states its own, as the reference daemon does (en-US, de-DE).
	Locales []string
	// Groups, when set, is the group state the node runs on, for a host
	// whose own assembler ([Config].Topology) mounts the stack's Groups and
	// ScenesManagement servers over it (endpoint.Config.Groups): one
	// manager serves the endpoints' servers, the bridge's group-message
	// routing and the root's GroupKeyManagement and Groupcast, as matter.js
	// has one GroupKeyManagementServer the GroupsServers of every endpoint
	// write (GroupsServer.ts). The facade loads it (groups.Manager.Load)
	// and attaches it; nil builds one over the credential store, which
	// [Node.Groups] returns for a host that binds its assembler after New.
	Groups *groups.Manager
	// Topology, when set, is the host's own topology — a host that
	// assembles its endpoints itself (its own endpoint.Assembler over its
	// own device model, one endpoint.Snapshot per scope, its own label and
	// scene persistence) hands the bridge its Snapshotter here, as the
	// reference daemon did before the facade (main.go:188, bridge.New's
	// first argument). The facade then builds no assembler and no
	// [Aggregator] ([Node.Aggregator] is nil); the root and Aggregator
	// endpoints' servers, the PartsList providers and every port stay the
	// facade's. nil is the facade's [Aggregator] under one scope.
	Topology bridge.Snapshotter
	// EndpointPersistence, when set, replaces the facade's own scene and
	// bridged-NodeLabel persistence ([NewEndpointPersistence] over the
	// node's store) in the facade's assembler and [Aggregator], for a host
	// that keeps that state itself; [Node.Persistence] returns it. nil is
	// the facade's own.
	EndpointPersistence EndpointPersistence
	// AggregatorServers are mounted on the Aggregator endpoint after
	// Identify, Descriptor, FixedLabel and UserLabel — an Actions server,
	// say (the daemon's buildAggregatorClusters extra, wiring.go:330-345).
	AggregatorServers []contract.ClusterServer
	// SupportedFabrics is OperationalCredentials' SupportedFabrics, the
	// number of fabrics the node admits (Matter §11.18.4.4: 1 to 254); 0
	// is 5, the facade's value before it was configurable. matter.js
	// defaults it to 254 when unset (OperationalCredentialsServer.ts:
	// 84-88 initialize), which cluster/core does too; the facade keeps 5.
	SupportedFabrics uint8
	// DisableTimeSynchronization leaves the TimeSynchronization cluster
	// (0x0038) off the root; the zero value mounts it, as the facade
	// always did. RootNode carries it under an optional conformance
	// (device/root_node_gen.go, generated from the snapshot).
	// Without it GeneralDiagnostics has no UTC clock: TimeSnapshot
	// answers SystemTimeMs alone and PosixTimeMs null, as matter.js
	// GeneralDiagnosticsServer.timeSnapshot does without a
	// TimeSynchronizationBehavior (GeneralDiagnosticsServer.ts:168-182).
	DisableTimeSynchronization bool
	// Client is the node's client stack ([Client]): the socket, exchanges
	// and peers its Binding entries reach other nodes through. The zero
	// value runs without one.
	Client Client
	// Observers are the host's callbacks on fabric and commissioning
	// events, each chained after the facade's own handler (observers.go);
	// the zero value observes nothing.
	Observers Observers
	// Logger is the node's logger; nil is slog.Default().
	Logger *slog.Logger
	// Clock is the node's time source; nil is [clock.System]. The node
	// hands it to the bridge (every device-side interval: the ack pump,
	// MRP, subscriptions' timers, the commissioning window, PASE lockout),
	// the session table, the subscription engine, the PASE and CASE
	// providers, the operational resolver, an advertiser that takes a
	// clock ([mdns.Zeroconf]), the group sender, the root's cluster
	// servers, OTA, the store's persist loop and the reopen poll. A test
	// passes a [github.com/SukramJ/go-fabric/clock/clocktest.Fake].
	Clock clock.Clock
}

type Endpoint interface {
	Spec() endpoint.Spec
}

type EndpointPersistence interface {
	endpoint.ScenesStore
	// OnNodeLabelWritten persists a commissioner-written NodeLabel of the
	// bridged endpoint under key; it is endpoint.Config.OnNodeLabelWritten.
	OnNodeLabelWritten(key endpoint.SourceKey, label string)
	// NodeLabel is the label persisted for key, "" for none.
	NodeLabel(ctx context.Context, key endpoint.SourceKey) string
}

type FabricInfo struct {
	FabricIndex        uint8
	FabricID           uint64
	NodeID             uint64
	RootPublicKey      []byte
	CompressedFabricID [8]byte
}

type Network struct {
	// Listen is the UDP listen address; empty is ":5540".
	Listen string
	// PreferIPv4 forces an IPv4-only socket.
	PreferIPv4 bool
	// TCP selects the Matter TCP transport; the zero value is TCP off. A
	// TCP role is also what the node's PASE and CASE responders advertise
	// in their session parameters (SupportedTransports: tcpServer for
	// Incoming, tcpClient for Outgoing), so a peer learns it during the
	// handshake and may open TCP to us — matter.js
	// ServerNetworkRuntime.ts:355-363.
	TCP bridge.TCPConfig
	// WiFi mounts WiFiNetworkDiagnostics (0x0036) on the root for a node on
	// Wi-Fi; the zero value (no Reporter) mounts none. NetworkCommissioning
	// stays Ethernet-only either way (concept v2 §B.4): the node states the
	// RootNode device-type condition WiFi, under which RootNode lists the
	// cluster ("[WiFi]", device/root_node_gen.go), through the assembler's
	// RootDeviceConditions — with [Config].Topology the host's own
	// assembler states it. EthernetNetworkDiagnostics stays mounted beside
	// it.
	WiFi WiFi
	// WiFiCommissioning mounts NetworkCommissioning with the Wi-Fi feature
	// instead of Ethernet, its scan and connect done by Driver — what the
	// commissioner's network steps configure. TESTING ONLY: the module's
	// nodes are Ethernet-attached; the reference daemon's --wifi-sim is
	// the one user. The zero value (no Driver) keeps the Ethernet-only
	// server, and the composition is unchanged.
	WiFiCommissioning WiFiCommissioning
	// ReannounceInterval is the cadence at which the node re-publishes its
	// DNS-SD records when its Advertiser is an mdns.Reannouncer
	// (mdns.Zeroconf is): the loop starts on [Node.Start] and stops on
	// [Node.Stop]. 0 is [DefaultReannounceInterval]. The loop is this
	// module's own device, not matter.js's (mdns.Reannouncer).
	ReannounceInterval time.Duration
	// DisableReannounce keeps the re-announce loop off; [Node.TriggerReannounce]
	// still re-publishes on demand.
	DisableReannounce bool
}

type Node struct {
	// contains filtered or unexported fields
}

type OTAProviderConfig struct {
	// ImageSource names and serves the images; nil mounts no provider.
	ImageSource mattercore.OTAImageSource
	// Consent asks the user; nil declines an image that needs a consent
	// the requestor cannot give.
	Consent mattercore.OTAConsent
	// ApplyPolicy decides an allowed apply; nil proceeds at once.
	ApplyPolicy mattercore.OTAApplyPolicy
	// BDXMaxBlockSize, when set, caps the block size of the image
	// transfers.
	BDXMaxBlockSize uint16
	// OnStatusChange observes the requestors' update states; nil observes
	// nothing.
	OnStatusChange func(peer mattercore.OTAPeer, status mattercore.OTAUpdateStatus, version uint32)
}

type Observers struct {
	// OnFabricAdded runs after an AddNOC installed a fabric and the
	// facade rebuilt the fabric's CASE identity and announced its
	// operational record. Mirrors matter.js FabricManager `events.added`
	// (FabricManager.ts:209).
	OnFabricAdded func(FabricInfo) error
	// OnFabricRemoved runs after RemoveFabric (or the fail-safe rollback
	// of an AddNOC) deleted a fabric and the facade's cleanup ran: the
	// fabric, its ACL and its keys are gone from the store, its CASE
	// identity and operational record are withdrawn, its sessions are
	// told and closed (the invoking one after the response). When it was
	// the last fabric the node's own window reopens afterwards, once the
	// node is idle — no fail-safe armed and no session left (matter.js
	// #resetWhenIdle); OnWindowTransition reports that. Mirrors
	// matter.js FabricManager `events.deleted` (FabricManager.ts:253).
	OnFabricRemoved func(FabricInfo) error
	// OnFabricUpdated runs after an UpdateNOC (or the fail-safe rollback
	// of one) changed a fabric's operational identity and the facade
	// moved the CASE identity and the operational record and closed the
	// fabric's other sessions. Mirrors matter.js FabricManager
	// `events.replaced` (FabricManager.ts:236, :377).
	OnFabricUpdated func(FabricInfo) error
	// OnCommissioningComplete runs after a successful
	// CommissioningComplete and the facade's own handling of it (pending
	// OperationalCredentials state cleared, the OTA requestor's query
	// scheduled), with the fabric the commissioning completed for. It
	// fires on every CommissioningComplete, whereas matter.js's
	// `commissioned` event fires when the fabric count crosses zero
	// (CommissioningServer.ts:143-157 #syncCommissioned).
	OnCommissioningComplete func(fabricIndex uint8) error
	// OnWindowTransition runs on every commissioning-window transition
	// (open, close, an administrator's AdminFabricIndex cleared), after
	// the facade switched the PASE acceptor and published or withdrew
	// the commissionable record.
	OnWindowTransition func(WindowSnapshot) error
}

type OtaConfig struct {
	// Dir receives the downloads; mandatory.
	Dir string
	// Harness applies an image in place, reporting its version as running
	// without a restart. TESTING ONLY — see the daemon's otaApplier.
	Harness bool
	// Applier carries out an update; nil is the daemon's applier, which
	// validates the image and keeps it under Dir/applied.
	Applier mattercore.OtaApplier
}

type ProductDescription struct {
	// Name is the advertised device name; empty is
	// BasicInformation.NodeLabel, as the daemon advertises (main.go:285).
	Name string
	// DeviceType is the advertised device type; 0 is RootNode (0x0016),
	// as the daemon advertises (main.go:290).
	DeviceType uint16
	// VendorID and ProductID are the node's identity; both mandatory.
	VendorID, ProductID uint16
}

type RootClusters struct {
	BasicInformation           *mattercore.BasicInformation
	AccessControl              *mattercore.AccessControl
	GeneralCommissioning       *mattercore.GeneralCommissioning
	AdministratorCommissioning *wire.AdministratorCommissioning
	// NetworkCommissioning is the Ethernet server; nil when
	// [Network].WiFiCommissioning has a Driver.
	NetworkCommissioning *mattercore.NetworkCommissioning
	// WiFiNetworkCommissioning is the Wi-Fi server, nil unless
	// [Network].WiFiCommissioning has a Driver (TESTING ONLY).
	WiFiNetworkCommissioning *mattercore.WiFiNetworkCommissioning
	GeneralDiagnostics       *mattercore.GeneralDiagnostics
	DiagnosticLogs           *mattercore.DiagnosticLogs
	// TimeSynchronization is nil when [Config].DisableTimeSynchronization
	// is set.
	TimeSynchronization    *mattercore.TimeSynchronization
	OperationalCredentials *mattercore.OperationalCredentials
	GroupKeyManagement     *mattercore.GroupKeyManagement
	Groupcast              *mattercore.Groupcast
	Descriptor             *mattercore.Descriptor
	// OTARequestor is nil unless [Config].OTA is set.
	OTARequestor *mattercore.OTASoftwareUpdateRequestor
	// WiFiNetworkDiagnostics is nil unless [Network].WiFi has a Reporter.
	WiFiNetworkDiagnostics *mattercore.WiFiNetworkDiagnostics
	// PowerSourceConfiguration lists the node's PowerSource endpoints;
	// it starts empty, for the host to fill once the topology exists.
	PowerSourceConfiguration *mattercore.PowerSourceConfiguration
	// contains filtered or unexported fields
}

type Store struct {
	DB          *sql.DB
	Credentials *store.Store
	Endpoints   endpoint.Store
}

type WiFi struct {
	// Reporter answers the cluster's reads and ResetCounts
	// (mattercore.WiFiReporter); nil mounts no cluster.
	Reporter mattercore.WiFiReporter
	// Features is the cluster's FeatureMap: wifidiagdef.FeaturePacketCounts
	// (PKTCNT) and wifidiagdef.FeatureErrorCounts (ERRCNT, which brings
	// ResetCounts).
	Features wifidiagdef.Feature
	// Attributes are the optional attributes served
	// (wifidiagdef.AttrCurrentMaxRate).
	Attributes []uint32
}

type WiFiCommissioning struct {
	// Driver scans and connects; nil mounts the Ethernet-only server.
	Driver contract.WiFiDriver
	// MaxNetworks is the size of the network list; 0 is 1.
	MaxNetworks uint8
	// ScanMaxTimeSeconds and ConnectMaxTimeSeconds; 0 are 10 and 20.
	ScanMaxTimeSeconds, ConnectMaxTimeSeconds uint8
}

type WindowCredentials struct {
	// Discriminator is the 12-bit discriminator the window is advertised
	// under.
	Discriminator uint16
	// Passcode is the window's setup passcode; it must pass
	// setup.IsValidSetupPIN.
	Passcode uint32
	// Iterations is the SPAKE2+ PBKDF2 iteration count, within
	// [spake2.IterationsMin, spake2.IterationsMax].
	Iterations uint32
	// Salt is the SPAKE2+ salt, spake2.PBKDFMinSaltSize to
	// spake2.PBKDFMaxSaltSize bytes.
	Salt []byte
	// Timeout is how long the window stays open; 0 is the node's own
	// window default (bridge.OwnWindowTimeoutUncommissioned while the node
	// has no fabric, bridge.OwnWindowTimeoutCommissioned once it has one).
	Timeout time.Duration
}

type WindowSnapshot struct {
	// Open reports whether a window is open, whoever opened it.
	Open bool
	// Own reports whether it is the node's own window — the one an
	// uncommissioned node opens, [Node.OpenBasicWindow]'s, or one the
	// host opened through CommissioningWindow().OpenOwnWindow — rather
	// than an administrator's.
	Own bool
	// Administrator is the AdministratorCommissioning view of the
	// window: WindowStatus, AdminFabricIndex, AdminVendorId. The node's
	// own window reads WindowNotOpen there, as matter.js keeps those
	// attributes for administrator windows only.
	Administrator wire.WindowStatusSnapshot
	// CommissioningMode is the CM value of the commissionable record the
	// node publishes after the transition: 0 none, 1 a basic window, 2
	// an enhanced window with an administrator's verifier.
	CommissioningMode uint8
	// Discriminator is the published record's discriminator; 0 when
	// CommissioningMode is 0.
	Discriminator uint16
}