feat: Native OSCORE (RFC 8613) Integration

[stoprocent]

feat: Native OSCORE (RFC 8613) Integration

Summary

Add built-in OSCORE (Object Security for Constrained RESTful Environments) support to node-coap using the coap-oscore package. OSCORE provides end-to-end encryption at the CoAP message level, operating on raw binary buffers so that all existing CoAP features — block transfers, observe, caching, retransmissions — work transparently over encrypted channels.

Changes

New Files

File	Description
lib/oscore.ts	SecurityContextManager — server-side registry for OSCORE contexts, keyed by recipientId + optional idContext. Manages token-to-context bindings for response encoding and aggregates SSN change events for persistence.
lib/oscore_helpers.ts	OSCORE option parsing utilities — extracts and parses the OSCORE option (number 9) from CoAP packets per RFC 8613 Section 6.1 (KID, KID Context, PIV fields).
test/oscore.ts	Comprehensive test suite with 12 tests covering all major scenarios.

Modified Files

File	Changes
package.json	Added coap-oscore dependency
models/models.ts	Extended AgentOptions (oscoreOnly), CoapServerOptions (oscoreContexts, oscoreOnly), and MiddlewareParameters (OSCORE context/metadata fields) — all optional, zero breaking changes
lib/incoming_message.ts	Added oscoreContext property and isOscore getter for server-side request introspection
lib/agent.ts	OSCORE context map with addOscoreContext()/removeOscoreContext(), async decode on incoming messages via _handlePlainMessage() extraction, sender.send() wrapping for transparent outgoing encryption, observe _disableFiltering for OSCORE streams, Echo auto-retry for 4.01+Echo responses
lib/middlewares.ts	New oscoreDecryptRequest middleware — detects OSCORE option, looks up context by KID, decodes raw buffer, re-parses inner packet, binds token for response encoding, handles Echo challenge (status 201) for first-request-after-reboot. Updated handleServerRequest to forward OSCORE metadata.
lib/server.ts	_oscoreContextManager and _oscoreOnly fields, middleware pipeline insertion, _finishSendResponse() helper extracted for async OSCORE response encoding, token lifecycle management (unbind on response/observe finish), updated _handle() signature to accept OSCORE metadata, dynamic addOscoreContext()/removeOscoreContext() with lazy middleware initialization
index.ts	Export SecurityContextManager, re-export OSCORE, OscoreContext, OscoreContextStatus types from coap-oscore
README.md	Added RFC 8613 to introduction, new OSCORE section with client/server/observe/dynamic examples, documented all new API surface (server options, agent methods, IncomingMessage properties, SecurityContextManager)

Design Decisions

1. OSCORE at buffer boundaries — Encrypt after generate(), decrypt before parse(). This keeps all existing CoAP logic working on decrypted packets with zero modifications to block transfer, observe, or caching code.

2. Agent wraps sender.send() — Instead of modifying every generate() call site, the agent monkey-patches sender.send() to encrypt all outgoing buffers. This automatically handles initial requests, block1 segments, block2 continuations, and retransmissions (RetrySend stores the already-encoded buffer).

3. Server uses middleware pipeline — oscoreDecryptRequest slots into the existing fastseries middleware chain between parseRequest and handleServerRequest. Uses .then()/.catch() (not async/await) for fastseries compatibility.

4. Per-block OSCORE — Per RFC 8613 §4.1.3.4, each block-wise message is independently OSCORE-protected. The sender.send() wrapping handles this automatically.

5. All additions are optional — Every new field is optional. A server/agent without OSCORE configuration behaves identically to before.

Test Coverage

Test	Description
GET round-trip	Basic GET with OSCORE encryption/decryption, verifies isOscore and oscoreContext.senderId
POST round-trip	POST with payload, OSCORE-protected in both directions
Mixed secure/insecure	Server handles both OSCORE and plaintext requests correctly
oscoreOnly server	Server rejects plaintext with 4.01
oscoreOnly agent	Agent throws on requests to peers without context
Multiple contexts on agent	Separate OSCORE contexts route correctly to different peers
Multiple contexts on server	Server handles requests from different OSCORE clients
Unknown client	Server returns 4.01 for OSCORE request with unregistered KID
SSN persistence	Verifies ssn events fire via SecurityContextManager
Dynamic add/remove (agent)	Add and remove contexts at runtime
Dynamic add/remove (server)	Add context at runtime on server created without OSCORE
Observe with OSCORE	Observe notifications encrypted transparently, _disableFiltering active

Results: 486 passing (474 existing + 12 new), 6 pending (unchanged), 0 failing

[coveralls]

Pull Request Test Coverage Report for Build 22158602291

Details

• 474 of 653 (72.59%) changed or added relevant lines in 7 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-2.9%) to 87.263%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
lib/server.ts	117	124	94.35%
lib/oscore.ts	116	133	87.22%
lib/oscore_helpers.ts	71	92	77.17%
lib/agent.ts	90	135	66.67%
lib/middlewares.ts	65	154	42.21%

Totals
Change from base Build 19027860563:	-2.9%
Covered Lines:	3260
Relevant Lines:	3710

---

💛 - Coveralls

[stoprocent]

Hey, is there any plan to review and merge? If not I will do a @stoprocent/node-coap but i rather contribute here :)

[stoprocent]

Hey guys, if you cannot review I will move to new namespace on npm. Just please let me know I understand everyones busy. @JKRhb @Apollon77

[JKRhb]

Hi @stoprocent, sorry for getting back to you earlier! I will probably have the time to do a review by tomorrow, I hope that works for you :) In any case thank you for working on this feature, having an OSCORE implementation in node-coap is pretty exciting! :)

[stoprocent]

No worries! I don’t want to rush the review. That’s the last thing I’d want to do. I just wanted to at least get it started.

[JKRhb]

Sorry for the delay! See a couple of initial comments below, I will continue the review in the upcoming days.

[JKRhb]

I think the version should only be bumped after merging this PR.

[JKRhb]

Seems like the CI is failing now since the semicolons were necessary after all :/ Sorry for the mistake, could you revert these two particular changes (or find a different solution that does not involve the semicolons)? Thank you!