@totemsdk/edge-coap 0.1.0 → 0.3.0

package/dist/cjs/gateway.js

@@ -0,0 +1,511 @@
+"use strict";
+/**
+ * CoAP Edge Gateway — wires a CoapTransportPort into an EdgeRuntime.
+ *
+ * Requests are CON messages matched to responses by token and remote endpoint
+ * (RFC 7252 §5.3). Confirmable requests are retransmitted with exponential
+ * backoff until acknowledged or until the request deadline expires. An empty
+ * ACK keeps the request pending for a separate response, which is acknowledged
+ * before being handed to the caller.
+ *
+ * RFC 7641 observations keep a token registered after the initial response;
+ * later notifications with a fresh 24-bit Observe sequence are delivered to the
+ * caller and confirmable notifications are acknowledged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCoapGateway = createCoapGateway;
+const codec_js_1 = require("./codec.js");
+const DEFAULT_TIMING = {
+    requestTimeoutMs: 10000,
+    ackTimeoutMs: 2000,
+    maxRetransmits: 4,
+};
+/** RFC 7641 §3.4 freshness window for observation sequence numbers. */
+const OBSERVATION_FRESHNESS_MS = 128000;
+const OBSERVATION_SEQUENCE_MODULO = 16777216;
+const OBSERVATION_HALF_RANGE = 8388608;
+function createCoapGateway(config) {
+    let status = 'stopped';
+    let unsubMsg;
+    let unsubErr;
+    const pending = new Map();
+    const pendingByMessageId = new Map();
+    const observations = new Map();
+    let messageId = 0;
+    function detach(key, entry) {
+        entry.settled = true;
+        clearTimeout(entry.deadline);
+        if (entry.retransmit)
+            clearTimeout(entry.retransmit);
+        entry.retransmit = undefined;
+        if (pending.get(key) === entry)
+            pending.delete(key);
+        if (pendingByMessageId.get(entry.messageId) === key)
+            pendingByMessageId.delete(entry.messageId);
+    }
+    function settle(key, entry, error, data) {
+        if (entry.settled)
+            return;
+        detach(key, entry);
+        if (error)
+            entry.resolve({ ok: false, error: error.message });
+        else
+            entry.resolve({ ok: true, data: data ?? { payload: new Uint8Array(0) } });
+    }
+    const context = {
+        transport: config.transport,
+        security: config.security,
+        pending,
+        pendingByMessageId,
+        observations,
+        nextMessageId: () => {
+            for (let candidates = 0; candidates <= 0xffff; candidates++) {
+                const id = messageId;
+                messageId = (messageId + 1) & 0xffff;
+                if (!pendingByMessageId.has(id))
+                    return id;
+            }
+            throw new Error('No free CoAP message ids');
+        },
+        timing: {
+            requestTimeoutMs: config.timing?.requestTimeoutMs ?? DEFAULT_TIMING.requestTimeoutMs,
+            ackTimeoutMs: config.timing?.ackTimeoutMs ?? DEFAULT_TIMING.ackTimeoutMs,
+            maxRetransmits: config.timing?.maxRetransmits ?? DEFAULT_TIMING.maxRetransmits,
+        },
+        settle,
+    };
+    const blockwise = {
+        enabled: config.blockwise?.enabled ?? true,
+        blockSize: normalizeBlockSize(config.blockwise?.blockSize ?? 1024),
+        maxBodySize: config.blockwise?.maxBodySize ?? 1024 * 1024,
+    };
+    if (!Number.isInteger(blockwise.maxBodySize) || blockwise.maxBodySize < 16) {
+        throw new Error('Invalid blockwise maxBodySize');
+    }
+    function findPending(remote, tokenKey, msgId) {
+        const key = tokenKey ?? (msgId === undefined ? undefined : pendingByMessageId.get(msgId));
+        if (!key)
+            return undefined;
+        const entry = pending.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.host !== remote.host || entry.port !== remote.port)
+            return undefined;
+        return { key, entry };
+    }
+    function acknowledge(remote, msgId) {
+        const ack = (0, codec_js_1.encodeCoap)({
+            type: 'ACK', messageId: msgId, token: new Uint8Array(0), path: [],
+            payload: new Uint8Array(0), remote, receivedAt: Date.now(),
+        });
+        void Promise.resolve(config.transport.send(remote.host, remote.port, ack)).catch(() => { });
+    }
+    async function cancelObservation(key) {
+        const observation = observations.get(key);
+        if (!observation)
+            return;
+        observations.delete(key);
+        const id = context.nextMessageId();
+        let message = {
+            type: 'CON', method: 'GET', messageId: id, token: observation.token, path: observation.path,
+            payload: new Uint8Array(0), observe: 1,
+            remote: { host: observation.host, port: observation.port }, receivedAt: Date.now(),
+        };
+        if (config.security?.protects(observation.host, observation.port)) {
+            try {
+                message = await config.security.protect(message);
+            }
+            catch {
+                return;
+            }
+        }
+        try {
+            await config.transport.send(observation.host, observation.port, (0, codec_js_1.encodeCoap)(message));
+        }
+        catch { /* deregistration is best effort */ }
+    }
+    function registerObservation(key, entry, msg) {
+        detach(key, entry);
+        const observation = {
+            token: entry.frame.slice(4, 4 + (entry.frame[0] & 0x0f)),
+            path: [...entry.observation.path],
+            host: entry.host,
+            port: entry.port,
+            handler: entry.observation.handler,
+            lastSequence: msg.observe,
+            lastReceivedAt: msg.receivedAt,
+        };
+        observations.set(key, observation);
+        entry.resolve({
+            ok: true,
+            data: { token: key, cancel: () => cancelObservation(key) },
+        });
+    }
+    function deliverNotification(key, observation, msg) {
+        if (observation.host !== msg.remote.host || observation.port !== msg.remote.port)
+            return;
+        if (msg.type === 'RST') {
+            observations.delete(key);
+            return;
+        }
+        if (msg.type === 'CON')
+            acknowledge(msg.remote, msg.messageId);
+        const codeClass = Number(msg.responseCode?.split('.')[0] ?? 0);
+        if (codeClass !== 2 || msg.observe === undefined) {
+            // A terminal error or a response without Observe ends the relation.
+            observations.delete(key);
+            return;
+        }
+        if (!isFreshObservation(observation.lastSequence, observation.lastReceivedAt, msg.observe, msg.receivedAt))
+            return;
+        observation.lastSequence = msg.observe;
+        observation.lastReceivedAt = msg.receivedAt;
+        status = 'running';
+        try {
+            observation.handler({
+                payload: msg.payload,
+                contentFormat: msg.contentFormat,
+                observe: msg.observe,
+                receivedAt: msg.receivedAt,
+            });
+        }
+        catch { /* consumer failure must not break the transport */ }
+    }
+    return {
+        get status() { return status; },
+        async start() {
+            if (status === 'running')
+                return;
+            await config.transport.bind(config.localPort);
+            unsubMsg = config.transport.onMessage((raw, remote) => {
+                void (async () => {
+                    let msg;
+                    try {
+                        msg = (0, codec_js_1.decodeCoap)(raw, remote);
+                    }
+                    catch {
+                        return;
+                    }
+                    // Fail closed at the security boundary: protected endpoints must send
+                    // OSCORE (empty ACK/RST is exempt), and OSCORE from an unconfigured
+                    // endpoint is never treated as plaintext.
+                    const control = msg.token.length === 0 && (msg.type === 'ACK' || msg.type === 'RST') && msg.responseCode === undefined;
+                    const protectedEndpoint = config.security?.protects(remote.host, remote.port) ?? false;
+                    if (msg.oscore !== undefined) {
+                        if (!protectedEndpoint || !config.security)
+                            return;
+                        try {
+                            msg = await config.security.unprotect(msg);
+                        }
+                        catch {
+                            return;
+                        }
+                    }
+                    else if (protectedEndpoint && !control) {
+                        return;
+                    }
+                    if (msg.token.length === 4) {
+                        const key = (0, codec_js_1.tokenToKey)(msg.token);
+                        const match = findPending(remote, key);
+                        if (match) {
+                            if (msg.type === 'RST') {
+                                settle(match.key, match.entry, new Error('CoAP reset'));
+                                return;
+                            }
+                            if (msg.type === 'CON')
+                                acknowledge(msg.remote, msg.messageId);
+                            const data = { payload: msg.payload };
+                            if (msg.contentFormat !== undefined)
+                                data.contentFormat = msg.contentFormat;
+                            if (msg.observe !== undefined)
+                                data.observe = msg.observe;
+                            if (msg.block1 !== undefined)
+                                data.block1 = msg.block1;
+                            if (msg.block2 !== undefined)
+                                data.block2 = msg.block2;
+                            if (msg.size1 !== undefined)
+                                data.size1 = msg.size1;
+                            if (msg.size2 !== undefined)
+                                data.size2 = msg.size2;
+                            if (match.entry.observation) {
+                                if (msg.observe === undefined) {
+                                    settle(match.key, match.entry, new Error('CoAP server did not establish the observation'));
+                                    return;
+                                }
+                                const codeClass = Number(msg.responseCode?.split('.')[0] ?? 0);
+                                if (codeClass !== 2) {
+                                    settle(match.key, match.entry, new Error(`CoAP error response ${msg.responseCode ?? 'unknown'}`));
+                                    return;
+                                }
+                                registerObservation(match.key, match.entry, msg);
+                                return;
+                            }
+                            const codeClass = Number(msg.responseCode?.split('.')[0] ?? 0);
+                            if (codeClass !== 2) {
+                                settle(match.key, match.entry, new Error(`CoAP error response ${msg.responseCode ?? 'unknown'}`));
+                                return;
+                            }
+                            status = 'running';
+                            settle(match.key, match.entry, undefined, data);
+                            return;
+                        }
+                        const observation = observations.get(key);
+                        if (observation)
+                            deliverNotification(key, observation, msg);
+                        return;
+                    }
+                    // Empty ACK/RST messages carry no token and are correlated by message id.
+                    if (msg.token.length !== 0 || (msg.type !== 'ACK' && msg.type !== 'RST'))
+                        return;
+                    const match = findPending(remote, undefined, msg.messageId);
+                    if (!match)
+                        return;
+                    if (msg.type === 'RST') {
+                        settle(match.key, match.entry, new Error('CoAP reset'));
+                        return;
+                    }
+                    if (msg.responseCode !== undefined)
+                        return;
+                    match.entry.acknowledged = true;
+                    if (match.entry.retransmit)
+                        clearTimeout(match.entry.retransmit);
+                    match.entry.retransmit = undefined;
+                })().catch(() => { });
+            });
+            unsubErr = config.transport.onError((err) => {
+                status = 'error';
+                for (const [key, entry] of [...pending]) {
+                    settle(key, entry, new Error(`CoAP transport error: ${err.message}`));
+                }
+                observations.clear();
+            });
+            status = 'running';
+        },
+        async stop() {
+            unsubMsg?.();
+            unsubErr?.();
+            unsubMsg = undefined;
+            unsubErr = undefined;
+            for (const [key, entry] of [...pending])
+                settle(key, entry, new Error('Gateway stopped'));
+            pending.clear();
+            pendingByMessageId.clear();
+            observations.clear();
+            await config.transport.close();
+            status = 'stopped';
+        },
+        async get(path, host, port) {
+            const first = await coapRequest(context, 'GET', path, new Uint8Array(0), host, port);
+            return blockwise.enabled
+                ? followBlock2(context, first, 'GET', path, new Uint8Array(0), host, port, blockwise.maxBodySize)
+                : first;
+        },
+        async post(path, payload, host, port) {
+            if (!blockwise.enabled) {
+                return coapRequest(context, 'POST', path, payload, host, port);
+            }
+            const first = payload.length > blockwise.blockSize
+                ? await uploadBlockwise(context, path, payload, host, port, blockwise.blockSize)
+                : await coapRequest(context, 'POST', path, payload, host, port);
+            return followBlock2(context, first, 'POST', path, new Uint8Array(0), host, port, blockwise.maxBodySize);
+        },
+        async observe(path, host, port, handler) {
+            return coapRequest(context, 'GET', path, new Uint8Array(0), host, port, {
+                observation: { path: [...path], handler },
+            });
+        },
+    };
+}
+function isFreshObservation(previous, receivedAt, next, now) {
+    if (now - receivedAt > OBSERVATION_FRESHNESS_MS)
+        return true;
+    const difference = ((next - previous) % OBSERVATION_SEQUENCE_MODULO + OBSERVATION_SEQUENCE_MODULO) % OBSERVATION_SEQUENCE_MODULO;
+    return difference !== 0 && difference < OBSERVATION_HALF_RANGE;
+}
+async function coapRequest(context, method, path, payload, host, port, options = {}) {
+    if (!path.length || path.some((segment) => !segment || segment.includes('/'))) {
+        return { ok: false, error: 'Invalid CoAP URI path' };
+    }
+    const { transport, pending, pendingByMessageId, timing, settle } = context;
+    let id;
+    let token;
+    let key;
+    let frame;
+    try {
+        id = context.nextMessageId();
+        token = uniqueToken(pending, context.observations);
+        key = (0, codec_js_1.tokenToKey)(token);
+        let message = {
+            type: 'CON', method, messageId: id, token, path, payload,
+            observe: options.observation ? 0 : undefined,
+            ...(options.block1 ? { block1: options.block1 } : {}),
+            ...(options.block2 ? { block2: options.block2 } : {}),
+            ...(options.size1 !== undefined ? { size1: options.size1 } : {}),
+            ...(options.accept !== undefined ? { accept: options.accept } : {}),
+            remote: { host, port }, receivedAt: Date.now(),
+        };
+        if (context.security?.protects(host, port)) {
+            try {
+                message = await context.security.protect(message);
+            }
+            catch (error) {
+                return { ok: false, error: `CoAP protection failed: ${error instanceof Error ? error.message : String(error)}` };
+            }
+        }
+        frame = (0, codec_js_1.encodeCoap)(message);
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    function scheduleRetransmit(entryKey, entry) {
+        if (entry.acknowledged || entry.attempts >= context.timing.maxRetransmits)
+            return;
+        entry.retransmit = setTimeout(() => {
+            if (entry.settled || entry.acknowledged)
+                return;
+            if (pending.get(entryKey) !== entry)
+                return;
+            entry.attempts++;
+            void Promise.resolve(transport.send(entry.host, entry.port, entry.frame)).catch(() => { });
+            entry.intervalMs *= 2;
+            scheduleRetransmit(entryKey, entry);
+        }, entry.intervalMs);
+    }
+    return new Promise((resolve) => {
+        const entry = {
+            messageId: id,
+            frame, host, port,
+            resolve,
+            deadline: setTimeout(() => settle(key, entry, new Error('CoAP request timed out')), timing.requestTimeoutMs),
+            intervalMs: timing.ackTimeoutMs,
+            attempts: 0,
+            acknowledged: false,
+            settled: false,
+            ...(options.observation ? { observation: options.observation } : {}),
+        };
+        pending.set(key, entry);
+        pendingByMessageId.set(id, key);
+        if (timing.ackTimeoutMs > 0)
+            scheduleRetransmit(key, entry);
+        void Promise.resolve(transport.send(host, port, frame)).catch((error) => {
+            settle(key, entry, error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+/**
+ * RFC 7252 §5.3.1 expects client tokens to be hard for an off-path attacker to
+ * guess. Use WebCrypto when the host provides it; otherwise mix a per-gateway
+ * seed so tokens are not simply sequential message ids.
+ */
+const tokenSeed = Math.floor(Math.random() * 0xffffffff);
+function uniqueToken(pending, observations) {
+    for (let attempt = 0; attempt < 8; attempt++) {
+        const token = createToken(attempt);
+        const key = (0, codec_js_1.tokenToKey)(token);
+        if (!pending.has(key) && !observations.has(key))
+            return token;
+    }
+    throw new Error('Unable to allocate a unique CoAP token');
+}
+function createToken(messageId) {
+    const token = new Uint8Array(4);
+    const webCrypto = globalThis.crypto;
+    if (typeof webCrypto?.getRandomValues === 'function') {
+        webCrypto.getRandomValues(token);
+        return token;
+    }
+    const value = (tokenSeed ^ Math.imul(messageId + 1, 0x9e3779b1)) >>> 0;
+    new DataView(token.buffer).setUint32(0, value, false);
+    return token;
+}
+function normalizeBlockSize(size) {
+    if (!Number.isInteger(size) || size < 16 || size > 1024 || (size & (size - 1)) !== 0) {
+        throw new Error(`Invalid blockwise block size ${size}; expected a power of two from 16 to 1024`);
+    }
+    return size;
+}
+function blockSizeExponent(size) {
+    return Math.log2(size) - 4;
+}
+async function uploadBlockwise(context, path, payload, host, port, blockSize) {
+    let sizeExponent = blockSizeExponent(blockSize);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const outcome = await uploadPass(context, path, payload, host, port, sizeExponent);
+        if (outcome.retryExponent === undefined) {
+            return outcome.result ?? { ok: false, error: 'Empty blockwise upload' };
+        }
+        sizeExponent = outcome.retryExponent;
+    }
+    return { ok: false, error: 'Blockwise size renegotiation failed' };
+}
+async function uploadPass(context, path, payload, host, port, sizeExponent) {
+    const blockSize = 2 ** (sizeExponent + 4);
+    let offset = 0;
+    let num = 0;
+    let last;
+    while (offset < payload.length) {
+        const chunk = payload.slice(offset, Math.min(offset + blockSize, payload.length));
+        const more = offset + chunk.length < payload.length;
+        const result = await coapRequest(context, 'POST', path, chunk, host, port, {
+            block1: { num, more, sizeExponent },
+            size1: payload.length,
+        });
+        if (!result.ok)
+            return { result };
+        if (more) {
+            const acknowledgement = result.data?.block1;
+            if (!acknowledgement)
+                return { result: { ok: false, error: 'Server did not acknowledge the blockwise upload' } };
+            if (acknowledgement.num !== num)
+                return { result: { ok: false, error: `Unexpected Block1 number ${acknowledgement.num}` } };
+            if (acknowledgement.sizeExponent < sizeExponent) {
+                // The server selected a smaller block size; restart the transfer.
+                return { retryExponent: acknowledgement.sizeExponent };
+            }
+            if (acknowledgement.sizeExponent > sizeExponent) {
+                return { result: { ok: false, error: 'Server increased the Block1 size mid-transfer' } };
+            }
+        }
+        last = result;
+        offset += chunk.length;
+        num++;
+    }
+    return { result: last };
+}
+async function followBlock2(context, first, method, path, body, host, port, maxBodySize) {
+    if (!first.ok || !first.data?.block2?.more)
+        return first;
+    const sizeExponent = first.data.block2.sizeExponent;
+    let assembled = first.data.payload.slice();
+    let expected = first.data.block2.num + 1;
+    let current = first.data;
+    if (assembled.length > maxBodySize)
+        return { ok: false, error: 'Blockwise response exceeds maxBodySize' };
+    while (current.block2?.more) {
+        const next = await coapRequest(context, method, path, method === 'POST' ? new Uint8Array(0) : body, host, port, {
+            block2: { num: expected, more: false, sizeExponent },
+        });
+        if (!next.ok || !next.data)
+            return next;
+        if (!next.data.block2)
+            return { ok: false, error: 'Blockwise response is missing Block2' };
+        if (next.data.block2.num !== expected) {
+            return { ok: false, error: `Unexpected Block2 number ${next.data.block2.num}` };
+        }
+        if (next.data.block2.sizeExponent !== sizeExponent) {
+            return { ok: false, error: 'Server changed the Block2 size mid-transfer' };
+        }
+        assembled = concatBytes(assembled, next.data.payload);
+        if (assembled.length > maxBodySize)
+            return { ok: false, error: 'Blockwise response exceeds maxBodySize' };
+        current = next.data;
+        expected++;
+    }
+    return { ok: true, data: { ...current, payload: assembled } };
+}
+function concatBytes(first, second) {
+    const out = new Uint8Array(first.length + second.length);
+    out.set(first, 0);
+    out.set(second, first.length);
+    return out;
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,13 @@
+export type { CoapTransportPort, CoapMessage, CoapMessageType, CoapMethod, CoapBlockOption } from './transport.js';
+export { createCoapGateway } from './gateway.js';
+export type { CoapGatewayConfig, CoapGateway, CoapResponseData, CoapObservationData, CoapObservation, CoapBlockwiseOptions, } from './gateway.js';
+export { decodeCbor, CborDecodeError } from './cbor.js';
+export type { CborValue, CborDecodeOptions } from './cbor.js';
+export { isOscoreProtected } from './security.js';
+export type { CoapSecurityPort } from './security.js';
+export { createOscoreContext } from './oscore.js';
+export type { OscoreContextConfig } from './oscore.js';
+export { createCoapSensorBridge, APPLICATION_CBOR } from './sensor-bridge.js';
+export type { CoapSensorBinding, CoapSensorBridgeConfig, CoapSensorBridge } from './sensor-bridge.js';
+export { NativeCoapTransport } from './native-transport.js';
+export type { NativeCoapConfig } from './native-transport.js';

package/dist/cjs/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeCoapTransport = exports.APPLICATION_CBOR = exports.createCoapSensorBridge = exports.createOscoreContext = exports.isOscoreProtected = exports.CborDecodeError = exports.decodeCbor = exports.createCoapGateway = void 0;
+var gateway_js_1 = require("./gateway.js");
+Object.defineProperty(exports, "createCoapGateway", { enumerable: true, get: function () { return gateway_js_1.createCoapGateway; } });
+var cbor_js_1 = require("./cbor.js");
+Object.defineProperty(exports, "decodeCbor", { enumerable: true, get: function () { return cbor_js_1.decodeCbor; } });
+Object.defineProperty(exports, "CborDecodeError", { enumerable: true, get: function () { return cbor_js_1.CborDecodeError; } });
+var security_js_1 = require("./security.js");
+Object.defineProperty(exports, "isOscoreProtected", { enumerable: true, get: function () { return security_js_1.isOscoreProtected; } });
+var oscore_js_1 = require("./oscore.js");
+Object.defineProperty(exports, "createOscoreContext", { enumerable: true, get: function () { return oscore_js_1.createOscoreContext; } });
+var sensor_bridge_js_1 = require("./sensor-bridge.js");
+Object.defineProperty(exports, "createCoapSensorBridge", { enumerable: true, get: function () { return sensor_bridge_js_1.createCoapSensorBridge; } });
+Object.defineProperty(exports, "APPLICATION_CBOR", { enumerable: true, get: function () { return sensor_bridge_js_1.APPLICATION_CBOR; } });
+var native_transport_js_1 = require("./native-transport.js");
+Object.defineProperty(exports, "NativeCoapTransport", { enumerable: true, get: function () { return native_transport_js_1.NativeCoapTransport; } });

package/dist/cjs/native-transport.d.ts

@@ -0,0 +1,33 @@
+/**
+ * NativeCoapTransport — connects to the edge-coap Go binary over TCP.
+ *
+ * The Go binary listens on a local TCP socket (default 127.0.0.1:15003) and
+ * accepts newline-delimited JSON send requests. Inbound datagrams are pushed
+ * back as `message` events; token correlation stays in the gateway.
+ */
+import type { CoapTransportPort } from './transport.js';
+export interface NativeCoapConfig {
+    host?: string;
+    port?: number;
+    connectTimeoutMs?: number;
+    requestTimeoutMs?: number;
+}
+export declare class NativeCoapTransport implements CoapTransportPort {
+    private socket;
+    private buffer;
+    private pending;
+    private messageHandlers;
+    private errorHandlers;
+    private readonly config;
+    private closedByUser;
+    constructor(config?: NativeCoapConfig);
+    private emitError;
+    bind(_port: number): Promise<void>;
+    close(): Promise<void>;
+    send(host: string, port: number, message: Uint8Array): Promise<void>;
+    onMessage(handler: (message: Uint8Array, remote: {
+        host: string;
+        port: number;
+    }) => void): () => void;
+    onError(handler: (err: Error) => void): () => void;
+}