README
¶
ESP RainMaker Neo - IoT Cloud
Tools
Documentation
Introduction
ESP RainMaker Neo is a serverless, open-source IoT cloud for ESP devices that you deploy into your own AWS account. It scales with your fleet and is pay-as-you-go. Devices connect over MQTT through AWS IoT. Phone apps, the admin dashboard and voice assistants reach the same backend over REST APIs and MQTT.
Repositories
| Repository | Holds |
|---|---|
| esp-rainmaker-neo | (this repository) Cloud backend, admin dashboard |
| esp-rainmaker-neo-firmware | Device firmware SDK |
| esp-rainmaker-home esp-rainmaker-neo-app-sdk-ts |
ESP RainMaker Home phone app (iOS and Android) ESP RainMaker Neo App SDK (TypeScript) |
Get Started
There are three ways to use it, in increasing order of involvement:
- Quick start: We host a public ESP RainMaker Neo deployment for facilitating evaluations and for hobbyists use. You don't need to do any cloud setup at all. Check out the detailed documentation here for more information.
- Deploy in your own account: Run the pre-built ESP RainMaker Neo cloud in your own AWS account. Check out the detailed documentation here for more information.
- Built From Source (Built-From-Source ESP RainMaker Neo): Build, modify and deploy the cloud yourself. This repository holds the cloud backend, its infrastructure, the admin dashboard, docs, and the test tooling. See BUILD.md for the full guide.
Specs & Documents
The cloud specification lives as Markdown under docs/en/specs/, with docs/en/index.md as the table of contents. The pages are readable directly in the repo; to build and view the HTML docs locally, see the docs build guide.
Contributing
Contributions are welcome — bug fixes, features, docs and tests alike. Start with CONTRIBUTING.md.
Bug reports and feature requests go through the issue templates; questions belong in Discussions.
Security
Never report a security vulnerability in a public issue. See SECURITY.md for the private reporting process and what to include.
Directories
¶
| Path | Synopsis |
|---|---|
|
src
|
|
|
alexa
Package alexa_skill defines the wire types used by the Alexa Smart Home skill Lambda.
|
Package alexa_skill defines the wire types used by the Alexa Smart Home skill Lambda. |
|
alexa/handlers/alexa_cfg
command
|
|
|
alexa/handlers/alexa_skill
command
|
|
|
awsutils/cognitoidputil
Package cognitoidputil provides Cognito Identity Pool utilities
|
Package cognitoidputil provides Cognito Identity Pool utilities |
|
awsutils/cognitoutil
Package cognitoutil provides Cognito authentication utilities
|
Package cognitoutil provides Cognito authentication utilities |
|
awsutils/kmsutil
Package kmsutil adapts an AWS KMS asymmetric key to crypto.Signer, so the private key never exists in this process.
|
Package kmsutil adapts an AWS KMS asymmetric key to crypto.Signer, so the private key never exists in this process. |
|
claim
Package claim holds the logic shared by the claim-initiate and claim-verify Lambdas: the configured variant, MAC normalization, claim-key construction, and the per-caller quota.
|
Package claim holds the logic shared by the claim-initiate and claim-verify Lambdas: the configured variant, MAC normalization, claim-key construction, and the per-caller quota. |
|
claim/ca_bootstrap
Package ca_bootstrap mints and publishes the assisted-claiming CA and holds the operator certificate configuration it mints from.
|
Package ca_bootstrap mints and publishes the assisted-claiming CA and holds the operator certificate configuration it mints from. |
|
claim/handlers/claim_admin
command
Claim admin API: superadmin-only configuration and bootstrap of the claiming CA.
|
Claim admin API: superadmin-only configuration and bootstrap of the claiming CA. |
|
claim/handlers/claim_handler
command
Claim handler lambda: POST /v1/claim/initiate and POST /v1/claim/verify.
|
Claim handler lambda: POST /v1/claim/initiate and POST /v1/claim/verify. |
|
espuser/auth
Package auth - Admin authentication service for admin users
|
Package auth - Admin authentication service for admin users |
|
espuser/clients
Package clients is the ESP User OAuth-client service over espuser-oauth-clients: create, list, patch, delete, enforcing the client write-invariants.
|
Package clients is the ESP User OAuth-client service over espuser-oauth-clients: create, list, patch, delete, enforcing the client write-invariants. |
|
espuser/db/admin_config_db
Table espuser-admin-config (PK config_name, SK subtype): admin-selected key-value config.
|
Table espuser-admin-config (PK config_name, SK subtype): admin-selected key-value config. |
|
espuser/db/auth_flows_db
Table espuser-auth-flows (PK flow_id): the TTL'd browser authorization-code flow record, from /oauth2/authorize through OTP login to the issued code (resolved by the by-code GSI at token exchange).
|
Table espuser-auth-flows (PK flow_id): the TTL'd browser authorization-code flow record, from /oauth2/authorize through OTP login to the issued code (resolved by the by-code GSI at token exchange). |
|
espuser/db/identity_providers_db
Table espuser-identity-providers: the upstream providers the federation broker may delegate to.
|
Table espuser-identity-providers: the upstream providers the federation broker may delegate to. |
|
espuser/db/oauth_clients_db
Table espuser-oauth-clients (PK client_id, no SK): the registered OAuth/OIDC client registry.
|
Table espuser-oauth-clients (PK client_id, no SK): the registered OAuth/OIDC client registry. |
|
espuser/db/refresh_tokens_db
Table espuser-refresh-tokens (PK user_id, SK client_id#family_id): one row per login family holding the current rotation counter.
|
Table espuser-refresh-tokens (PK user_id, SK client_id#family_id): one row per login family holding the current rotation counter. |
|
espuser/handlers/authorize
command
GET /oauth2/authorize (validate -> LOGIN flow record -> 302 to the login page with a flow_id cookie) and the served login UI.
|
GET /oauth2/authorize (validate -> LOGIN flow record -> 302 to the login page with a flow_id cookie) and the served login UI. |
|
espuser/handlers/clients
command
|
|
|
espuser/handlers/publish_discovery
command
Command publish_discovery builds the static OIDC/OAuth discovery documents and uploads them to S3, once, at deploy.
|
Command publish_discovery builds the static OIDC/OAuth discovery documents and uploads them to S3, once, at deploy. |
|
espuser/handlers/revoke
command
|
|
|
espuser/handlers/token
command
|
|
|
espuser/handlers/user_auth
command
Command user_auth serves the native /v1/user/auth/* password APIs.
|
Command user_auth serves the native /v1/user/auth/* password APIs. |
|
espuser/handlers/user_common
command
|
|
|
espuser/handlers/userinfo
command
|
|
|
espuser/idp
Package idp runs the upstream leg of a brokered login, with ESP User as a confidential client of an upstream IdP. It is deliberately independent of the client's downstream leg — see the "why brokered, not pass-through" argument in espuser/docs/en/specs/federation.md.
|
Package idp runs the upstream leg of a brokered login, with ESP User as a confidential client of an upstream IdP. It is deliberately independent of the client's downstream leg — see the "why brokered, not pass-through" argument in espuser/docs/en/specs/federation.md. |
|
espuser/legacyauth
Package legacyauth serves the native /v1/user/auth/* password APIs.
|
Package legacyauth serves the native /v1/user/auth/* password APIs. |
|
espuser/refreshtoken
Package refreshtoken is the ESP User refresh-token service: it owns the token lifecycle — mint a family on login, rotate-on-use with reuse=theft detection, and revoke — over the espuser-refresh-tokens store.
|
Package refreshtoken is the ESP User refresh-token service: it owns the token lifecycle — mint a family on login, rotate-on-use with reuse=theft detection, and revoke — over the espuser-refresh-tokens store. |
|
espuser/scope
Package scope is the single source of truth for ESP User's OAuth/OIDC scope values and space-delimited membership tests (RFC 6749 §3.3).
|
Package scope is the single source of truth for ESP User's OAuth/OIDC scope values and space-delimited membership tests (RFC 6749 §3.3). |
|
espuser/sender
Package sender resolves which SES identity the IdP sends mail from.
|
Package sender resolves which SES identity the IdP sends mail from. |
|
gva/handlers/gva_action
command
|
|
|
gva/handlers/gva_cfg
command
|
|
|
mcp/handlers/mcp_server
command
|
|
|
rmneo/db/processed_ts_db
Package db provides database operations for the RainMaker platform.
|
Package db provides database operations for the RainMaker platform. |
|
rmneo/handlers/file/admin_files
command
|
|
|
rmneo/handlers/group/group
command
|
|
|
rmneo/handlers/node/node_assoc
command
|
|
|
rmneo/handlers/node/node_conn
command
|
|
|
rmneo/handlers/node/node_reset
command
|
|
|
rmneo/handlers/node/node_service
command
|
|
|
rmneo/handlers/node/node_tags
command
|
|
|
rmneo/handlers/user/assume_role
command
|
|
|
rmneo/handlers/user/user_client
command
|
|
|
rmneo/handlers/user/user_creds
command
Command user_creds backs POST /v1/user/credentials: it verifies the presented bearer access token in-handler (no gateway authorizer) and exchanges it for Cognito Identity Pool credentials.
|
Command user_creds backs POST /v1/user/credentials: it verifies the presented bearer access token in-handler (no gateway authorizer) and exchanges it for Cognito Identity Pool credentials. |
|
rmneo/node/nodelifecycle
Package nodelifecycle hosts generic node-lifecycle hooks (node-left-group, node-offline).
|
Package nodelifecycle hosts generic node-lifecycle hooks (node-left-group, node-offline). |
|
rmneo/nodeadmin/bulk_job
Package bulk_job centralises the steps the registration and update Lambdas share when kicking off a bulk job: generate a request ID, write the node_reg_reqs row in `requested` state, and dispatch the shared Fargate task with the per-job env var set.
|
Package bulk_job centralises the steps the registration and update Lambdas share when kicking off a bulk job: generate a request ID, write the node_reg_reqs row in `requested` state, and dispatch the shared Fargate task with the per-job env var set. |
|
rmneo/nodeadmin/jobs_api
Package jobs_api centralises the read-side handlers shared by the registration and update Lambdas: status lookup and the paginated failed-nodes audit list.
|
Package jobs_api centralises the read-side handlers shared by the registration and update Lambdas: status lookup and the paginated failed-nodes audit list. |
|
rmneo/notification/integrationauth
Package integrationauth keeps the OAuth tokens we hold as a client of a user's linked third-party service fresh, so the notification senders can call out to Alexa, GVA, and webhooks.
|
Package integrationauth keeps the OAuth tokens we hold as a client of a user's linked third-party service fresh, so the notification senders can call out to Alexa, GVA, and webhooks. |
|
rmneo/service/timeseries/timewindow
Package timewindow provides time window management functionality for timeseries data processing.
|
Package timewindow provides time window management functionality for timeseries data processing. |
|
smartthings/handlers/st_action
command
|
|
|
smartthings/handlers/st_cfg
command
|
|
|
test/mock
Package mock provides mock implementations for AWS Cognito Provider
|
Package mock provides mock implementations for AWS Cognito Provider |
|
tools/rmng-lint
command
|
|
|
tools/rmng-lint/losterr
Package losterr reports errors that are constructed and then thrown away.
|
Package losterr reports errors that are constructed and then thrown away. |
|
utils/certissuer
Package certissuer produces device certificates from a validated public key under a named profile.
|
Package certissuer produces device certificates from a validated public key under a named profile. |
|
utils/httpclient
Package httpclient owns the process-wide outbound HTTP client so every outbound call shares one timeout and one seam tests can replace.
|
Package httpclient owns the process-wide outbound HTTP client so every outbound call shares one timeout and one seam tests can replace. |
|
utils/jsonutil
Package jsonutils converts between a dotted key path ("0x1.c.s.0x6.a.0x0") and its nested map form ({"0x1":{"c":{"s":{"0x6":{"a":{"0x0":<value>}}}}}}).
|
Package jsonutils converts between a dotted key path ("0x1.c.s.0x6.a.0x0") and its nested map form ({"0x1":{"c":{"s":{"0x6":{"a":{"0x0":<value>}}}}}}). |
|
utils/jwtutil
Package jwtutils holds reusable RS256 JWT + JWK helpers: sign a claim set with a kid-stamped header, verify a token against a JWK set, parse an RSA signing key, and build the public JWK/JWKS.
|
Package jwtutils holds reusable RS256 JWT + JWK helpers: sign a claim set with a kid-stamped header, verify a token against a JWK set, parse an RSA signing key, and build the public JWK/JWKS. |
|
utils/metrics
Package metrics provides CloudWatch Embedded Metrics Format (EMF) support for Lambda functions to emit custom metrics without API call overhead.
|
Package metrics provides CloudWatch Embedded Metrics Format (EMF) support for Lambda functions to emit custom metrics without API call overhead. |
|
utils/otputil
Package otputils holds generic, table-agnostic OTP helpers: id/code generation and salted-hash create/verify.
|
Package otputils holds generic, table-agnostic OTP helpers: id/code generation and salted-hash create/verify. |
|
utils/pkceutil
Package pkceutil derives and verifies RFC 7636 PKCE code challenges.
|
Package pkceutil derives and verifies RFC 7636 PKCE code challenges. |
|
utils/rlog
Package rlog provides a global logger for rmng.
|
Package rlog provides a global logger for rmng. |
|
utils/secretutil
Package secretutil generates cryptographically-random secrets/identifiers.
|
Package secretutil generates cryptographically-random secrets/identifiers. |
|
test
|
|
|
infra/handlers/test_webhook
command
|
|
|
infra/webhook
Package webhook is the business layer of the test webhook mock: the in-cloud stand-in for the third-party endpoints (Alexa, Google Voice Assistant, Matter command relay) the notifications flow POSTs to during integration tests.
|
Package webhook is the business layer of the test webhook mock: the in-cloud stand-in for the third-party endpoints (Alexa, Google Voice Assistant, Matter command relay) the notifications flow POSTs to during integration tests. |
Click to show internal directories.
Click to hide internal directories.