fix(oscore): address open review items from PR #397

- server: hoist _oscoreOnly out of the oscoreContexts gate so the flag
  is honoured when contexts are added at runtime via addOscoreContext()
- agent: drop unsolicited plaintext datagrams in oscoreOnly mode for
  peers that have no registered context (defense in depth)
- middlewares: drop the (oscore as any).clearRebootRecovery() cast; the
  method is publicly typed in coap-oscore ≥ 2.2.1
- middlewares: wrap parseOscoreOption() in try/catch so malformed OSCORE
  options surface as 4.01 Unauthorized rather than bubbling through the
  middleware chain as a 5.00
- oscore_helpers: reject reserved high flag bits (0xe0) and PIV lengths
  6 and 7 per RFC 8613 §6.1
- oscore: give _pendingEchoNonces entries a 30s TTL so peers that never
  reply to an Echo challenge can't accumulate in the map; matched
  storePendingEcho/clearPendingEcho/getPendingEcho accessors accordingly
- helpers: introduce ECHO_OPTION constant (RFC 9175 option 252) and use
  it everywhere instead of the magic string '252'
- agent: switch import crypto = require('crypto') to ESM-style import
  for consistency with the rest of the codebase
- README: collapse the two-require server example into a single require
  from 'coap' (OscoreContextStatus is re-exported)
- package.json: revert version bump to 1.4.2 (matches master), bump
  coap-oscore floor to ^2.2.2 (latest published)

Adds 4 new tests covering the changes above:
- oscoreOnly applied via addOscoreContext() at runtime
- oscoreOnly agent silently drops unsolicited inbound plaintext
- malformed OSCORE option (reserved PIV length) → 4.01
- pending Echo nonce evicted after TTL

All 24 OSCORE tests pass; 492 in the wider suite (IPv6 tests excluded —
broken in sandbox, unaffected by these changes).

Author: claude

README.md

@@ -178,8 +178,7 @@ req.end()
 
 ```js
 const coap = require('coap')
-const { OSCORE, SecurityContextManager } = require('coap')
-const { OscoreContextStatus } = require('coap-oscore')
+const { OSCORE, OscoreContextStatus, SecurityContextManager } = require('coap')
 
 const contexts = new SecurityContextManager()
 

lib/agent.ts

@@ -6,7 +6,7 @@
  * See the included LICENSE file for more details.
  */
 
-import crypto = require('crypto')
+import crypto from 'crypto'
 import { Socket, createSocket } from 'dgram'
 import { AgentOptions, CoapRequestParams, Block, Parameters } from '../models/models'
 import { EventEmitter } from 'events'
@@ -21,7 +21,7 @@ import { SegmentedTransmission } from './segmentation'
 import { parseBlockOption } from './block'
 import { AddressInfo } from 'net'
 import { parameters, createParameters } from './parameters'
-import { hasOscoreOption } from './oscore_helpers'
+import { hasOscoreOption, ECHO_OPTION } from './oscore_helpers'
 
 interface OscoreRsinfo extends AddressInfo {
     oscore?: boolean
@@ -94,6 +94,11 @@ class Agent extends EventEmitter {
         this._sock.on('message', (msg, rsinfo) => {
             const oscoreCtx = this._getOscoreContext(rsinfo.address, rsinfo.port)
             if (oscoreCtx == null) {
+                if (this._oscoreOnly) {
+                    // Drop unsolicited plaintext from peers with no context
+                    // when the agent is in OSCORE-only mode.
+                    return
+                }
                 this._handlePlainMessage(msg, rsinfo)
                 return
             }
@@ -420,7 +425,7 @@ class Agent extends EventEmitter {
 
         // Echo auto-retry for OSCORE peers
         if (packet.code === '4.01' && req != null && this._getOscoreContext(rsinfo.address, rsinfo.port) != null) {
-            const echoOpt = getOption(packet.options, '252')
+            const echoOpt = getOption(packet.options, ECHO_OPTION)
             if (echoOpt != null) {
                 // Limit Echo retries to prevent infinite loops from malicious servers
                 const retryCount = (req as any)._echoRetries ?? 0
@@ -441,7 +446,7 @@ class Agent extends EventEmitter {
                             }
                         }
                     }
-                    retryReq.setOption('252', echoOpt)
+                    retryReq.setOption(ECHO_OPTION, echoOpt)
 
                     ;(retryReq as any)._echoRetries = retryCount + 1
 
@@ -485,7 +490,7 @@ class Agent extends EventEmitter {
             response = new ObserveStream(packet, rsinfo, outSocket)
             if (rsinfo.oscore === true) {
                 (response as ObserveStream)._disableFiltering = true
-                ;(response as ObserveStream).oscoreProtected = true
+                response.oscoreProtected = true
             }
             response.on('close', () => {
                 this._tkToReq.delete(packet.token.toString('hex'))

lib/middlewares.ts

@@ -11,7 +11,7 @@ import { parse, generate, ParsedPacket } from 'coap-packet'
 import { Socket } from 'dgram'
 import { or, isOption, getOption } from './helpers'
 import { MiddlewareParameters } from '../models/models'
-import { getOscoreOptionValue, parseOscoreOption } from './oscore_helpers'
+import { getOscoreOptionValue, parseOscoreOption, ECHO_OPTION } from './oscore_helpers'
 
 type middlewareCallback = (nullOrError: null | Error) => void
 
@@ -133,7 +133,18 @@ export function oscoreDecryptRequest (request: MiddlewareParameters, next: middl
         return next(null)
     }
 
-    const { kid, kidContext } = parseOscoreOption(oscoreOptValue)
+    let kid: Buffer | null
+    let kidContext: Buffer | null
+    try {
+        ({ kid, kidContext } = parseOscoreOption(oscoreOptValue))
+    } catch {
+        // Malformed OSCORE option (reserved bits, PIV length out of range, etc.)
+        request.server._sendError(
+            Buffer.from('Unauthorized'),
+            request.rsinfo, request.packet, '4.01'
+        )
+        return
+    }
     const ctxMgr = request.server._oscoreContextManager
 
     if (ctxMgr == null || kid == null) {
@@ -179,7 +190,7 @@ export function oscoreDecryptRequest (request: MiddlewareParameters, next: middl
                 if (decrypted != null) {
                     try {
                         const innerPacket = parse(decrypted)
-                        const echoVal = getOption(innerPacket.options, '252' as any)
+                        const echoVal = getOption(innerPacket.options, ECHO_OPTION)
                         if (Buffer.isBuffer(echoVal)) {
                             innerEcho = echoVal
                         }
@@ -197,8 +208,7 @@ export function oscoreDecryptRequest (request: MiddlewareParameters, next: middl
                     crypto.timingSafeEqual(innerEcho, storedNonce)
                 ) {
                     // Echo verified — complete the reboot recovery
-                    // Note: clearRebootRecovery() is added in the concurrent node-oscore update
-                    ;(oscore as any).clearRebootRecovery()
+                    oscore.clearRebootRecovery()
                     ctxMgr.clearPendingEcho(kid, kidContext ?? undefined)
 
                     // Continue processing with the decrypted inner message
@@ -227,7 +237,7 @@ export function oscoreDecryptRequest (request: MiddlewareParameters, next: middl
                     ack: request.packet?.confirmable === true,
                     messageId: request.packet?.messageId,
                     token: request.packet?.token,
-                    options: [{ name: '252' as any, value: echoNonce }]
+                    options: [{ name: ECHO_OPTION as any, value: echoNonce }]
                 })
 
                 oscore.encode(innerResponse)

lib/oscore.ts

@@ -16,9 +16,13 @@ import type { OSCORE } from 'coap-oscore'
  */
 export class SecurityContextManager extends EventEmitter {
     private static readonly MAX_TOKEN_BINDINGS = 10000
+    // Echo challenges only need to live long enough for the client to
+    // round-trip the nonce back; if the client never replies, the entry
+    // is evicted so the map can't grow unbounded.
+    private static readonly PENDING_ECHO_TTL_MS = 30_000
     private _contexts: Map<string, OSCORE>
     private _tokenToContext: Map<string, OSCORE>
-    private _pendingEchoNonces: Map<string, Buffer>
+    private _pendingEchoNonces: Map<string, { nonce: Buffer, timer: NodeJS.Timeout }>
 
     constructor () {
         super()
@@ -98,26 +102,42 @@ export class SecurityContextManager extends EventEmitter {
 
     /**
      * Store a pending Echo nonce for a given security context.
+     * The entry self-evicts after PENDING_ECHO_TTL_MS to prevent the map
+     * from accumulating entries when peers never reply to the challenge.
      */
     storePendingEcho (recipientId: Buffer, idContext: Buffer | undefined, nonce: Buffer): void {
         const key = this._toKey(recipientId, idContext)
-        this._pendingEchoNonces.set(key, nonce)
+        const existing = this._pendingEchoNonces.get(key)
+        if (existing != null) {
+            clearTimeout(existing.timer)
+        }
+        const timer = setTimeout(() => {
+            this._pendingEchoNonces.delete(key)
+        }, SecurityContextManager.PENDING_ECHO_TTL_MS)
+        if (typeof timer.unref === 'function') {
+            timer.unref()
+        }
+        this._pendingEchoNonces.set(key, { nonce, timer })
     }
 
     /**
      * Retrieve the pending Echo nonce for a given security context.
      */
     getPendingEcho (recipientId: Buffer, idContext: Buffer | undefined): Buffer | undefined {
         const key = this._toKey(recipientId, idContext)
-        return this._pendingEchoNonces.get(key)
+        return this._pendingEchoNonces.get(key)?.nonce
     }
 
     /**
      * Clear the pending Echo nonce for a given security context.
      */
     clearPendingEcho (recipientId: Buffer, idContext: Buffer | undefined): void {
         const key = this._toKey(recipientId, idContext)
-        this._pendingEchoNonces.delete(key)
+        const entry = this._pendingEchoNonces.get(key)
+        if (entry != null) {
+            clearTimeout(entry.timer)
+            this._pendingEchoNonces.delete(key)
+        }
     }
 
     private _toKey (recipientId: Buffer, idContext?: Buffer): string {

lib/oscore_helpers.ts

@@ -13,6 +13,16 @@ const OSCORE_OPTION_NUMBER = 9
 const FLAG_KID = 0x08
 const FLAG_KID_CTX = 0x10
 const FLAG_PIV_MASK = 0x07
+// Bits 5-7 of the OSCORE option flag byte are reserved per RFC 8613 §6.1
+// and MUST be 0 in a valid option.
+const FLAG_RESERVED_MASK = 0xe0
+// PIV (Partial IV) length is encoded in the low 3 bits; values 6 and 7 are
+// reserved per RFC 8613 §6.1.
+const MAX_PIV_LEN = 5
+
+// RFC 9175 Echo option number (used as the OSCORE reboot-recovery challenge
+// per RFC 8613 Appendix B.1.2).
+export const ECHO_OPTION = '252'
 
 export interface OscoreOptionFields {
     kid: Buffer | null
@@ -53,7 +63,14 @@ export function parseOscoreOption (value: Buffer): OscoreOptionFields {
     let offset = 0
     const flags = value[offset++]
 
+    if ((flags & FLAG_RESERVED_MASK) !== 0) {
+        throw new Error('Malformed OSCORE option: reserved flag bits set')
+    }
+
     const pivLen = flags & FLAG_PIV_MASK
+    if (pivLen > MAX_PIV_LEN) {
+        throw new Error('Malformed OSCORE option: PIV length reserved')
+    }
     let piv: Buffer | null = null
     if (pivLen > 0) {
         if (offset + pivLen > value.length) {

lib/server.ts

@@ -152,9 +152,10 @@ class CoAPServer extends EventEmitter {
                 this._parameters.sendAcksForNonConfirmablePackets
         }
 
+        this._oscoreOnly = this._options.oscoreOnly ?? false
+
         if (this._options.oscoreContexts != null) {
             this._oscoreContextManager = this._options.oscoreContexts
-            this._oscoreOnly = this._options.oscoreOnly ?? false
             this._middlewares.push(oscoreDecryptRequest)
         }
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "coap",
-  "version": "1.6.0",
+  "version": "1.4.2",
   "description": "A CoAP library for node modelled after 'http'",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -57,7 +57,7 @@
     "bl": "^6.0.12",
     "@types/readable-stream": "^4.0.14",
     "capitalize": "^2.0.4",
-    "coap-oscore": "^2.2.1",
+    "coap-oscore": "^2.2.2",
     "coap-packet": "^1.1.1",
     "debug": "^4.3.5",
     "fastseries": "^2.0.0",

test/oscore.ts

@@ -1078,4 +1078,135 @@ describe('OSCORE', function () {
             })
         }).timeout(2000)
     })
+
+    describe('oscoreOnly applied via addOscoreContext', function () {
+        it('should reject plaintext after a context is added at runtime', function (done) {
+            const port = nextPort()
+            const { server: serverOscore } = createOscorePair()
+
+            // Server is created with oscoreOnly:true but no contexts yet
+            const server = trackServer(createServer({ oscoreOnly: true }))
+            server.on('request', () => {
+                done(new Error('Should not receive request — oscoreOnly should reject plaintext'))
+            })
+
+            server.listen(port, () => {
+                server.addOscoreContext(serverOscore, Buffer.from('01', 'hex'))
+
+                const plainAgent = trackAgent(new Agent({ type: 'udp4' }))
+                const req = request({
+                    hostname: '127.0.0.1',
+                    port,
+                    pathname: '/test',
+                    agent: plainAgent
+                })
+                req.on('response', (res) => {
+                    expect(res.code).to.equal('4.01')
+                    done()
+                })
+                req.end()
+            })
+        })
+    })
+
+    describe('oscoreOnly agent drops inbound plaintext', function () {
+        it('should silently drop unsolicited plaintext from peers with no context', function (done) {
+            const agent = trackAgent(new Agent({ type: 'udp4', oscoreOnly: true }))
+            const agentSock: any = (agent as any)._sock
+            let errored = false
+            agent.on('error', () => { errored = true })
+
+            agentSock.bind(0, '127.0.0.1', () => {
+                const agentPort = agentSock.address().port
+                const sender = dgram.createSocket('udp4')
+                const datagram = generate({
+                    code: '2.05',
+                    payload: Buffer.from('plain'),
+                    messageId: 1,
+                    token: Buffer.alloc(0)
+                })
+                sender.send(datagram, agentPort, '127.0.0.1', () => {
+                    sender.close()
+                    // Give the agent a tick to (not) emit anything
+                    setTimeout(() => {
+                        try {
+                            expect(errored).to.equal(false)
+                            done()
+                        } catch (e) {
+                            done(e as Error)
+                        }
+                    }, 100)
+                })
+            })
+        }).timeout(2000)
+    })
+
+    describe('PIV validation', function () {
+        it('should reject OSCORE options with reserved PIV length', function (done) {
+            const port = nextPort()
+            const { server: serverOscore } = createOscorePair()
+            const contexts = new SecurityContextManager()
+            contexts.addContext(serverOscore, Buffer.from('01', 'hex'))
+
+            const server = trackServer(createServer({ oscoreContexts: contexts }))
+            server.on('request', () => {
+                done(new Error('Should not receive request — malformed PIV must be rejected'))
+            })
+
+            server.listen(port, () => {
+                // Hand-craft a CoAP packet with an OSCORE option whose flag byte
+                // encodes PIV length 6 (reserved per RFC 8613 §6.1).
+                const oscoreValue = Buffer.concat([
+                    Buffer.from([0x06]), // flags: pivLen=6
+                    Buffer.alloc(6) // arbitrary PIV bytes
+                ])
+                const packet = generate({
+                    code: '0.01',
+                    confirmable: true,
+                    messageId: 1,
+                    token: Buffer.from([0xaa]),
+                    options: [{ name: 'OSCORE' as any, value: oscoreValue }]
+                })
+                const client = dgram.createSocket('udp4')
+                client.on('message', (msg) => {
+                    try {
+                        const reply = parse(msg)
+                        expect(reply.code).to.equal('4.01')
+                        client.close()
+                        done()
+                    } catch (e) {
+                        client.close()
+                        done(e as Error)
+                    }
+                })
+                client.send(packet, port, '127.0.0.1')
+            })
+        }).timeout(2000)
+    })
+
+    describe('pending Echo nonce TTL', function () {
+        it('should evict stored Echo nonces after the TTL elapses', function (done) {
+            // Shortcut the TTL for the test by monkey-patching the static
+            // (readonly is TS-only; the value is captured at store time).
+            const originalTtl = (SecurityContextManager as any).PENDING_ECHO_TTL_MS
+            ;(SecurityContextManager as any).PENDING_ECHO_TTL_MS = 50
+
+            const contexts = new SecurityContextManager()
+            const recipientId = Buffer.from('01', 'hex')
+            const nonce = Buffer.from('cafebabe', 'hex')
+            contexts.storePendingEcho(recipientId, undefined, nonce)
+            expect(contexts.getPendingEcho(recipientId, undefined)).to.deep.equal(nonce)
+
+            setTimeout(() => {
+                try {
+                    expect(contexts.getPendingEcho(recipientId, undefined)).to.equal(undefined)
+                    done()
+                } catch (e) {
+                    done(e as Error)
+                } finally {
+                    ;(SecurityContextManager as any).PENDING_ECHO_TTL_MS = originalTtl
+                }
+            }, 150)
+        }).timeout(2000)
+    })
 })