README
¶
Cypra
Cypra is an open-source, self-hosted, multi-tenant authentication platform: a Go server with an embedded React dashboard, Postgres storage, hosted login, and a per-tenant OIDC issuer designed to be bootable by a small team in an afternoon.
The current implementation source of truth lives in PLAN.md, DESIGN.md, and BRAINSTORM.md. The original v1 product plan is archived at docs/archive/PLAN-2026-05-09-v1-product-plan.md, and the historical phase task log is archived at docs/archive/TASKS-2026-05-09-legacy-phases.md. Execution is tracked in TASKS.md.
Architecture
Cypra ships as one Go binary with an embedded dashboard SPA. The server exposes hosted login, per-tenant OIDC, REST admin APIs, health/readiness checks, metrics, storage URLs, and the dashboard from the same process. Postgres is the only required external data service; storage can be local disk or S3-compatible.
Tenant isolation is enforced at three layers: host-based tenant resolution, TenantScopedDB, and Postgres RLS. Each tenant has its own OIDC issuer (https://<tenant>.<install-domain>), WebAuthn RP ID, signing-key namespace, users, sessions, and OIDC clients.
Screenshots and visual walkthroughs are captured during the Phase 12/13 local canonical demo. See docs/firstrun.md for the first-run path and tests/e2e/lighthouse-baseline.json for the current hosted-login/dashboard baseline.
Prerequisites
- Go 1.26.1 via the pinned toolchain, with
go.modtargeting Go 1.25. - Bun 1.3.11.
- Docker Compose.
portlessfor HTTPS and wildcard tenant-subdomain local development.golangci-lint,gofumpt, andgoimports.
From Zero To Tests Pass
git clone https://github.com/watzon/cypra.git
cd cypra
bun install --frozen-lockfile
go mod download
make ci
The agent-friendly equivalent is:
./bin/agent-ci run --quiet --all
Local Development
Start the local development stack:
make dev
make dev creates .env from .env.example if needed, starts the compose-managed dev dependencies, starts portless with wildcard routing, registers https://cypra.localhost to Cypra, runs migrations, starts the dashboard Vite server, starts Cypra, and stops the dev compose services when you exit.
To manage only the compose dependencies:
make dev-up
make dev-down
Local HTTPS routes are served through portless:
https://cypra.localhosthttps://*.cypra.localhost
Docker Compose
The production compose stack keeps Cypra and Postgres private on the compose network. For a public VPS, copy .env.production.example, set a versioned CYPRA_IMAGE, and run the TLS profile so Caddy is the only public entrypoint:
cp .env.production.example .env.production
docker compose --env-file .env.production -f deploy/docker-compose.yml --profile with-tls up -d
For local development, use make dev instead. It layers deploy/docker-compose.dev.yml to publish local-only ports and runs HTTPS through portless.
To test an unpublished image locally:
docker build -t cypra:local .
CYPRA_IMAGE=cypra:local docker compose --env-file .env -f deploy/docker-compose.yml -f deploy/docker-compose.dev.yml up -d cypra
The Railway one-click recipe is documented in docs/deploy/railway-template.md. Publication of the separate Railway template repository is a deployment task.
Tests
make testruns Go and dashboard tests.make lintruns Go and dashboard linters.make typecheckruns Go vet and TypeScript checks.make ci-pipelineis the exact pipeline used by./bin/agent-ciand GitHub Actions.
Documentation
docs/architecture/overview.mdexplains the runtime architecture.docs/security/threat-model.mdcovers threats, secret handling, and GDPR posture.docs/contributing/testing.mddocuments CI and coverage floors.docs/contributing/extending.mdexplains auth, email, and storage extension points.docs/deploy/vps.mddescribes the single-host VPS recipe.docs/deploy/observability.mdcovers metrics, logs, traces, and error tracking.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
cypra
command
Package main provides the Cypra CLI entrypoint.
|
Package main provides the Cypra CLI entrypoint. |
|
Package dashboard embeds the built dashboard SPA into the Cypra binary.
|
Package dashboard embeds the built dashboard SPA into the Cypra binary. |
|
internal
|
|
|
audit
Package audit writes Cypra's append-only audit stream.
|
Package audit writes Cypra's append-only audit stream. |
|
auth
Package auth contains Phase 3 authorization scaffolding.
|
Package auth contains Phase 3 authorization scaffolding. |
|
auth/backupcodes
Package backupcodes implements one-time recovery codes for users and instance admins.
|
Package backupcodes implements one-time recovery codes for users and instance admins. |
|
auth/invite
Package invite implements tenant and instance-admin invitation flows.
|
Package invite implements tenant and instance-admin invitation flows. |
|
auth/magiclink
Package magiclink implements magic-link token issuance and consumption.
|
Package magiclink implements magic-link token issuance and consumption. |
|
auth/password
Package password implements password credentials and reset tokens.
|
Package password implements password credentials and reset tokens. |
|
auth/totp
Package totp implements TOTP enrollment and verification.
|
Package totp implements TOTP enrollment and verification. |
|
auth/upstream
Package upstream defines the Provider abstraction used by the social-SSO system and exposes a process-wide registry of registered providers.
|
Package upstream defines the Provider abstraction used by the social-SSO system and exposes a process-wide registry of registered providers. |
|
auth/upstream/apple
Package apple implements the Sign-in-with-Apple social provider.
|
Package apple implements the Sign-in-with-Apple social provider. |
|
auth/upstream/discord
Package discord implements the Discord social provider.
|
Package discord implements the Discord social provider. |
|
auth/upstream/github
Package github implements the GitHub social provider.
|
Package github implements the GitHub social provider. |
|
auth/upstream/google
Package google implements the Google upstream OAuth state and nonce checks.
|
Package google implements the Google upstream OAuth state and nonce checks. |
|
auth/upstream/microsoft
Package microsoft implements the Microsoft (Azure AD / Entra) social provider.
|
Package microsoft implements the Microsoft (Azure AD / Entra) social provider. |
|
auth/upstream/oidcgeneric
Package oidcgeneric implements a single-instance OIDC client used by Enterprise SSO connections.
|
Package oidcgeneric implements a single-instance OIDC client used by Enterprise SSO connections. |
|
auth/upstream/providers
Package providers imports every social-SSO provider package so that their init() functions register them in the upstream registry.
|
Package providers imports every social-SSO provider package so that their init() functions register them in the upstream registry. |
|
auth/webauthn
Package webauthn runs passkey ceremonies with per-tenant RP IDs.
|
Package webauthn runs passkey ceremonies with per-tenant RP IDs. |
|
auth/webauthn2fa
Package webauthn2fa provides a WebAuthn-backed second-factor seam.
|
Package webauthn2fa provides a WebAuthn-backed second-factor seam. |
|
authpolicy
Package authpolicy holds the per-tenant policy structs that govern auth provider behavior (password complexity, magic-link TTL, signup eligibility, allowed Google domains, etc.) and the helpers that load them from the tenant_auth_methods.config JSONB column.
|
Package authpolicy holds the per-tenant policy structs that govern auth provider behavior (password complexity, magic-link TTL, signup eligibility, allowed Google domains, etc.) and the helpers that load them from the tenant_auth_methods.config JSONB column. |
|
bootstrap
Package bootstrap implements first-boot setup-token handling.
|
Package bootstrap implements first-boot setup-token handling. |
|
botmitigation
Package botmitigation verifies bot-challenge tokens before auth flows.
|
Package botmitigation verifies bot-challenge tokens before auth flows. |
|
crypto
Package crypto contains Cypra's password hashing and envelope encryption primitives.
|
Package crypto contains Cypra's password hashing and envelope encryption primitives. |
|
db
Package db contains Cypra's tenant-scoped database boundary.
|
Package db contains Cypra's tenant-scoped database boundary. |
|
db/fuzz
Package fuzz contains the reusable tenant-isolation fuzzer harness that later phases use to enroll HTTP handlers.
|
Package fuzz contains the reusable tenant-isolation fuzzer harness that later phases use to enroll HTTP handlers. |
|
dbtest
Package dbtest provides Postgres-backed integration-test helpers.
|
Package dbtest provides Postgres-backed integration-test helpers. |
|
email
Package email sends transactional email through pluggable backends.
|
Package email sends transactional email through pluggable backends. |
|
hostedlogin
Package hostedlogin renders server-owned authentication pages.
|
Package hostedlogin renders server-owned authentication pages. |
|
httpserver
Package httpserver wires the Cypra HTTP surface.
|
Package httpserver wires the Cypra HTTP surface. |
|
logging
Package logging provides structured logging helpers.
|
Package logging provides structured logging helpers. |
|
migrate
Package migrate applies Cypra SQL migrations.
|
Package migrate applies Cypra SQL migrations. |
|
models
Package models defines GORM structs that mirror the SQL schema.
|
Package models defines GORM structs that mirror the SQL schema. |
|
observability
Package observability contains small OpenTelemetry helpers shared by runtime paths.
|
Package observability contains small OpenTelemetry helpers shared by runtime paths. |
|
oidc
Package oidc contains OIDC provider primitives.
|
Package oidc contains OIDC provider primitives. |
|
pat
Package pat manages personal access tokens.
|
Package pat manages personal access tokens. |
|
ratelimit
Package ratelimit implements Postgres-backed token buckets.
|
Package ratelimit implements Postgres-backed token buckets. |
|
sessions
Package sessions manages Cypra access and refresh sessions.
|
Package sessions manages Cypra access and refresh sessions. |
|
storage
Package storage abstracts binary object storage.
|
Package storage abstracts binary object storage. |
|
storage/localdisk
Package localdisk stores objects on local disk and signs proxy URLs.
|
Package localdisk stores objects on local disk and signs proxy URLs. |
|
storage/openstore
Package openstore wires the storage backends from configuration.
|
Package openstore wires the storage backends from configuration. |
|
storage/s3compat
Package s3compat stores objects in S3-compatible backends and presigns reads.
|
Package s3compat stores objects in S3-compatible backends and presigns reads. |
|
sdk
|
|
|
go
module
|