moth

README

moth

Self-hosted authentication for your mobile apps — in one binary.
One instance hosts your whole portfolio of apps. No SaaS bill, no lock-in.

Website & docs · Quick start · Changelog · MIT

---

What & why

moth is a single Go binary that gives your mobile apps sign-up, sign-in, email verification, password reset, and Sign in with Google/Apple — backed by per-project ES256 JWTs any standard library can verify offline.

It also monetizes them: App Store and Google Play subscription receipts are validated server-side (no billing SaaS), the same tiers sell on the web through Stripe-hosted Checkout, and everything is distilled into entitlements like pro your app gates on, sold through a themed paywall configured from the admin, and reported as revenue per month on the analytics tab. A free tier is always built in, so paid subscriptions stay optional. On device, the first-party moth_billing plugin runs the native purchase itself — StoreKit 2 on iOS, Play Billing on Android — so selling needs one dependency and zero adapter code.

And it registers their devices for push notifications: every signed-in device reports its APNs / FCM / Web Push credential (with an honest permission state) through the moth_push plugin or the React useMothPush() hook, and your backend reads the live registry over moth.server.v1 and sends with the push services' own APIs. moth registers, your server sends — sender credentials never touch it, and dead tokens age out through sign-out, feedback, and staleness sweeps.

Every app you ship is a project: a sealed tenant with its own users, its own signing keypair, its own provider credentials, its own login branding, its own subscription tiers, its own analytics. Adding app #10 costs what app #1 did — one project created in the admin, zero new infrastructure.

Everything ships inside the binary: the SQLite database, the admin web console, the hosted email pages, the fonts, the Flutter SDK packages (moth_auth plus the moth_billing and moth_push native companions, served from the instance's own pub repository), the @moth/react React SDK (served from the instance's own npm registry), the CLI, and the documentation you're reading (served at /docs, version-matched to the binary). moth serve and you're running.

Reach for moth when you want Firebase-style auth for a portfolio of apps but would rather own the data, the bill, and the deployment.

Quick start

Four steps from nothing to a logged-in Flutter app (full version in the quick start guide):

# 1. Build the single binary (release binaries & Homebrew tap ship with v1.0).
make build            # → bin/moth

# 2. Run it. Open the admin, complete first-run setup, create a project,
#    and copy its publishable key (pk_…).
./bin/moth serve      # http://localhost:8080/admin

# 3. Add the SDK to your Flutter app from moth's own pub repository.
#    (dart pub speaks to the instance you just started.)
dart pub add moth_auth \
  --hosted-url http://localhost:8080/pub
#    React app instead? The instance serves an npm registry too:
#      echo '@moth:registry=http://localhost:8080/npm' >> .npmrc
#      npm install @moth/react

# 4. Point the client at your instance + project and sign a user in.

final moth = MothClient(
  baseUrl: 'http://localhost:8080',
  publishableKey: 'pk_...',
);
await moth.signUp(email: email, password: password);
final session = await moth.signIn(email: email, password: password);
// session.accessToken is an ES256 JWT verifiable against the project JWKS.

Deploy it for real

moth is CGO-free and self-contained, so deployment is "copy the binary + one data directory". The installation guide covers moth.toml, a hardened systemd unit, Docker, and reverse proxies (Caddy/Traefik/nginx) including the HTTP/2-end-to-end requirement native gRPC needs. A scratch-based image is a docker build . away (see Dockerfile).

docker build -t moth .
docker run -d -p 8080:8080 -v moth-data:/data \
  -e MOTH_BASE_URL=https://auth.example.com moth

Performance

argon2id password verification — deliberately slow — dominates SignIn cost, so honest throughput is tens-to-low-hundreds of sign-ins per second per core, with steady-state token refreshes far cheaper. moth ships a repeatable ghz harness at scripts/loadtest/ so you can measure the number on your hardware. This project does not quote a load figure it has not measured on the machine it attributes it to; recorded runs live in scripts/loadtest/RESULTS.md.

Development

See CONTRIBUTING.md and CLAUDE.md for the layout and conventions. Common targets:

Command	What
make build	build bin/moth (embeds the SPA + docs)
make test	go test ./...
make dev	Go server on :8080 + Vite SPA on :5173
make proto	regenerate gen/ + the TS client
make docs-embed	re-sync the embedded /docs from the website
make website	build the public website

License

MIT © 2026 Aloïs Deniel. The moth_auth Flutter SDK is MIT too.