tina4-nodejs 3.13.92 → 3.13.95

package/types/core/src/middleware.d.ts

@@ -0,0 +1,330 @@
+import type { Tina4Request, Tina4Response, Middleware } from "./types.js";
+export declare class MiddlewareChain {
+    private middlewares;
+    use(fn: Middleware): void;
+    /**
+     * Run the chain in REGISTRATION order — each middleware runs exactly once,
+     * in the order it was attached via use(). The chain advances from ONE
+     * source only: `next()`. (The old runner double-advanced — a for-loop index
+     * AND next() both incremented — so every other middleware was silently
+     * skipped. Fixed by driving the chain purely by next(), mirroring Python's
+     * _make_mw_continuation Russian-doll continuation.)
+     *
+     * A middleware may stop the chain by:
+     *   - not calling next() (it owns the response), or
+     *   - ending the response (res.raw.writableEnded).
+     * Returns true when the whole chain ran to completion (handler may proceed),
+     * false when it was short-circuited.
+     */
+    run(req: Tina4Request, res: Tina4Response): Promise<boolean>;
+}
+/**
+ * True when a middleware spec is a CLASS (the beforeX/afterX convention)
+ * rather than a plain `(req, res, next)` middleware function.
+ *
+ * A class's `prototype` property is non-writable by the language spec
+ * (ClassDefinitionEvaluation); an ordinary function's is writable, and an
+ * arrow function, async function or bound function has no `prototype` at all.
+ * That is a language-level distinction rather than a name or source-string
+ * sniff, so a class named `cors` and a function named `Cors` both classify
+ * correctly.
+ */
+export declare function isMiddlewareClass(spec: unknown): boolean;
+export declare class MiddlewareRunner {
+    /** Globally registered middleware classes (parity with PHP/Ruby/Python orchestrators). */
+    private static globalMiddleware;
+    /**
+     * Register a middleware class to run on every request.
+     * Mirrors Tina4\Middleware::use (PHP), Tina4::Middleware.use (Ruby),
+     * and Middleware.use (Python).
+     */
+    static use(cls: any): void;
+    /** Return the list of globally registered middleware classes. */
+    /**
+     * Global middleware that runs BEFORE route matching.
+     *
+     * A middleware opts in with `static preMatch = true`. Everything else stays
+     * where it has always run - after matching - so this is additive and no
+     * existing middleware changes behaviour.
+     *
+     * The two groups need opposite things. CORS must run before matching so its
+     * headers survive a short-circuited 401/403; a browser shown a 401 without
+     * them reports a CORS error and the real status never reaches the developer.
+     * CSRF must run AFTER, because it reads the matched route's metadata to
+     * honour a route marked noAuth - PHP shipped exactly that bypass as dead
+     * code once, because the metadata was not assigned yet.
+     *
+     * NOT named `beforeMatch` - hook discovery treats every `before*` static as
+     * a middleware hook and would call the flag itself with (req, res).
+     */
+    static partitionByMatchPhase(all: any[]): {
+        pre: any[];
+        post: any[];
+    };
+    static getGlobal(): any[];
+    /** Clear all globally registered middleware (primarily for tests). */
+    static reset(): void;
+    /**
+     * Discover the before-prefixed / after-prefixed hook names on a middleware
+     * class, INHERITED HOOKS INCLUDED, base class first (M1).
+     *
+     * `Object.getOwnPropertyNames` returns a class's OWN statics only, in
+     * source-declaration order. On its own that silently DROPPED every hook a
+     * subclass inherited: for `class Sub extends Base` with `static beforeBase`
+     * on the base, discovery returned only ["beforeSub"] even though
+     * `Sub.beforeBase` is a live function — so a shared base middleware simply
+     * never ran, with no error. Python returns ['before_base','before_sub'] and
+     * Ruby [:before_base,:before_sub]; Node was the only one of the four that
+     * lost hooks.
+     *
+     * So walk the prototype chain (the STATIC side: Sub -> Base -> ...) and emit
+     * base-class hooks BEFORE the subclass's own, de-duping an override to its
+     * first (base) position. That is exactly Python's `_discover_methods`
+     * walking `reversed(__mro__)` over each `__dict__`, and Ruby's
+     * `discover_methods` walking `ancestors.reverse_each`.
+     *
+     * Within one class the order is still source-declaration order — we
+     * deliberately do NOT sort(), so hooks run in the order they were written
+     * (parity with Python walking __dict__, PHP get_class_methods, Ruby
+     * instance_methods(false)). Cross-class order is the natural iteration of
+     * the registered classes = REGISTRATION order.
+     *
+     * The chain walk stops at Function.prototype / Object.prototype, so the
+     * built-in members are never scanned. A plain object registered as
+     * middleware still works: its own keys are level 0.
+     */
+    private static methodNames;
+    /**
+     * Execute every beforeX static method found on the supplied classes.
+     *
+     * ORDER (M1): cross-class = REGISTRATION order (the order classes were
+     * attached via Router.use / MiddlewareRunner.use); within a class =
+     * DEFINITION order (source order, never alphabetical). before_* run before
+     * the handler.
+     *
+     * THROW (M2): each before* call is wrapped — a throwing middleware is
+     * LOGGED and produces a deterministic clean 500 (it never crashes the
+     * worker / leaks an unhandled exception), and the chain short-circuits
+     * (skip = true, handler skipped).
+     *
+     * Short-circuits (skip = true, handler skipped) when a before* sets a
+     * status >= 400 or ends/500s the response.
+     *
+     * ASYNC — each hook is awaited so middleware can perform async work (e.g.
+     * the distributed responseCache before-hook awaiting `backend.get`). Awaiting
+     * a synchronous hook that returns an array is harmless (the array resolves
+     * immediately), so existing sync hooks keep working unchanged.
+     *
+     * RETURN VALUE — see `interpretHookResult` for the one table every hook at
+     * every scope obeys. A returned Response object is the PRIMARY
+     * short-circuit; `false` is a deny.
+     *
+     * Returns [req, res, shouldContinue].
+     */
+    static runBefore(classes: any[], req: Tina4Request, res: Tina4Response): Promise<[Tina4Request, Tina4Response, boolean]>;
+    /**
+     * Execute every afterX static method found on the supplied classes.
+     *
+     * ORDER (M1): cross-class = REGISTRATION order; within a class = DEFINITION
+     * order. after_* run after the handler.
+     *
+     * THROW (M2): each after* call is wrapped — a throwing after middleware is
+     * LOGGED and produces a clean 500, then the remaining after* STILL run
+     * (they may add headers / logging). No unhandled exception leaks.
+     *
+     * AFTER-ON-4xx RULE (M2): after_* ALWAYS run, even when a before_*
+     * short-circuited with status >= 400 and the handler was skipped — so they
+     * can still add headers / logging. The dispatcher calls runAfter
+     * unconditionally after the before/handler block (see server.ts).
+     *
+     * ASYNC — each hook is awaited (e.g. the responseCache after-hook awaiting
+     * `backend.set`). Awaiting a synchronous hook is harmless, so existing sync
+     * after-hooks keep working unchanged.
+     *
+     * RETURN VALUE — the SAME table as runBefore (`interpretHookResult`): the
+     * contract is one table for every hook at every scope. There is nothing left
+     * to skip after the handler, so a short-circuit here ends the after chain.
+     * A THROW is different and unchanged: it is logged, becomes a clean 500, and
+     * the remaining after hooks still run.
+     */
+    static runAfter(classes: any[], req: Tina4Request, res: Tina4Response): Promise<[Tina4Request, Tina4Response]>;
+}
+/** Configuration for the CORS middleware */
+export interface CorsConfig {
+    /** Allowed origins. Default: NONE (deny) — or TINA4_CORS_ORIGINS env, comma-separated. "*" allows any. */
+    origins?: string | string[];
+    /** Allowed methods. Default: standard REST methods (or TINA4_CORS_METHODS env) */
+    methods?: string | string[];
+    /** Allowed headers. Default: Content-Type, Authorization (or TINA4_CORS_HEADERS env) */
+    headers?: string | string[];
+    /** Access-Control-Max-Age in seconds. Default: 86400 (or TINA4_CORS_MAX_AGE env) */
+    maxAge?: number;
+    /** Send Access-Control-Allow-Credentials. Default: false (or TINA4_CORS_CREDENTIALS env). Never sent with a wildcard origin. */
+    credentials?: boolean;
+}
+/** Reset the CORS warn-once ledger. Test seam. */
+export declare function resetCorsWarnings(): void;
+/**
+ * The resolved CORS policy — ONE implementation of the rules.
+ *
+ * Both the function middleware `cors()` and the class middleware
+ * `CorsMiddleware` build one of these and apply what it returns. They used to
+ * be two independent implementations that had already drifted: `cors()` never
+ * read TINA4_CORS_CREDENTIALS at all, so the DEFAULT always-on pipeline
+ * silently ignored a documented env var (measured 2026-07-31). One feature,
+ * one code path.
+ *
+ * DENY BY DEFAULT (ADR-0018). With no origins configured, NO
+ * Access-Control-Allow-Origin is emitted and the browser's own CORS check
+ * blocks the cross-origin request. "*" still works, it just has to be asked for.
+ *
+ * CREDENTIALS AND THE WILDCARD ARE MUTUALLY EXCLUSIVE. The Fetch Standard's
+ * CORS check treats "*" as a literal (not a wildcard) once the request's
+ * credentials mode is "include", so ACAO: * with
+ * Access-Control-Allow-Credentials: true is rejected by every browser.
+ *
+ * VARY: ORIGIN whenever the ACAO value is COMPUTED from the request's Origin,
+ * i.e. whenever an allow-list is configured — on a MISS as well as a match.
+ * RFC 9110 s12.5.5: a Vary field name list tells cache recipients they "MUST
+ * NOT use this response to satisfy a later request unless the later request
+ * has the same values for the listed header fields as the original request".
+ * The miss case matters most: without it a shared cache can store the no-ACAO
+ * response for origin B and serve it to origin A. A constant "*" genuinely
+ * does not vary and gets no Vary, which would only fragment a CDN's cache.
+ *
+ * Access-Control-Allow-Methods / -Allow-Headers are static configured lists
+ * here, never derived from the request's Access-Control-Request-* headers, so
+ * those field names do NOT belong in Vary.
+ */
+export declare class CorsPolicy {
+    readonly allowedOrigins: string[];
+    readonly allowedMethods: string;
+    readonly allowedHeaders: string;
+    readonly maxAge: number;
+    readonly credentials: boolean;
+    constructor(config?: CorsConfig);
+    /** Whether an operator has actually declared a CORS policy. */
+    isConfigured(): boolean;
+    /** The origin to send in Access-Control-Allow-Origin, or undefined for none. */
+    resolveOrigin(requestOrigin: string): string | undefined;
+    /**
+     * The CORS headers for a request origin. `isPreflight` adds Max-Age, which
+     * the Fetch Standard only defines for a preflight response.
+     */
+    headersFor(requestOrigin: string, isPreflight: boolean): Record<string, string>;
+}
+/**
+ * Built-in CORS middleware (function form).
+ *
+ * A thin adapter over CorsPolicy — see that class for the rules and the
+ * standards behind them. Reads configuration from env vars when not provided:
+ *   TINA4_CORS_ORIGINS — comma-separated list of allowed origins, or "*"
+ *   TINA4_CORS_METHODS — comma-separated list of allowed methods
+ *   TINA4_CORS_HEADERS — comma-separated list of allowed headers
+ *   TINA4_CORS_MAX_AGE — preflight cache duration in seconds
+ *   TINA4_CORS_CREDENTIALS — send Access-Control-Allow-Credentials
+ *
+ * A real preflight is answered 204. The status is the same whether the origin
+ * was allowed or denied — the browser does the blocking.
+ */
+export declare function cors(config?: CorsConfig): Middleware;
+/**
+ * Class-based CORS middleware using the before/after convention.
+ *
+ * The same CorsPolicy as `cors()` — one implementation, one set of semantics.
+ *
+ * Usage:
+ *   Router.use(CorsMiddleware);
+ */
+export declare class CorsMiddleware {
+    static beforeCors(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+    /**
+     * Check if a request is an OPTIONS preflight.
+     *
+     * NOTE: returns true for ANY OPTIONS, with no Origin check, so the name
+     * overstates what it tests. The real short-circuit uses isCorsPreflight().
+     * Kept because existing tests pin this meaning.
+     */
+    static isPreflight(method: string): boolean;
+}
+/**
+ * Class-based rate limiter middleware using the before/after convention.
+ * Uses the same sliding-window algorithm as the `rateLimiter()` function.
+ *
+ * Reads configuration from env vars:
+ *   TINA4_RATE_LIMIT  — max requests per window (default 100)
+ *   TINA4_RATE_WINDOW — window duration in seconds (default 60)
+ *
+ * Usage:
+ *   Router.use(RateLimiterMiddleware);
+ */
+export declare class RateLimiterMiddleware {
+    private static store;
+    private static cleanupTimer;
+    private static ensureCleanup;
+    static beforeRateLimit(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+    /**
+     * Check if an IP is within rate limits without recording a request.
+     * Returns [allowed, info] matching Python/Ruby API.
+     */
+    static check(ip: string): [boolean, {
+        limit: number;
+        remaining: number;
+        reset: number;
+        window: number;
+    }];
+}
+/**
+ * Class-based request logger middleware using the before/after convention.
+ * `beforeLog` stamps the request start time.
+ * `afterLog` prints the coloured status line.
+ *
+ * Usage:
+ *   Router.use(RequestLogger);
+ */
+export declare class RequestLogger {
+    static beforeLog(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+    static afterLog(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+}
+/**
+ * Class-based security headers middleware using the before/after convention.
+ * Auto-injects security headers on every response.
+ *
+ * Configuration via env vars:
+ *   TINA4_FRAME_OPTIONS       — X-Frame-Options (default: "SAMEORIGIN")
+ *   TINA4_HSTS                — Strict-Transport-Security max-age value
+ *                                (default: "" = off; set to "31536000" to enable)
+ *   TINA4_CSP                 — Content-Security-Policy (default: "default-src 'self'")
+ *   TINA4_REFERRER_POLICY     — Referrer-Policy (default: "strict-origin-when-cross-origin")
+ *   TINA4_PERMISSIONS_POLICY  — Permissions-Policy (default: "camera=(), microphone=(), geolocation=()")
+ *
+ * Usage:
+ *   Router.use(SecurityHeadersMiddleware);
+ */
+export declare class SecurityHeadersMiddleware {
+    static beforeSecurity(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+}
+/**
+ * Class-based CSRF middleware using the before/after convention.
+ * Validates form tokens on state-changing requests (POST, PUT, PATCH, DELETE).
+ *
+ * Off by default — only active when TINA4_CSRF=true in .env or when
+ * registered explicitly via Router.use(CsrfMiddleware).
+ *
+ * Behaviour:
+ *   - Skips GET, HEAD, OPTIONS requests.
+ *   - Skips routes marked .noAuth().
+ *   - Skips requests with a valid Authorization: Bearer header (API clients).
+ *   - Checks request body formToken then X-Form-Token header.
+ *   - Rejects if token found in query string formToken (log warning, 403).
+ *   - Validates token with validToken using SECRET env var.
+ *   - If token payload has session_id, verifies it matches request session.
+ *   - Returns 403 on failure.
+ *
+ * Usage:
+ *   Router.use(CsrfMiddleware);
+ */
+export declare class CsrfMiddleware {
+    static beforeCsrf(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+}
+export declare function requestLogger(): Middleware;

package/types/core/src/mqtt.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Zero-dependency MQTT 3.1.1 client — the protocol every broker and every IoT
+ * device already speaks.
+ *
+ * Built on Node's `node:net` and `node:tls` stdlib modules only: no npm package,
+ * so an app that talks to Mosquitto / EMQX / HiveMQ / AWS IoT adds nothing to its
+ * dependency tree. Shaped like the Queue on purpose — publish / subscribe /
+ * consume:
+ *
+ *     import { Mqtt } from "@tina4stack/tina4-node";
+ *
+ *     const mqtt = new Mqtt({ url: "mqtt://broker:1883" });   // TINA4_MQTT_URL
+ *     await mqtt.connect();
+ *     await mqtt.publish("fleet/meter-42/telemetry", '{"kwh":12.5}', 1);
+ *
+ *     for await (const message of mqtt.consume("fleet/+/telemetry", 1)) {
+ *       if (message.isDuplicate()) continue;                  // QoS 1 is at-least-once
+ *       store(message.topic, message.payload);
+ *     }
+ *
+ * Environment: TINA4_MQTT_URL (default mqtt://127.0.0.1:1883),
+ * TINA4_MQTT_CLIENT_ID, TINA4_MQTT_KEEPALIVE (seconds, default 60),
+ * TINA4_MQTT_CA_FILE, TINA4_MQTT_TLS_VERIFY.
+ *
+ * Node has no synchronous blocking socket read, so connect()/publish()/
+ * subscribe()/receive() are async and consume() is an async generator — the same
+ * idiom as the Queue. No background task runs by default; opt in to the
+ * cooperative keepalive with startKeepalive(), which registers a background()
+ * task exactly like the queue consumers do.
+ *
+ * Single reader: like every MQTT client the socket has ONE network reader. Call
+ * receive()/consume() from one place.
+ */
+import { MqttMessage } from "./mqttMessage.js";
+/** Any MQTT protocol / connection failure. */
+export declare class MqttError extends Error {
+    constructor(message: string);
+}
+/** The broker did not answer inside the timeout. */
+export declare class MqttTimeoutError extends MqttError {
+    constructor(message: string);
+}
+export interface MqttOptions {
+    url?: string;
+    clientId?: string;
+    username?: string;
+    password?: string;
+    caFile?: string;
+    tlsVerify?: boolean;
+    keepalive?: number;
+    cleanSession?: boolean;
+    willTopic?: string;
+    willPayload?: unknown;
+    willQos?: number;
+    willRetain?: boolean;
+    /** Seconds to wait for a control-packet answer (CONNACK / PUBACK / SUBACK). */
+    timeout?: number;
+    /** Seconds to wait for an application message; null/undefined blocks. */
+    readTimeout?: number | null;
+}
+export interface ParsedMqttUrl {
+    host: string;
+    port: number;
+    tls: boolean;
+    username: string | null;
+    password: string | null;
+}
+export declare class Mqtt {
+    readonly host: string;
+    readonly port: number;
+    readonly clientId: string;
+    readonly keepalive: number;
+    readonly cleanSession: boolean;
+    readonly username: string | null;
+    private readonly secure;
+    private readonly password;
+    private readonly caFile;
+    private readonly tlsVerify;
+    private readonly willTopic;
+    private readonly willPayload;
+    private readonly willQos;
+    private readonly willRetain;
+    private readonly timeout;
+    private readonly readTimeout;
+    private packetId;
+    private inbox;
+    private lastWriteAt;
+    private socket;
+    private keepaliveTask;
+    private readBuffer;
+    private waiter;
+    private socketError;
+    constructor(options?: MqttOptions);
+    /**
+     * Split an MQTT url into { host, port, tls, username, password }.
+     *
+     * "mqtt://host:port" and "tcp://host:port" are plain TCP (default port 1883);
+     * "mqtts://host:port" is TLS (default 8883). A bare "host" or "host:port"
+     * works too, and an IPv6 literal is bracketed ("mqtt://[::1]:1883").
+     * Credentials ride in the userinfo and are percent-decoded, so a password
+     * containing @ : or / survives.
+     */
+    static parseUrl(url: string): ParsedMqttUrl;
+    /**
+     * Decode %XX in url userinfo. NOT decodeURI-style "+"-to-space: a "+" in a
+     * password must survive verbatim, and an invalid "%" is left as-is (never throws).
+     */
+    private static percentDecode;
+    /**
+     * Remaining Length varint: 7 bits per byte, high bit means "another byte
+     * follows". A single-byte assumption works for every packet under 128 bytes
+     * and then fails, so this is exercised directly at 0 / 127 / 128 / 16383.
+     */
+    static encodeRemainingLength(value: number): Buffer;
+    /**
+     * Open the socket and complete the CONNECT / CONNACK handshake. Also the
+     * reconnect path: an existing socket is closed first, and a durable session
+     * (cleanSession false) resumes with the same clientId. Returns this for
+     * chaining (`const c = await new Mqtt(opts).connect()`).
+     */
+    connect(): Promise<this>;
+    /** Whether a socket is currently open. */
+    connected(): boolean;
+    /** True when this connection runs over TLS (mqtts://). */
+    tls(): boolean;
+    /**
+     * The negotiated cipher suite name, or null on a plain connection. A real name
+     * here is proof the TLS handshake actually completed.
+     */
+    cipher(): string | null;
+    /** The negotiated TLS protocol version ("TLSv1.3"), or null when plain. */
+    tlsVersion(): string | null;
+    /**
+     * Publish an application message. Resolves to the packet identifier for QoS 1
+     * (the broker's PUBACK must carry it back) and null for QoS 0.
+     *
+     * retain=true tells the broker to keep this as the topic's last known value and
+     * hand it to every FUTURE subscriber. Publishing an EMPTY payload with
+     * retain=true clears a retained value.
+     */
+    publish(topic: string, payload: unknown, qos?: number, retain?: boolean): Promise<number | null>;
+    /**
+     * Subscribe to a topic filter ("fleet/+/telemetry", "fleet/#"). Resolves to the
+     * QoS the broker GRANTED, which can be lower than requested.
+     *
+     * A SUBACK carrying 0x80 is a REFUSAL, not a success -- treating any SUBACK as
+     * success means sitting on a dead subscription receiving nothing, so it throws.
+     */
+    subscribe(topicFilter: string, qos?: number): Promise<number>;
+    /**
+     * Read the next application message.
+     *
+     * ack=true (the default) acknowledges a QoS 1 delivery immediately, which is
+     * right for a synchronous read. Pass ack=false when the message must be stored
+     * before the broker is allowed to forget it -- an unacknowledged QoS 1 message
+     * is redelivered with DUP set. consume() does exactly that.
+     */
+    receive(timeout?: number | null, ack?: boolean): Promise<MqttMessage>;
+    /**
+     * Long-running consumer, mirroring Queue.consume().
+     *
+     *     for await (const message of mqtt.consume("fleet/+/telemetry", 1)) {
+     *       store(message);
+     *     }
+     *
+     * The message is acknowledged AFTER the loop body hands control back to the
+     * generator (the next iteration), so a body that throws leaves the message
+     * unacknowledged and the broker redelivers it with DUP set -- at-least-once,
+     * the point of QoS 1. iterations > 0 stops after that many messages.
+     */
+    consume(topicFilter?: string | null, qos?: number, iterations?: number, timeout?: number | null): AsyncGenerator<MqttMessage>;
+    /** PUBACK a QoS 1 delivery. Called by MqttMessage.acknowledge(). */
+    acknowledge(packetId: number): Promise<boolean>;
+    /**
+     * PINGREQ and wait for the PINGRESP. Use this when nothing else is reading the
+     * socket; under a consume loop use startKeepalive() instead.
+     */
+    ping(timeout?: number | null): Promise<boolean>;
+    /**
+     * Write a PINGREQ without waiting for the answer. The PINGRESP is absorbed by
+     * whatever is reading the socket (receive() skips it).
+     */
+    sendKeepalive(): Promise<boolean>;
+    /**
+     * Opt in to the cooperative keepalive. Registers a background() task -- the
+     * same mechanism the queue consumers use -- that sends a PINGREQ only when the
+     * connection has gone quiet, so an actively publishing client costs no extra
+     * packets.
+     */
+    startKeepalive(intervalSeconds?: number): {
+        stop: () => void;
+    };
+    /** Stop the cooperative keepalive registered by startKeepalive(). */
+    stopKeepalive(): boolean;
+    /**
+     * Say goodbye properly: DISCONNECT then close. The broker discards the Last
+     * Will on a graceful disconnect.
+     */
+    disconnect(): Promise<boolean>;
+    /**
+     * Drop the socket WITHOUT a DISCONNECT -- what a crashed or unplugged device
+     * looks like to the broker, and therefore what fires the Last Will.
+     */
+    kill(): boolean;
+    private connectFlags;
+    /**
+     * Open a connected socket, upgrading to TLS when mqtts://. Rejects with an
+     * MqttError on a connect timeout or a TLS verification failure (the cert error
+     * message is preserved so a rejected cert reports WHY). Each connection builds
+     * its OWN tls options object, so a CA supplied for one client never leaks into
+     * a later client.
+     */
+    private openSocket;
+    private refuseUnsupportedQos;
+    /** Encode an MQTT string: a 2-byte big-endian length followed by UTF-8 bytes. */
+    private static mqttString;
+    private static uint16;
+    private static payloadBytes;
+    /** The next packet identifier (1..65535; 0 is invalid). */
+    private nextPacketId;
+    private writePacket;
+    /**
+     * Read one control packet. The fixed header is read in exactly 1 + N bytes
+     * (N <= 4 for the varint) so the next packet's header is never consumed by a
+     * speculative over-read.
+     */
+    private readPacket;
+    /**
+     * Read exactly `need` bytes from the socket buffer, awaiting more data when
+     * short. Only one read is ever outstanding (the protocol reads sequentially),
+     * so a single waiter slot is enough. The 'data' handler feeds the buffer and
+     * services the waiter; a deadline arms a timer that rejects with a timeout.
+     */
+    private readExact;
+    private take;
+    private serviceWaiter;
+    private onData;
+    private onSocketGone;
+    /** Read packets until the next PUBLISH, skipping keepalive PINGRESPs. */
+    private readPublish;
+    /**
+     * Park a PUBLISH that arrives while we wait for a PUBACK/SUBACK/PINGRESP
+     * (normal when the same connection both publishes and subscribes) so receive()
+     * still delivers it, in order, instead of it being mistaken for the ack.
+     */
+    private stashPublish;
+    private parsePublish;
+    /**
+     * Wait for a specific acknowledgement, tolerating interleaved PUBLISH and
+     * PINGRESP packets. A mismatched packet identifier is silent data loss if
+     * ignored, so it throws.
+     */
+    private waitForAcknowledgement;
+    private idleFor;
+    private deadlineIn;
+    private closeSocket;
+}

package/types/core/src/mqttMessage.d.ts

@@ -0,0 +1,67 @@
+/**
+ * One MQTT 3.1.1 application message as delivered by the broker.
+ *
+ * Shaped like the Queue's job (its unit of work): it carries the payload plus
+ * the delivery metadata a consumer needs, and it knows how to acknowledge itself
+ * back to the client it came from. Mirrors tina4_python.mqtt.MqttMessage,
+ * Tina4::MqttMessage (Ruby), and Tina4\MqttMessage (PHP).
+ *
+ * The two flags matter for correctness, not decoration:
+ *
+ *   retained  — the broker replayed the topic's last known value to us because
+ *               we subscribed AFTER it was published. It is current state, not a
+ *               fresh event.
+ *   duplicate — the DUP flag. The broker is REDELIVERING a QoS 1 message it never
+ *               saw acknowledged. QoS 1 is at-least-once, so a duplicate is
+ *               guaranteed eventually; a consumer that treats a DUP delivery as a
+ *               new sample double-counts energy or mileage. Key the ingest on
+ *               (deviceId, deviceTimestamp) and it is harmless.
+ *
+ * The payload is a Buffer of the raw bytes; text() decodes it for JSON/string
+ * payloads.
+ */
+/** The slice of an Mqtt client an MqttMessage needs to acknowledge itself. */
+export interface MqttAcknowledger {
+    acknowledge(packetId: number): Promise<boolean>;
+}
+export declare class MqttMessage {
+    readonly topic: string;
+    readonly payload: Buffer;
+    readonly qos: number;
+    readonly retained: boolean;
+    readonly duplicate: boolean;
+    readonly packetId: number | null;
+    private readonly client;
+    private acknowledgedFlag;
+    constructor(topic: string, payload: Buffer, qos?: number, retained?: boolean, duplicate?: boolean, packetId?: number | null, client?: MqttAcknowledger | null);
+    /** True when the broker replayed this as the topic's retained (last known) value. */
+    isRetained(): boolean;
+    /**
+     * True when the broker set the DUP flag — a REDELIVERY of a QoS 1 message we
+     * never acknowledged, not a new sample.
+     */
+    isDuplicate(): boolean;
+    /**
+     * PUBACK a QoS 1 delivery so the broker stops redelivering it.
+     *
+     * A QoS 0 message needs no acknowledgement, and a second call is a no-op, so
+     * this is always safe to call once processing succeeded. Returns true only
+     * when a PUBACK was actually sent.
+     */
+    acknowledge(): Promise<boolean>;
+    /** True once this message has been acknowledged back to the broker. */
+    isAcknowledged(): boolean;
+    /** The payload decoded as text (for JSON / string payloads). */
+    text(encoding?: BufferEncoding): string;
+    /** The message as a plain object. */
+    toObject(): {
+        topic: string;
+        payload: Buffer;
+        qos: number;
+        retained: boolean;
+        duplicate: boolean;
+        packetId: number | null;
+    };
+    /** String form is the payload text (parity with Python __str__ / Ruby to_s). */
+    toString(): string;
+}