architecture docs
AWS

Security and access

Who and what can reach each part of the system, and how they prove who they are.

Devices

  • Each device has its own certificate, attached to its own thing. It can only connect with that certificate, under its own ID.
  • The device policy allows exactly three things: connect as itself, publish its own telemetry, and use its own shadow.
  • There’s no public URL that can lock or unlock a device. Commands only go through the outbox and the device shadow.
  • On dev and staging, self-registering virtual devices share a claim certificate that can only ask for a new identity. A Lambda approves it only for a fresh VIRTUAL- name, never a real device’s ID.

People

Owners

web app
  • Sign in with a code sent by SMS to their phone.
  • Age and identity checked by Persona.
  • Persona’s results arrive by a signed webhook.

Admin users

admin app
  • Email and password. No self-registration: admins create accounts.
  • Two roles: Admin (everything) and Staff (dashboard and device actions).
  • The last active admin can’t be removed or demoted.

The two apps share no code and keep separate sign-ins and cookies.

Infrastructure

  • Deploys: GitHub signs in to AWS with a short-lived token (OIDC) and a deploy role per stage. There are no AWS keys in GitHub. Staging’s role only accepts main.
  • Secrets (auth secrets, Twilio, Persona…) are stored per stage in SST, never in the repo.
  • Database: private on staging and production. Connections from Lambdas verify the database’s TLS certificate.
  • People’s AWS access goes through AWS IAM Identity Center, with one profile per stage’s account.
  • These docs are public: they hold no keys, passwords or account IDs.