fba-go-admin

fba-go-admin is the official versioned Admin backend for fba-go. It owns the Admin runtime, built-in business modules, and reusable integrations. Project scaffolding is embedded in the fbago CLI and is not maintained in this repository.

Public Surface

• admin.Run and admin.Options: application bootstrap.
• modules/<id>.FBAPlugin: stable plugin facades for generated projects.
• plugins.yaml: module registration source of truth.
• internal/generated/fba_plugins.gen.go: deterministic generated registration.
• plugins.lock: resolved module metadata.

Generated projects depend on this module without copying its implementation:

go get github.com/yuWorm/fba-go-admin@v0.1.0
fbago plugin sync

Bootstrap administrator

Admin seed data deliberately creates a disabled admin account without a compiled-in password. Activate it exactly once after running migrations:

go run ./cmd/api admin bootstrap

ADMIN_BOOTSTRAP_PASSWORD supplies the password non-interactively. When it is empty, the command prompts for the password and confirmation without echoing either value. The generated development scaffold sets Admin@Local2026!; shared and deployed configuration must replace or remove that local-only credential.

Reset an existing user's password through the same runtime:

go run ./cmd/api admin set-password [username]

The username defaults to admin. The command reads and confirms the new password without echoing it, applies the configured password policy and history checks, then revokes the user's active sessions. Redirected stdin may supply the password and confirmation as two lines for secret-manager automation; the password is never accepted as a command argument.

TOTP two-factor authentication

Admin accounts can bind a standard authenticator app through the protected /api/v1/auth/2fa endpoints. Password and OAuth2 logins return two_factor_required, a single-use two_factor_challenge_token, and its expiry instead of creating a session when TOTP is enabled. Complete the login with POST /api/v1/auth/login/2fa.

Set TOTP_ENCRYPTION_KEY to an application-specific secret of at least 32 bytes. It defaults to TOKEN_SECRET_KEY, but a dedicated stable key prevents JWT signing-key rotation from making existing TOTP bindings unreadable. TOTP secrets are AES-GCM encrypted at rest; challenge tokens are hashed, expire after five minutes, permit five attempts, and are consumed atomically.

Binding lifecycle:

• GET /api/v1/auth/2fa: current binding status.
• POST /api/v1/auth/2fa/setup: re-authenticate with the current password and receive the provisioning URI and QR image.
• POST /api/v1/auth/2fa/confirm: confirm the first authenticator code.
• DELETE /api/v1/auth/2fa: disable TOTP with the current password and code.
• DELETE /api/v1/sys/users/:pk/2fa: superuser recovery for a lost device.

Development

Use the published fba-go dependency:

make tidy
make test
make run

To test against a sibling fba-go checkout without changing the release module file:

cp go.mod go.local.mod
go mod edit -modfile=go.local.mod \
  -replace github.com/yuWorm/fba-go=../fba-go
go mod tidy -modfile=go.local.mod
make L=1 test

Refresh and verify plugin registration with:

make generate
make check-generated

Release tags use ordinary root-module semantic versions such as v0.1.0.