@crvouga/mockingbird-service-aws-iot

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the AWS IoT Core data plane for test suites and local development: IoTDataPlane Publish over HTTP with Signature Version 4 verification, and the MQTT 5 message broker over TCP and WebSocket (/mqtt) with custom-authorizer policies, AWS IoT's persistent session rules and its documented departures from the MQTT specification. It runs in the test process on OS-assigned ports with no AWS account, and session expiry follows a clock the suite moves instead of waiting.

• Operation coverage (HTTP): SUPPORT.md
• No AWS account was used as an oracle. Behaviour follows the Publish API reference, the MQTT, custom authentication, policy and quota pages, and AWS's SDK signer. What those do not settle is listed under Unverified.
• It is not the EMQX emulator with another name: where the two vendors differ (@crvouga/mockingbird-service-emqx), each follows its own.

Install

npm install -D @crvouga/mockingbird-service-aws-iot

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-aws-iot serve or createServer from ./server (Node and Bun). createRuntime (the default entry) is portable: it serves Publish over fetch and MQTT through runtime.attach, with no listener.

Usage

Point the app's IoT data endpoint at url and its MQTT URL at mqttUrl or wsUrl. There is no TLS: use the http://, mqtt:// and ws:// URLs as given.

import { createServer } from "@crvouga/mockingbird-service-aws-iot/server"
import { IoTDataPlaneClient, PublishCommand } from "@aws-sdk/client-iot-data-plane"
import mqtt from "mqtt"

// Test setup: start the emulator with the credentials and authorizer policies the test needs.
const arn = (resource: string) => `arn:aws:iot:us-east-1:123456789012:${resource}`
const iot = await createServer({
  settings: {
    // HTTP: SigV4 signatures are verified against these keys.
    credentials: [{ accessKeyId: "test-key", secretAccessKey: "test-secret" }],
    // MQTT: what the custom authorizer answers for a username and password.
    authorizers: [
      {
        username: "alice",
        password: "alice-token",
        policyDocuments: [
          {
            Version: "2012-10-17",
            Statement: [
              { Effect: "Allow", Action: "iot:Connect", Resource: arn("client/alice-*") },
              { Effect: "Allow", Action: "iot:Subscribe", Resource: arn("topicfilter/user/alice") },
              { Effect: "Allow", Action: "iot:Receive", Resource: arn("topic/user/alice") },
            ],
          },
        ],
      },
    ],
  },
})

// Application code: the MQTT client and AWS SDK client it already uses, pointed at the emulator.
const device = await mqtt.connectAsync(iot.mqttUrl, {
  protocolVersion: 5,
  clientId: "alice-phone",
  clean: false,
  properties: { sessionExpiryInterval: 600 },
  username: "alice",
  password: "alice-token",
})
await device.subscribeAsync("user/alice", { qos: 1 })

const client = new IoTDataPlaneClient({
  region: "us-east-1",
  endpoint: iot.url,
  credentials: { accessKeyId: "test-key", secretAccessKey: "test-secret" },
})
await client.send(new PublishCommand({ topic: "user/alice", qos: 1, payload: '{"hello":"alice"}' }))

await device.endAsync()
await iot.close() // closes every listener and drops every client

npx mockingbird-aws-iot serve --port 8851 --mqtt-port 8883 \
  --credential test-key:test-secret --settings ./aws-iot-settings.json

Each createServer() is its own broker with its own ports; two of them share nothing. Under Bun, mqtt's Node WebSocket transport does not start (Bun's ws has no createWebSocketStream), so connect to wsUrl with the library's browser transport (new MqttClient((c) => browserStreamBuilder(c, options), options) from mqtt/lib/connect/ws), or use connectStream(runtime) from ./server for a socket-free connection. On Node the plain mqtt.connect("ws://…/mqtt") works.

Topics are what the client sends. AWS IoT separates levels with / and gives : no meaning, so an application that calls a topic user:example and publishes it as user/example does that mapping itself; the emulator, like AWS, never sees the first form.

Routes

SigV4. With credentials empty, any request carrying a well-formed Authorization: AWS4-HMAC-SHA256 … header is accepted unverified (as Mockingbird's other AWS emulators do), and an unsigned request is still refused. With credentials configured the signature must verify: service iotdata, the configured region, host and x-amz-date signed, the path encoded a second time in the canonical request (as every service but S3), the payload hash the SHA-256 of the body, and x-amz-security-token matching for temporary credentials. A credential's policyDocuments, when given, must allow iot:Publish on arn:aws:iot:<region>:<account>:topic/<topic>.

MQTT

MQTT 5.0 over TCP and over WebSocket at /mqtt (subprotocol mqtt). Both reach the same sessions, and the same sessions Publish delivers to.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets): publish_throttled (429 ThrottlingException), publish_unauthorized (401 UnauthorizedException), publish_internal_failure (500 InternalFailureException), connect_not_authorized (CONNACK 0x87), connect_bad_credentials (0x86), connect_quota_exceeded (0x97). A CONNECT is the fault operation MqttConnect, so any reason code can be forced: {"operationId": "MqttConnect", "effect": "connack", "params": {"reasonCode": 137}}.

Namespaces

Parallel workers isolate themselves by namespace. HTTP: x-mockingbird-namespace, a /__admin/ns/<name> prefix on the endpoint, or by access key id (PUT /__admin/credentials {"credentials": {"<AWS_ACCESS_KEY_ID>": "<namespace>"}}). MQTT: the WebSocket URL ws://…/__admin/ns/<name>/mqtt, or the same credential map keyed by the CONNECT's username (without its query string), then its client id. Unmapped clients use the default namespace.

Unverified

The documentation does not settle these; the emulator's choice is stated so a suite does not mistake it for the vendor's:

• The success body. The API reference says Publish answers an empty body; AWS's custom authentication tutorial shows {"message": "OK", "traceId": "…"}. The emulator sends the latter, which the SDK ignores.
• Refused credentials. For an unsigned request or a signature that does not verify the emulator answers 403 {"message": "Forbidden", "traceId"} with x-amzn-ErrorType: ForbiddenException: the body is the one AWS documents for a rejected custom-authorizer signature, the status and header are inferred. For a valid signature without iot:Publish it answers the documented 401 UnauthorizedException; whether AWS answers 401 or 403 there was not confirmed.
• Whether AWS sends x-amzn-ErrorType, the message text of each 400, and the HTTP error for a payload over 128 KB (the emulator uses 400 InvalidRequestException).
• "128 KB" and "146 KB" are taken as 131072 and 149504 bytes. AWS's MQTT page also says the Maximum Packet Size "cannot exceed 128 KB"; the quota page's 146 KB is used.
• What the client sees for isAuthenticated: false (AWS says it "terminates the connection"; the emulator sends CONNACK 0x87 first), for a topic over the limits or beginning with $ (AWS says such operations "can result in a terminated connection"; the emulator answers SUBACK 0x8F / PUBACK 0x90 and keeps the connection), and for an oversized MQTT payload (DISCONNECT 0x95).
• A QoS 2 SUBSCRIBE getting no SUBACK is AWS's documented behaviour, stated without a protocol version; it is applied to MQTT 5 as written.
• The Receive Maximum (100, from the quota on unacknowledged publishes), when Server Keep Alive is sent, the format of an assigned client id, and whether the Lambda event's username includes the query string (the emulator strips it).
• Signing dates are not checked against the clock, so a suite can freeze time.

Deliberately not modelled

• MQTT 3.1 and 3.1.1 (refused with that protocol's return code 1), TLS, X.509 client certificates, ALPN and SNI, and SigV4-presigned WebSocket URLs.
• Custom authorizers over HTTP, token signing, and disconnectAfterInSeconds / refreshAfterInSeconds (accepted, not enforced).
• Policy Condition, NotAction and NotResource (a document using them is refused), policy variables other than ${iot:ClientId}, and iot:RetainPublish.
• Retained messages: the CONNACK says Retain Available 0, a retained MQTT publish is answered DISCONNECT 0x9A, and retain=true over HTTP is 400. AWS itself supports them.
• Will messages (accepted in CONNECT, never published), shared subscriptions (SUBACK 0x9E), keep-alive timeouts, message expiry, outbound topic aliases, and reserved $aws/… topics.
• Rate and count quotas (publishes per second, subscriptions per connection or per SUBSCRIBE, the 10 messages per second replay of a stored session).
• The thing registry, shadows, rules and actions, jobs, provisioning, the other data-plane operations, billing and infrastructure management.

API

Part of mockingbird.