npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@sirena-lwm2m/server

v0.5.0

Published

A TypeScript LwM2M server for the devices that can't speak for themselves.

Readme

sirena-lwm2m-server

A TypeScript LwM2M server for the devices that can't speak for themselves.

Documentation

  • The OMA LwM2M object model (ObjectRegistry, standard objects 0..10, ObjectDefinition, ResourceDefinition) now lives in @sirena-lwm2m/core and is re-exported from this package.
  • Queue Mode — the contract the server keeps with a device that sleeps between its registration updates.
  • The enrolment server address — how a device in Security Mode 4 learns the address it enrols against, and what the server does — and does not — with it.
  • Supported protocols — the transports the server speaks, how to enable each, and what the health endpoint reports.
  • The reach matrix — which operation works on which binding, and what no binding carries.
  • Running the server — the flags, the environment variables and the environment file, and the order they are resolved in.

OSCORE-secured bootstrap and registration

LwM2M 1.2 clients can protect bootstrap and registration with OSCORE (RFC 8613) application-layer security. The server ships the full cryptographic core (HKDF-SHA-256 key derivation, AES-CCM-16-64-128, anti-replay window, OSCORE option codec) and an ITransport decorator that applies it to any underlying transport:

import {
  OscoreContextStore,
  OscoreTransport,
} from "@sirena-lwm2m/server";

const contexts = new OscoreContextStore();
// Build contexts from the Security Object / security-store credentials.
await contexts.loadFromSecurityStore(securityStore, "device-1");

const transport = new OscoreTransport({ transport: coapUdp, contexts });
const server = new LwM2MServer({ transports: [transport], router });

OscoreTransport resolves contexts by endpoint for outbound traffic and by the OSCORE kid for inbound traffic, verifies and decrypts requests, and protects the responses. Messages with no matching context pass through unchanged unless requireOscore: true is set. The oscore field of SecurityCredentials carries the per-endpoint Master Secret, Master Salt and Sender/Recipient IDs.

Block-wise transfer under OSCORE

A payload that does not fit in one datagram travels as a sequence of blocks (RFC 7959). Under OSCORE the blocks are protected one by one: the block-wise transfer sits inside the encryption envelope (RFC 8613 §4.1.3.4.1), so the number of the block and the "more blocks follow" bit travel in the protected part of the message, and the peer decrypts every block before it reassembles them. A large write therefore reaches the device whole while its payload never reaches the wire in the clear.

One protected message carries one block: at most the block size of the block-wise policy (1024 bytes by default, or the size the request asked for) of plaintext, plus the OSCORE overhead — the AEAD tag, the inner framing of the message and the OSCORE option. The datagram that carries it therefore stays inside the MTU budget a CoAP/UDP datagram has. A whole payload is bounded by the block-wise policy's assembled-size cap (16 MiB): a peer that is sent more refuses the transfer rather than buffering without bound.

CoAP over DTLS on UDP (coaps)

The server can listen for CoAP over DTLS 1.2 on UDP (RFC 7252 §9), the coaps listener, in the pre-shared-key mode or the certificate mode (below): a device opens a DTLS session with a ClientHello in a UDP datagram, presents its PSK identity, and registers over the session like any other client. The key is read, by identity, from the security store through the DtlsCredentialResolver; an identity the store does not know and a wrong key are both refused at the handshake ("refused" means the handshake never completes and no session exists; an unknown identity is answered with an alert, a wrong key may be met with silence and the device's handshake timeout). The handshake's PSK identity reaches the server: it travels on every inbound request (LwM2MMessage.peerIdentity) and is recorded on the device's registration (LwM2MClient.peerIdentity, in memory only). It is not compared with the endpoint name.

A device the store knows but the resolver has not resolved yet (a brand-new device) has its first handshake refused with the unknown-identity alert (the store cannot be awaited inside a handshake, and the security store has no "list every credential" method to resolve ahead of time); the device retries and its second attempt succeeds. A device that cannot retry the handshake cannot register on its first attempt; resolve known devices up front with DtlsCredentialResolver.load.

The listener is the CoAP package's own coaps:// server with its built-in DTLS socket (TLS_PSK_WITH_AES_128_CCM_8 and TLS_PSK_WITH_AES_128_GCM_SHA256). DTLS never fragments: a CoAP message may be at most 1200 bytes, and a larger message is not sent and fails visibly (use block-wise transfer for a large body). Start it with --coaps-port (COAPS_PORT; 0 is an OS-assigned port; registry kind coaps). It runs next to the coaps+tcp listener, which is a separate transport on a TCP port.

Certificate mode

With --coaps-cert, --coaps-key and --coaps-ca (COAPS_CERT, COAPS_KEY, COAPS_CA: PEM files, the certificate and the key going together, named like the --coaps-tcp-* settings) the listener presents its own certificate (TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 or TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256) and a configured authority is used: the device's certificate is requested and validated against it, so a certificate from an unknown authority, an expired one, or none at all is refused at the handshake. --coaps-request-client-cert (COAPS_REQUEST_CLIENT_CERT) is true to request it, false to never ask (every device that completes the handshake is served) and unset to let the authority decide; an inconsistent configuration is refused at startup. Keys must be EC (ECDSA) keys: that is all the CoAP package's DTLS socket speaks. RSA is not supported over DTLS: a certificate or key of another type, or a key that does not belong to the certificate, makes the listener fail at startup with an error naming the problem (the coaps+tcp listener, which runs over TLS, still accepts RSA).

Limits and cautions of the coaps listener.

  • ECDSA only. DTLS in the CoAP package speaks ECDHE-ECDSA and nothing else, so an RSA certificate or key is refused when the runner starts, not in a device's handshake. RSA remains supported on the coaps+tcp listener.
  • Certificate options without --coaps-ca leave the listener with no authority to validate a device certificate against: no client certificate is requested and the listener serves unauthenticated devices. Always configure the authority.
  • A wrong pre-shared key is dropped silently (the device sees its handshake time out), while an unknown identity is answered with an alert.
  • A brand-new PSK identity fails its first handshake and registers on the retry (see above). In code: new CoapsTransport({ mode: "x509", certificate: { cert, key, ca } }).

The certificate chain of the handshake is available for the session: LwM2MMessage.peerCertificateChain on every inbound request, LwM2MClient.peerCertificateChain on the registration (in memory only) and { certificateChain } in the onHandshake report, as summaries (subject, issuer, serial, validity, SHA-256 fingerprint). The certificate is not bound to the endpoint name: any device with a certificate the authority accepts may register under any name. Proven by int-402 and int-403.

CoAP over TLS on TCP (coaps+tcp)

The server can listen for CoAP over TLS on TCP, the coaps+tcp listener: a device whose pre-shared key is in the security store registers over the protected channel and shows up for the operator like any other client. The listener can also be secured with certificates instead — see Certificate mode below.

The channel is protected by TLS on a TCP port, and the two modes of the handshake are the modes of TLS: the pre-shared key and the certificate. It is not DTLS, and it is not reachable by a device that speaks DTLS over UDP; that binding is the coaps listener above. The listener is configured and started as coaps+tcp (registry kind coaps+tcp, flags --coaps-tcp-*). It was called coap-dtls (flags --coap-dtls-*, environment COAP_DTLS_*) before issue #368; those names are refused with a message that names their replacements. RFC 8323's CoAP over TLS, which this repository also implements, runs on the separate coap-tls registry kind.

The credential lookup lives in its own module — the DtlsCredentialResolver — and the listener stays ignorant of the store:

import {
  CoapsTcpTransport,
  DtlsCredentialResolver,
} from "@sirena-lwm2m/server";

const credentials = new DtlsCredentialResolver(securityStore);
// The identity a device presents is the endpoint name the store is keyed by.
await credentials.load("device-1");

const transport = new CoapsTcpTransport({
  host: "0.0.0.0",
  port: 5684,
  credentials,
});

The resolver answers the handshake with the pre-shared key of the identity the device presents. An identity the security store does not know is refused: the handshake fails and the device never registers.

The store answers asynchronously, while a TLS handshake cannot wait for a promise. The resolver therefore keeps the identities it has resolved in memory: an identity it has not resolved yet is read from the store in the background — the handshake that asked for it is refused, and the device's next attempt finds the key. A deployment that knows its devices resolves them up front (load), and every device is then served from its first attempt; the management runner resolves the endpoints it already knows.

The protected channel carries the whole device-management surface: the server's requests — a Read, a Write, a Partial Update, an Execute, a Create, a Delete, a Discover, a Write-Attributes, the composite operations and an observation — travel over the connection the device opened, and the device's answers come back on it. A device that closed its connection cannot be reached: the request fails at once with an UnreachableError, which is distinct from the timeout a silent device produces.

The runner starts the listener when --coaps-tcp-port names a port, and reports it on the health endpoint next to the other protocols.

Certificate mode

The listener can be secured with certificates instead of a pre-shared key: it presents its own certificate, validates the device's certificate against the configured authority, and refuses a device whose certificate the authority does not accept. The certificate material is configured once, for the listener — it is not read from the security store and it does not vary per device:

const transport = new CoapsTcpTransport({
  host: "0.0.0.0",
  port: 5684,
  mode: "x509",
  certificate: {
    cert: serverCertPem,
    key: serverKeyPem,
    ca: authorityPem,
  },
});

A configured authority is used: the device's certificate is requested and validated against it, so a device that presents a rejected certificate — or none at all — is refused in the handshake, before it can register. The default lives in the transport rather than in the runner: the listener asks for the device's certificate whenever an authority is configured, so the rule holds for every consumer of the transport and not only for the runner's configuration. The client-certificate request is what the authority decides, and it can be turned off explicitly (requestClientCert: false): the device is then never asked for a certificate, the server authenticates itself to the device, and every device that completes the handshake is served.

The endpoint identity is still the endpoint name the Register request carries (ep=), exactly as in the pre-shared-key mode. The certificate authenticates the device at the handshake; it does not bind the device to an endpoint name, and the server does not compare the presented certificate with the security store — the store holds no client certificate to compare it with.

The runner starts a certificate-mode listener when the configuration names the material: --coaps-tcp-cert, --coaps-tcp-key and --coaps-tcp-ca (or the COAPS_TCP_CERT, COAPS_TCP_KEY and COAPS_TCP_CA environment variables) name the PEM files the material is read from. --coaps-tcp-request-client-cert (COAPS_TCP_REQUEST_CLIENT_CERT) turns the client-certificate request off (false) or asks for it explicitly (true); left unset, the authority decides. A request without an authority is refused when the runner starts.

The certificate lifecycle

The lifecycle of the listener's certificate — how it is rotated, how it is renewed, and whether per-device certificates are needed — is answered in docs/coaps-tcp-certificate-lifecycle.md. In short: the rotation is a restart of the runner with the new material (the CoAP package's certificate-update hook reaches its TLS listeners, not the coaps+tcp listener), the renewal is an out-of-band new certificate plus that same restart, and per-device certificates are not needed at this scope — the listener is listener-level: one server certificate, one authority, an optional client-certificate request.

The enrolment server address

A device in Security Mode 4 ("Certificate mode with EST") enrols itself: it generates its key pair locally and gets its certificate from an enrolment (EST) server. The server hands the device the address of that enrolment server through the bootstrap — and performs no enrolment of its own. It issues no request to the enrolment server, generates no key pair and asks for no certificate; the address is configuration the device is given. The server holds no client for the enrolment server at all: an enrolment would be an HTTP request, and no module of the enrolment path opens one.

The specification has no resource for it. The LwM2M 1.2 Security Object defines resources 0..30, and none of them is an enrolment server address (Core V1.2.1 §E.1, Tables E.1-1 and E.1-2): resource 0 is the LwM2M Server URI, resource 25 the secondary server URI, resource 26 the MQTT server. How this server carries the address is therefore a modelling decision of this server, not a protocol behaviour:

  • In the security configuration — the Security Object instance of the bootstrap profile — the address is named by its semantic name estServerUri. The profile's resource map is keyed by resource id or semantic name, and this is the one semantic name the Security Object has.
  • On the wire the address is a resource of the Security Object instance, under the extension id 31 (EST_SERVER_URI_EXTENSION_ID) — the id the specification leaves free in the Security Object. The id is this server's, not the specification's: the specification's own resources are untouched.
  • The write is the Security Object write the bootstrap already performs: the same Bootstrap-Write (and the same Bootstrap-Pack) that carries Security Mode 4 carries the address, so the device receives the mode and the address together.

One mapping, one precedence. The semantic name is the source of truth and the extension id is its wire projection. An instance that carries both is read and written by the name, so the credentials the server derives and the bytes it writes cannot disagree about the address. The extension is written whenever the configuration names the address, whatever Security Mode the instance carries: that a device which does not know the extension ignores an unknown resource id is an assumption about the device, which the server cannot verify.

const profile: BootstrapProfile = {
  securityInstances: [
    {
      "0": "coaps://server.example:5684",
      "2": 4, // Security Mode: certificate mode with EST
      estServerUri: "https://est.example.com:8443",
    },
  ],
  serverInstances: [{ "0": 1, "1": 86400 }],
};

What the mode means for the rest of the server. A device in mode 4 is expected to enrol itself, so the server holds no identity for it: its credentials carry the mode and the enrolment server address, and no pre-shared key — the DtlsCredentialResolver does not serve such an endpoint. The mode survives the round trip through the security configuration: the Security Object instance becomes credentials, the store keeps the mode and hands it back unchanged, and a consumer can tell that the endpoint enrols itself rather than holding an identity the server already knows. The store keeps the trust anchor too (serverPublicKey, the /0/x/4 resource): a mode-4 record that lost it on the way back would have no anchor to verify the server's certificate against.

Queue Mode

A device that cannot hold a session open registers in Queue Mode: the LwM2M binding mode carries the Q suffix — UQ, USQ, SQ, TQ. The binding-mode vocabulary in src/interfaces/registration/bindingMode.ts names that suffix (QUEUE_MODE_CODE) and accepts it on its own (Q) as well as next to any transport code — a binding mode is a set of codes, not a sequence, so there is no adjacency rule — so the registration is accepted as it stands and the mode it states is recorded on the client — the operator UI shows it in the client's row.

A Queue Mode client is asleep between its registration updates. The server never guesses that a device is asleep: a device that is merely quiet is not a device that has gone to sleep, so the sleep is stated explicitly.

// Put a registered client to sleep. Every management operation
// against it is buffered until it wakes up.
server.markClientAsleep(clientId);

The client wakes up on its next registration update — the wake-up a Queue Mode device announces itself with. The server drains the queue on its own then; the explicit setter is there for a caller that has to drive it out of band.

// Wake a client up by hand and drain its queue. The return value
// is the number of queued requests the drain started with — zero when
// there was nothing queued.
server.markClientAwake(clientId);

The sleep is set through the library API — markClientAsleep() and markClientAwake() on the LwM2MServer object. The server binary does not expose them: the runner has no route and no command that puts a client to sleep, so an operator who runs the binary has no way to put a client to sleep. The automatic detection of a sleeping device is not implemented either, so a server started by the runner keeps every client awake and every management request goes straight out.

A fresh registration is not a wake-up. It replaces the client's registration record, so whatever was still queued for the replaced client is rejected with a NotFoundError rather than delivered, and the new registration starts with an empty queue. The drain happens on the next registration update.

What the server owes a sleeping client

  • A request for a sleeping client is buffered, not sent. Nothing reaches the wire until the client is awake.
  • A client that goes back to sleep keeps its queue. A client that is put back to sleep while its queue is being drained stops the drain: the requests that were not sent stay in the queue, ahead of the requests that were issued later, and they wait there for the client's next wake-up.
  • The buffered requests are delivered in the order they were issued. The queue is a FIFO and the drain is sequential, so the device sees the requests in that order. A request issued while the drain is running waits behind the ones that were already queued — it does not overtake them.
  • A buffered request is not lost. The timeout of a request belongs to the time the request spends on the wire: it is armed when the request is sent, not when it is buffered. A request that waits in the queue for longer than its own timeout is still delivered when the client wakes up, and still resolves with the device's answer.
  • The requests of a client that goes away are rejected, not left pending. A deregistration, an expiry or a fresh registration that replaces the record rejects the queued requests with a NotFoundError, so the caller learns that the request will never be answered — and a rejected request is never put on the wire.

What the operator sees

markClientAsleep and markClientAwake are the API. The queue-mode path reports itself through the server's logger:

| Line | Level | What it says | | --- | --- | --- | | ManagementHandler: request buffered (Queue Mode) | debug | a request was buffered; the metadata carries the queue length | | ManagementHandler: client marked asleep | debug | the client was put to sleep | | ManagementHandler: client awake, draining queue | info | the client woke up; the metadata carries the number of drained requests | | ManagementHandler: client awake, drain in progress | debug | the client woke up again while its queue was still being drained | | ManagementHandler: client awake, empty queue | debug | the client woke up with nothing queued | | ManagementHandler: queued request sent | debug | a drained request went on the wire |

Every management operation the REST API issues — a read, a write, an execute — goes through the same path, so a request to a sleeping device is buffered and delivered the same way. A sleeping device is one the library API put to sleep: the runner never puts one to sleep on its own, so an operator who runs the binary never sees this path taken.

Supported protocols

The server speaks LwM2M 1.2 over these transports:

| Protocol | How it is reached | Enabled by | | --- | --- | --- | | CoAP over UDP | coap://host:5683 | Always. The management server binds it; the standalone bootstrap server binds 5783, the combined one needs --bootstrap-port. | | CoAP over TCP | coap+tcp://host:5683 | --coap-tcp-port on the management server. | | CoAP over TLS (RFC 8323, the coap-tls kind) | coaps+tcp://host:5684 | A coap-tls transport built through the transport registry (buildTransport), with its certificate material. CoAP over TLS on TCP with the RFC 8323 framing. The coaps+tcp:// scheme is shared with the listener two rows down (the coaps+tcp kind): same TLS-over-TCP wire format, different transport; neither is DTLS, and coaps:// is DTLS over UDP. | | CoAP over DTLS on UDP, pre-shared key or certificate | coaps://host:5684 | --coaps-port on the management server (registry kind coaps). DTLS 1.2 over UDP; the listener answers the handshake with the pre-shared key the security store holds for the identity the device presents, and refuses an unknown identity and a wrong key. With --coaps-cert, --coaps-key and --coaps-ca it presents its own ECDSA certificate and validates the device's against the authority; a certificate from an unknown authority or an expired one is refused. A CoAP message is at most 1200 bytes: DTLS does not fragment. Proven by int-401, int-402 and int-403. | | CoAP over TLS on TCP, pre-shared key or certificate | coaps+tcp://host:5684 | --coaps-tcp-port on the management server (registry kind coaps+tcp). The channel is protected by TLS on a TCP port — it is not DTLS, and a device that speaks DTLS over UDP cannot reach it. The listener answers the handshake with the pre-shared key the security store holds for the device that presents it; a device whose identity the store does not know is refused. With --coaps-tcp-cert, --coaps-tcp-key and --coaps-tcp-ca the listener is secured with certificates instead: it presents its own certificate, and the configured authority is used — the device's certificate is requested and validated against it, so a device whose certificate the authority does not accept is refused. | | HTTP | http://host:8080 | A transport built through the transport registry (buildTransport). | | HTTPS | https://host:8443 | A transport built through the transport registry (buildTransport), with its certificate material. | | MQTT | mqtt://broker:1883 | --mqtt-broker-url on the management server, --bootstrap-mqtt-broker-url for the combined bootstrap server, --mqtt-broker-url on the standalone bootstrap server. |

The reach matrix below says what each binding carries, operation by operation — and what no binding carries. The Client Registration interface works over every binding. The Device Management interface works over CoAP and over MQTT, and over HTTP for everything but its two composite operations. The Information Reporting interface works over CoAP and over MQTT; over HTTP it carries the device-initiated Send and nothing else. The Bootstrap interface works over CoAP and over MQTT; over HTTP the device's Bootstrap-Request is classified and reaches the server, but nothing serves it there — with no bootstrap handler wired into the HTTP gateway the request comes back as a server error — and the steps of the sequence the server would then drive are not carried at all, so the sequence cannot run. Over the coaps+tcp listener the protected channel carries the whole device-management surface: the server's requests travel over the connection the device opened, and the device's answers come back on it. The coaps+tcp column covers both of the listener's security modes — the pre-shared key and the certificate: the operations are the same, only the handshake differs.

The composite operations are issued over MQTT as well, with the same SenML family the CoAP binding uses: a Read-Composite and a composite observation carry their selection in the binding's own paths field, a Write-Composite carries the values to write in its payload field, and the composite observation is cancelled with the binding's cancel operation, carrying the token of the observation it cancels. Over HTTP all three composite operations are refused — plain HTTP/1.1 has no FETCH and no iPATCH to carry them.

The device-management interface can also issue a LwM2M 1.2 partial update — partialWrite(clientId, path, values, options) — which updates the named resources of an Object Instance and leaves the others alone. A key names a resource (/3/0/13) or one of its resource instances (/1/0/25/0). The request is a POST on the instance path — a CoAP POST, or the MQTT binding's partial-update operation — whose payload carries only the named resources, in TLV (the default) or in LwM2M CBOR (11544). A full replace of the same instance is a different operation on the wire: a CoAP PUT, or the MQTT binding's replace operation. The two are told apart by their operation, not by a flag in the payload.

Over HTTP the request/reply half works — a device registers, reads and writes through the HTTP gateway — and the server-originated request/response operations reach a device too: the device states the base URL it is reachable at in its registration, in the X-LwM2M-Address header, and the server's Read, Write, Execute, Create, Delete, Discover and Write-Attributes requests are sent there — a partial update as a POST on the Object Instance, a full replace as a PUT. What plain HTTP/1.1 cannot do is a server push: an observe notification has no place in the request/response model, so an observation does not reach an HTTP device. The composite operations are refused over HTTP as well, and so are the steps of the bootstrap sequence — the Bootstrap-Request the device sends is classified and reaches the server, but nothing serves it, and the steps the server would then drive are not carried either; the reach matrix below says which operation each binding carries.

Migrating a deployment between them is a configuration change, not a rewrite: the client speaks the same LwM2M 1.2 interfaces either way, and the server keeps the same stores, the same REST API and the same operator UI. A device that cannot reach a CoAP endpoint can register against a broker instead, and the server treats it like any other client.

The MQTT binding is the LwM2M 1.2 one (OMA-TS-LightweightM2M_Transport §8): the topics are [PREFIX/]lwm2m/(rd|bs)/{endpoint}, the payloads are CBOR, and a client that reached the server over a broker and stated no binding mode of its own is recorded with the MQTT binding code (M).

The reach matrix

Which operation works on which binding. The table is derived from the transport code and from the suites that exercise it: the last column names the suites that prove the row, so every claim in the table is checkable. The matrix and the ETS ledger (compliance/ets-ledger.md) are kept in step — the matrix says what this build carries on each binding, and the ledger says, case by case, what Sirena does against the OMA Enabler Test Specification. Each of the two has a suite of its own that keeps it true.

The coaps+tcp column is the pre-shared-key and certificate listener: a TLS socket on a TCP port. The channel is protected, but it is not DTLS over UDP, and a device that speaks DTLS over UDP cannot reach it. The coaps listener (DTLS 1.2 over UDP, pre-shared-key and certificate modes) is not a column of the matrix yet; int-401 and int-402 prove it, and int-403 proves a device refusing the server's identity.

A cell says one of four things:

  • yes — the binding carries the operation, and a suite proves it on that binding: the suite either drives the operation end to end or pins the binding's wire form for it. A suite is a test of the server workspace or an ETS case script of the compliance workspace — a case script drives its procedure against the live server over the binding it uses, so it proves what that binding carries in the same way.
  • carried — the binding carries the operation, but no suite proves it on that binding. The operation crosses the binding in the direction it needs — the server's request reaches the device, or the device's request reaches the server — but the repository does not show it on the wire.
  • no — the operation does not cross this binding in the direction it needs. Either the binding refuses it outright — the server fails the call at once, so the caller learns that there is no path to the device instead of waiting for a timeout — or the direction the operation needs does not exist there.
  • not served — the binding classifies the request, but the server does not serve it: the request is acknowledged with an empty success response and nothing is done with it.

| Operation | CoAP/UDP | CoAP/TCP | CoAP/TLS | coaps+tcp | HTTP/HTTPS | MQTT | Proven by | | --- | --- | --- | --- | --- | --- | --- | --- | | Client Registration — the device registers with the server | | | | | | | | | Register | yes | yes | yes | yes | yes | yes | coap-udp.test.ts, coap-tcp.test.ts, coap-tls.test.ts, coaps-tcp.test.ts, http.test.ts, https.test.ts, mqtt.test.ts | | Update | yes | yes | yes | carried | yes | yes | coap-udp.test.ts, coap-tcp.test.ts, coap-tls.test.ts, http.test.ts, mqtt.test.ts | | Deregister | yes | yes | yes | carried | yes | yes | coap-udp.test.ts, coap-tcp.test.ts, coap-tls.test.ts, http.test.ts, mqtt.test.ts | | Device Management — the server reaches the device | | | | | | | | | Read | yes | yes | yes | yes | yes | yes | coap-udp.test.ts, coap-tcp-management.test.ts, coap-tls-management.test.ts, coaps-tcp.test.ts, http-transport.test.ts, mqtt.test.ts | | Write (replace) | yes | yes | yes | yes | yes | yes | coap-udp.test.ts, coap-tcp-management.test.ts, coap-tls-management.test.ts, coaps-tcp.test.ts, http.test.ts, mqtt-management.test.ts | | Partial update | yes | yes | yes | yes | yes | yes | coap-udp.test.ts, coap-tcp-management.test.ts, coap-tls-management.test.ts, coaps-tcp.test.ts, http.test.ts, mqtt-management.test.ts | | Execute | yes | yes | yes | yes | yes | yes | coap-tcp-management.test.ts, coap-tls-management.test.ts, coaps-tcp.test.ts, http-transport.test.ts, mqtt-management.test.ts, int-241.ts (the reboot over CoAP/UDP) | | Create | yes | yes | yes | yes | yes | yes | coap-tcp-management.test.ts, coap-tls-management.test.ts, coaps-tcp.test.ts, http-transport.test.ts, mqtt-management.test.ts, int-270.ts (the instance over CoAP/UDP) | | Delete | yes | yes | yes | yes | yes | yes | coap-tcp-management.test.ts, coap-tls-management.test.ts, coaps-tcp.test.ts, http-transport.test.ts, mqtt-management.test.ts, int-290.ts (the instance over CoAP/UDP) | | Discover | yes | yes | yes | yes | yes | yes | coap-tcp-management.test.ts, coap-tls-management.test.ts, coaps-tcp.test.ts, http-transport.test.ts, mqtt-management.test.ts, int-260.ts (the discovery over CoAP/UDP) | | Write-Attributes | yes | yes | yes | yes | yes | yes | coap-tcp-management.test.ts, coap-tls-management.test.ts, coaps-tcp.test.ts, http-transport.test.ts, mqtt-management.test.ts, int-261.ts (the attributes over CoAP/UDP) | | Read-Composite | yes | carried | carried | yes | no | yes | coaps-tcp.test.ts, http-transport.test.ts (the refusal), mqtt-composite.test.ts, int-235.ts (the composite read over CoAP/UDP) | | Write-Composite | yes | yes | yes | yes | no | yes | coap-large-payloads.test.ts, coaps-tcp.test.ts, http-transport.test.ts (the refusal), mqtt-composite.test.ts | | Device Management and Information Reporting — the device reaches the server | | | | | | | | | Read, Write, Execute, Create, Delete, Discover, Write-Attributes, Observe | not served | not served | not served | not served | not served | not served | — | | Information Reporting — the server asks the device to report | | | | | | | | | Observe | yes | yes | yes | yes | no | yes | coap-udp.test.ts, coap-tcp-observe.test.ts, coap-tls-observe.test.ts, coaps-tcp.test.ts, http-transport.test.ts (the refusal), mqtt-observe.test.ts | | Observe-Composite | yes | carried | carried | carried | no | yes | http-transport.test.ts (the refusal), mqtt-composite.test.ts, int-304.ts (the composite observation over CoAP/UDP — the ETS case itself is recorded as planned, because the script does not reproduce its third pass criterion) | | Cancel observation | yes | yes | yes | yes | no | yes | coap-cancellation.test.ts, coap-tcp-observe.test.ts, coap-tls-observe.test.ts, coaps-tcp.test.ts, mqtt-observe.test.ts, int-302.ts (the Reset over CoAP/UDP) | | Information Reporting — the device reports on its own | | | | | | | | | Notify | yes | yes | yes | yes | no | yes | coap-udp.test.ts, coap-tcp-observe.test.ts, coap-tls-observe.test.ts, coaps-tcp.test.ts, http-transport.test.ts (the refusal), mqtt-observe.test.ts | | Send | yes | carried | carried | carried | yes | yes | coap-udp.test.ts, http.test.ts, mqtt.test.ts | | Bootstrap | | | | | | | | | Bootstrap-Request | yes | yes | yes | carried | yes | yes | bootstrap-transports.test.ts, coap-large-payloads.test.ts, mqtt-bootstrap.test.ts, http-transport.test.ts (the inbound classification) | | Bootstrap-Pack-Request | yes | yes | yes | carried | yes | yes | coap-large-payloads.test.ts, bootstrap-pack.test.ts (the HTTP classification), mqtt-bootstrap.test.ts | | Bootstrap-Delete | yes | carried | carried | carried | no | yes | bootstrap-server.test.ts, mqtt-bootstrap.test.ts | | Bootstrap-Write | yes | yes | yes | carried | no | yes | coap-large-payloads.test.ts, mqtt-bootstrap.test.ts | | Bootstrap-Discover | yes | carried | carried | carried | no | yes | bootstrap-server.test.ts, mqtt-bootstrap.test.ts | | Bootstrap-Read | carried | carried | carried | carried | no | carried | — | | Bootstrap-Finish | yes | carried | carried | carried | no | yes | bootstrap-server.test.ts, mqtt-bootstrap.test.ts |

Five notes on the table:

  • The four CoAP bindings share one mapping — the method, the path and the options of a request are read the same way over UDP, over TCP, over TLS and over the protected listener (src/transport/internal/CoapMapping.ts). The ETS cases the matrix cites drive their procedure against the live server over CoAP/UDP, so a cell the matrix marks yes there is proved by the case the last column names. A cell marked carried over CoAP/UDP — the Bootstrap-Read — is carried by the mapping the CoAP/TCP and the CoAP/TLS suites drive; no case drives it over UDP.
  • The cancellation of an observation has two wire forms: a CoAP Reset over UDP (RFC 7252 §3.2) and the explicit request of RFC 7641 §3.6 over the reliable bindings, which the device acknowledges. The MQTT binding has its own cancel operation. The CoAP/UDP suite ends its observation without asserting the Reset on the wire, but the ETS case int-302.ts does assert it — the device's observation is gone after the Reset reaches it — so the CoAP/UDP cell is yes.
  • The coaps+tcp binding carries the server-originated requests over the protected connection the device opened: the whole device-management surface, the composite operations and the observation travel on it, and the device's answers come back on the same connection. The cancellation of an observation is the CoAP Reset there — the server writes it on the connection the device opened, and the device never answers it. The composite observation and the bootstrap steps are carried rather than yes: the binding carries them, but no suite drives them over the protected channel. The device-initiated operations — the Update, the Deregister, the Send, the Bootstrap-Request — are carried there as well: the device's request reaches the server. The channel itself is the one the paragraph above describes: TLS on a TCP port, not DTLS over UDP.
  • The Bootstrap-Delete, the Bootstrap-Discover and the Bootstrap-Finish are carried over CoAP/TCP and CoAP/TLS: the large-payload suite drives the whole sequence on those connections, but it asserts only the Bootstrap-Write, so nothing pins the other steps there. The CoAP/UDP suite (bootstrap-server.test.ts) asserts every step of the sequence on the wire — the two Deletes, the two Writes, the Discover and the Finish — which is why those cells are yes while the two reliable bindings are carried.
  • OSCORE is not a binding of its own: it is a decorator over a CoAP transport, so every CoAP cell above holds for an OSCORE-protected channel too (see OSCORE-secured bootstrap and registration).

What no binding carries

A missing capability reads as a documented fact, not as a bug report. These are the gaps the matrix records:

  • The coaps listener in the matrix. The matrix's coaps+tcp column is a TLS socket on a TCP port, which a device that speaks DTLS over UDP cannot reach. The coaps listener (DTLS 1.2 over UDP, pre-shared-key and certificate modes) is proven by int-401, int-402 and int-403, not by a column of this matrix.
  • Server push over HTTP. An observation notification has no place in the request/reply model of plain HTTP/1.1, so an observation does not reach an HTTP device. The HTTP binding refuses the operation at once, and the caller learns that the device cannot be observed instead of waiting for a notification that will never come. The other half follows: with no observation, no notification is ever due, so the Notify direction is empty over HTTP as well.
  • The composite operations over HTTP. A Read-Composite and the composite observation are a CoAP FETCH, and a Write-Composite is a CoAP iPATCH; HTTP/1.1 has neither, so the HTTP binding refuses all three.
  • The bootstrap sequence over HTTP. A Bootstrap-Request is classified and reaches the server, but nothing serves it, and every step the server sends to the device — the Delete, the Write, the Discover, the Read, the Finish — is refused, so the sequence cannot run.
  • The device-initiated direction of the Device Management and the Information Reporting interfaces. A device that asks the server to read, write, write-attributes, execute, create, delete, discover or observe something is answered with an empty success response, and nothing is done with the request: the server serves those interfaces in the server→device direction only. The Send operation and the Bootstrap interface are the device-initiated operations the server does serve.

What the server reports

The server names the protocols it is running on its health endpoint and in the operator UI:

curl http://localhost:8080/health
{
  "status": "ok",
  "uptime": 42,
  "protocols": [
    { "kind": "coap-udp", "host": "0.0.0.0", "port": 5683 },
    { "kind": "mqtt", "url": "mqtt://broker.internal:1883" }
  ]
}

The list is what the deployment is actually serving: the address each socket-bound transport is bound to (the port the OS assigned, when the deployment asked for an ephemeral one), and the broker URL an MQTT transport connects to — without its credentials, because the health endpoint needs no authentication. The operator UI shows the same list, so an operator can see what a running server speaks without reading its configuration.

Running the server

Configuration

Every runner setting resolves in one order:

  1. the command-line flag,
  2. the real environment variable,
  3. the .env file in the working directory,
  4. the built-in default.

The environment file is read through the runtime's built-in API, so no package enters the dependency tree. A variable that is already set in the environment wins over the value in the file, and a flag wins over both. A missing file is not an error. A different file is named with --environment-file — not --env-file, which the Node runtime owns and would handle before the runner ever starts.

The runners read the file; the library never does. .env.example lists the settings and their defaults.

The sirena binary starts the management server (CoAP/UDP by default, plus the operator REST API) and the sirena-bootstrap binary starts the bootstrap server. Both take flags with environment-variable fallbacks.

LwM2M 1.2 over MQTT is opt-in: the server starts an MQTT transport only when a broker URL is configured.

| Binary | Flag | Environment variable | Default | Meaning | | --- | --- | --- | --- | --- | | sirena | --coap-tcp-port | COAP_TCP_PORT | 0 | The port the CoAP/TCP listener binds. 0 means the listener is not started — the CoAP/TCP binding is opt-in, so the default leaves it off. This is the opposite of the coaps+tcp listener below, whose 0 is an OS-assigned port. | | sirena | --coaps-port | COAPS_PORT | (unset) | The UDP port the coaps listener (CoAP over DTLS 1.2) binds. Unset means the listener is not started; 0 is an OS-assigned port. Without the certificate material below the devices' pre-shared keys come from the security store. | | sirena | --coaps-cert | COAPS_CERT | (unset) | The PEM file the coaps listener's server certificate is read from. It must be an ECDSA (EC) certificate: an RSA or unparseable one fails the startup. Goes with --coaps-key. | | sirena | --coaps-key | COAPS_KEY | (unset) | The PEM file the coaps listener's EC private key is read from; it must belong to --coaps-cert. | | sirena | --coaps-ca | COAPS_CA | (unset) | The PEM file the authority bundle is read from. A configured authority is used: the device's certificate is requested and validated against it. Without it a certificate-mode listener serves unauthenticated devices. | | sirena | --coaps-request-client-cert | COAPS_REQUEST_CLIENT_CERT | (unset) | Whether the coaps listener requests a client certificate: true, false (never ask; every device that completes the handshake is served) or unset (the authority decides). A request without an authority is refused at startup. | | sirena | --coaps-tcp-port | COAPS_TCP_PORT | (unset) | The port the coaps+tcp listener (CoAP over TLS on TCP) binds. Unset means the listener is not started; 0 is an OS-assigned port. The listener is secured with the certificate material below when it is given any; without it, the devices' pre-shared keys come from the security store. | | sirena | --coaps-tcp-cert | COAPS_TCP_CERT | (unset) | The PEM file the coaps+tcp listener's server certificate is read from. Set with --coaps-tcp-key, it secures the listener with certificates instead of with the pre-shared keys of the security store. | | sirena | --coaps-tcp-key | COAPS_TCP_KEY | (unset) | The PEM file the coaps+tcp listener's server private key is read from. It goes with --coaps-tcp-cert. | | sirena | --coaps-tcp-ca | COAPS_TCP_CA | (unset) | The PEM file the authority bundle is read from — the trust anchor the device's certificate is validated against. A configured authority is used: the device's certificate is requested and validated against it. | | sirena | --coaps-tcp-request-client-cert | COAPS_TCP_REQUEST_CLIENT_CERT | (unset) | Whether the coaps+tcp listener requests a client certificate. Unset leaves the decision to the authority — a configured authority means the device's certificate is requested. false turns the request off: the device is never asked for a certificate and every device that completes the handshake is served. true asks for it explicitly; a request without an authority is refused when the runner starts, and a value that is neither true nor false is refused too. | | sirena | --mqtt-broker-url | MQTT_BROKER_URL | (empty) | The broker the management server talks to. Empty means no MQTT transport is started. | | sirena | --bootstrap-mqtt-broker-url | BOOTSTRAP_MQTT_BROKER_URL | (empty) | The broker the combined bootstrap server talks to. | | sirena-bootstrap | --mqtt-broker-url | BOOTSTRAP_MQTT_BROKER_URL | (empty) | The broker the standalone bootstrap server talks to. | | sirena | --mqtt-topic-prefix | MQTT_TOPIC_PREFIX | (empty) | The topic prefix (the tenant segment) the management server serves. Empty means the bare lwm2m/... topics. | | sirena | --bootstrap-mqtt-topic-prefix | BOOTSTRAP_MQTT_TOPIC_PREFIX | (empty) | The topic prefix the combined bootstrap server serves. | | sirena-bootstrap | --mqtt-topic-prefix | BOOTSTRAP_MQTT_TOPIC_PREFIX | (empty) | The topic prefix the standalone bootstrap server serves. |

A deployment that shares a broker with others isolates itself on a topic prefix: the server serves PREFIX/lwm2m/... and ignores every other tenant's topics. A server without a prefix serves the bare lwm2m/... topics.

The management server and the bootstrap server take independent broker URLs, so the two interfaces can be pointed at different brokers or run as separate processes. A broker that cannot be reached fails the startup with a message naming the broker, rather than leaving a half-configured server behind.

sirena --mqtt-broker-url mqtt://broker.internal:1883
sirena-bootstrap --mqtt-broker-url mqtt://bootstrap-broker.internal:1883

The broker client (mqtt) is an optional peer dependency: install it when you want the MQTT transport. The package's main entry point exports the MQTT transport and its option types, and its runtime never loads the broker client — it is imported when a connection is opened. A TypeScript consumer that turns skipLibCheck off needs the peer packages' type declarations to type-check the entry point, the same way it already does for the CoAP transports.

Dependency policy

The library (@sirena-lwm2m/server) has zero mandatory production dependencies. Optional adapters (express, ws) are declared as optionalDependencies and loaded only via subpath imports (@sirena-lwm2m/server/transport/http, etc.). Peer dependencies (@sirena-lwm2m/coap, mqtt) must be installed by the consumer when needed. SQLite support uses the built-in node:sqlite module (Node 24+) — no install step required.

A CI job (.github/workflows/dep-tree-guard.yml) enforces this on every PR and push to main. It packs the library, installs it in a clean directory, and fails the build if any of the following appear in the resulting dep tree: express, ws, mqtt, aedes, @sirena-lwm2m/coap.

The Story

In the waters below Sorrento's cliffs, the Sirens once lured sailors with signals no one could ignore. Somewhere between the fourth espresso and a heated debate about CBOR encoding, a group of engineers sitting on a terrace above the Tyrrhenian Sea realized they were building the same thing — a way for tiny, voiceless devices to sing clearly across any network. Sirena was named that afternoon. Not for the danger, but for the clarity of the signal.