@crvouga/mockingbird-service-aws-iot 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @crvouga/mockingbird-service-aws-iot
+
+## 0.1.0 (2026-10-11)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @crvouga/mockingbird-service-aws-iot discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-aws-iot/`; no repository checkout is needed to discover the emulator's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **HTTP Publish with SigV4, MQTT 5 sessions and custom-authorizer policies**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- aws-iot`.
+- Evidence model: Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual emulator result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `aws-iot`.

package/README.md

@@ -1,3 +1,235 @@
-# Temporary Holding Version
+# @crvouga/mockingbird-service-aws-iot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Local emulators. Real API contracts. Part of [Mockingbird](https://github.com/crvouga/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](https://github.com/crvouga/mockingbird/blob/main/packages/service/aws-iot/SUPPORT.md)
+- No AWS account was used as an oracle. Behaviour follows the
+  [Publish API reference](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_Publish.html),
+  the [MQTT](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html),
+  [custom authentication](https://docs.aws.amazon.com/iot/latest/developerguide/custom-auth.html),
+  [policy](https://docs.aws.amazon.com/iot/latest/developerguide/pub-sub-policy.html) and
+  [quota](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits)
+  pages, and AWS's SDK signer. What those do not settle is listed under [Unverified](#unverified).
+- It is not the EMQX emulator with another name: where the two vendors differ
+  (`@crvouga/mockingbird-service-emqx`), each follows its own.
+
+## Install
+
+```bash
+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.
+
+```ts
+import { createServer } from "@crvouga/mockingbird-service-aws-iot/server"
+import { IoTDataPlaneClient, PublishCommand } from "@aws-sdk/client-iot-data-plane"
+import mqtt from "mqtt"
+
+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") },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+})
+
+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
+```
+
+```bash
+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
+
+| Route | Behaviour |
+| --- | --- |
+| `POST /topics/{topic}?qos=0\|1` | IoTDataPlane `Publish`. The body is the payload, taken as the bytes sent. The topic is percent-decoded once (`user%2Fexample` is `user/example`; `a%252Fb` is the literal `a%2Fb`); unencoded slashes are accepted too, as in AWS's own examples. `200 {"message": "OK", "traceId": "…"}` whether or not anyone subscribes. Also read: `retain`, `contentType`, `responseTopic`, `messageExpiry` (adjusted into 1…604800), and the `x-amz-mqtt5-user-properties`, `x-amz-mqtt5-payload-format-indicator` and `x-amz-mqtt5-correlation-data` headers, which reach subscribers as MQTT 5 properties. |
+| errors | `{"message": "…", "traceId": "…"}` with `x-amzn-ErrorType`. `400 InvalidRequestException` for a topic that is empty, has wildcards, exceeds 256 bytes or 7 slashes, or starts with `$`; a `qos` other than 0 or 1; a bad `retain`, `messageExpiry` or MQTT 5 header; a malformed percent escape; a payload over 128 KB. `401 UnauthorizedException` when the signing identity's policy does not allow `iot:Publish` on the topic. `403` (`Forbidden`) when the request is unsigned or its signature does not verify. `405 MethodNotAllowedException` for any other verb or path. An `x-mockingbird-reason` header says which check failed. |
+
+**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.
+
+| Area | Behaviour |
+| --- | --- |
+| Authentication | Custom authentication only. `authorizers` lists the outcomes of a custom authorizer by MQTT username and password (the username's `?x-amz-customauthorizer-name=…` query is read and stripped); or pass `authorizer` to `createRuntime`, a function that receives the Lambda event (`protocolData.mqtt.{username, password (base64), clientId}`) and returns `{isAuthenticated, principalId, policyDocuments}`. No matching entry, `isAuthenticated: false`, a failing function, or a policy that does not allow `iot:Connect` on `client/<clientId>` is CONNACK `0x87`. With neither configured every client connects, allowed everything. |
+| Policies | `iot:Connect` on `client/<id>`, `iot:Publish` and `iot:Receive` on `topic/<name>`, `iot:Subscribe` on `topicfilter/<filter>`. Default deny; an explicit `Deny` overrides any `Allow`. `*` and `?` are wildcards (`*` spans levels); MQTT's `+` and `#` in a policy are ordinary characters, so a policy must name the filter a client subscribes with. `${iot:ClientId}` expands. A denied SUBSCRIBE is SUBACK `0x87`; a denied QoS 1 PUBLISH is PUBACK `0x87`; a subscriber without `iot:Receive` for a topic silently receives nothing from it. |
+| CONNACK | Maximum QoS 1, Retain Available 0 (see below), Maximum Packet Size 149504, Topic Alias Maximum 8, Receive Maximum 100, Wildcard Subscription Available 1, Subscription Identifier Available 0, Shared Subscription Available 0. Server Keep Alive when AWS would change the client's: 1200 for `0` or more than 1200, 30 for less than 30. |
+| Persistent sessions | Clean Start 0 with a Session Expiry Interval above 0. The interval is capped at the account quota (`persistentSessionExpirySeconds`, one hour by default, seven days at most) and the adjusted value is returned in the CONNACK. A session keeps its subscriptions and QoS 1 messages only (QoS 0 is not stored). The timer starts when the connection ends; at expiry the session and its queue are discarded. |
+| Client id | At most 128 bytes (CONNACK `0x85` beyond). A second connection with a connected client id is accepted and the first is sent DISCONNECT `0x8E`. |
+| Topics | At most 256 bytes and 7 forward slashes; topics and filters beginning with `$` are refused (SUBACK `0x8F`, PUBACK `0x90`). `sensor/#` matches `sensor/` and `sensor/a/b` and not `sensor`. |
+| QoS | 0 and 1. A SUBSCRIBE asking for QoS 2 gets no SUBACK; a QoS 2 PUBLISH is answered DISCONNECT `0x9B`. A publish nobody subscribes to is acknowledged `0x00`. |
+| Payload | At most 128 KB; a larger PUBLISH disconnects the client. |
+| Subscription Identifiers | Not supported, as on AWS: DISCONNECT `0xA1`. |
+
+### Admin (beyond the standard contract)
+
+| Route | Effect |
+| --- | --- |
+| `GET /__admin/publishes` | `{total, publishes}`: the last 1000 accepted publishes as metadata (`topic`, `qos`, `bytes`, `source: "http" \| "mqtt" \| "admin"`, `clientId`, `matched`, `at`). Payloads are never kept. |
+| `GET /__admin/clients`, `GET /__admin/clients/:clientId` | Sessions: `connected`, `transport`, `sessionExpiryInterval`, `expiresAt`, counts of `subscriptions`, `queued`, `inflight`; one session also lists its `topics`. |
+| `GET /__admin/subscriptions?clientId=` | Subscriptions: `topicFilter`, granted `qos`, options. |
+| `POST /__admin/inject` | `{topic, payload \| payloadBase64, qos?: 0 \| 1}`: deliver raw bytes to the topic's subscribers, bypassing signing, validation and publish policy (`iot:Receive` still applies). Use it for bytes a consumer's parser must refuse. Answers `{matched}`. |
+| `POST /__admin/transport/cut` | `{clientId?}`: a network outage for one client, or for all. Live connections die with no DISCONNECT and new CONNECTs are dropped unanswered. Sessions are untouched and expire on their own schedule. |
+| `POST /__admin/transport/restore` | `{clientId?}`: end the outage. `GET /__admin/transport` lists what is cut. |
+| `POST /__admin/clients/:clientId/disconnect` | `{reasonCode?}`: send DISCONNECT (default `0x98`) and close; the session stays. |
+| `GET` / `PUT /__admin/settings` | `{credentials?, authorizers?, region?, accountId?, persistentSessionExpirySeconds?}` for the calling namespace. A policy document the emulator cannot evaluate is refused with `400`. Reset returns to the values the runtime was created with. |
+| `POST /__admin/clock` | Standard. Moving the clock settles session expiry at once. |
+| `POST /__admin/reset`, checkpoints | Standard. Reset drops every connection and session. Restoring a checkpoint restores sessions, subscriptions and queues, and drops live connections. |
+
+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
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `createRuntime` | function | The emulator with the full service contract. Options: `settings`, `authorizer`, `clock`, `seed`, `adminPrefix`, `adminKey`, `onLog`, `sqlite`. Adds `attach(transport, info?, namespace?)` for an MQTT connection, `webSocketPath(pathname)`, `endpoints`, and `stop()`. |
+| `AwsIotAPI` | class | One namespace: `fetch(request)` for `Publish`, `broker` for MQTT, `state`, `reset()`. Options: `sqlite`, `now`, `namespace`, `settings`, `authorizer`, `connectFault`. |
+| `AWS_IOT_PRESETS` | object | Every named fault preset. |
+| `AWS_IOT_NAMESPACE` | string | The service name, `"aws-iot"`. |
+| `SIGNING_NAME` | string | `"iotdata"`, the SigV4 signing name. |
+| `MQTT_CONNECT_OPERATION`, `MQTT_WEBSOCKET_PATH` | strings | `"MqttConnect"`, the operation id a fault rule uses for a CONNECT; and `"/mqtt"`. |
+| `MAX_PAYLOAD_BYTES`, `MAX_PACKET_SIZE`, `MAX_TOPIC_BYTES`, `MAX_TOPIC_SLASHES`, `MAX_CLIENT_ID_BYTES`, `MAX_MESSAGE_EXPIRY_SECONDS`, `MAX_PERSISTENT_SESSION_EXPIRY_SECONDS`, `KEEP_ALIVE_RANGE` | numbers | AWS IoT Core's limits as the emulator enforces them. |
+| `DEFAULT_SETTINGS` | object | Region `us-east-1`, account `123456789012`, no credentials or authorizers, a one-hour session quota. |
+| `parseSettings` | function | Validate a settings patch from JSON; throws naming the field that is wrong. |
+| `parsePolicyDocument`, `isAllowed`, `resourceArn`, `PolicyError` | functions, class | Parse a policy document (object or JSON string), evaluate it for an action and target, and build the ARN an action is checked against. |
+| `accessKeyCredential`, `splitUsername` | functions | The access key id of a signed request; an MQTT username and the authorizer its query string names (how credentials map to namespaces). |
+| `ReasonCode` | object | MQTT 5 reason codes by name. |
+| `document`, `operationIds`, `supportedOperationIds` | values | The HTTP contract and its operation ids. |
+| `createServer`, `connectStream`, `loadSettingsFile`, `serveTarget`, `DEFAULT_PORT`, `DEFAULT_MQTT_PORT` (`./server`) | Node | Serve HTTP, WebSocket and TCP (`{url, mqttUrl, mqttPort, wsUrl, runtime, close()}`; options add `port`, `mqttPort`, `host`, `sweepMs`); an in-process MQTT stream; read a `--settings` file; the `serve` CLI target; ports 8851 and 8883. |
+
+Part of [mockingbird](https://github.com/crvouga/mockingbird).

package/SUPPORT.md

@@ -0,0 +1,11 @@
+# AWS IoT Core data plane (Mockingbird subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **1**
+- supported by the emulator: **1**
+- parity enabled: **1**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `Publish` | `POST /topics/{topic}` | ✅ supported | ⚠️ unsafe (opt-in) |  |