Platform Bootstrap & Passkey Enrollment #

TsubameMail separates platform operator identity (/v1/platform/*) from tenant users. On a fresh installation, the first super_admin is created via a one-time loopback-protected bootstrap ceremony.

Security Guarantees #

  • Loopback-Only Bootstrap: POST /v1/platform/bootstrap checks remoteIsLoopback and compares Authorization: Bearer <TSUBAME_PLATFORM_BOOTSTRAP_TOKEN> in constant time.
  • Single-Use Consumption: Once consumed, the bootstrap token is permanently marked used (ErrBootstrapConsumed); replaying it returns 409 Conflict or 403 Forbidden.
  • Mandatory User Verification: WebAuthn ceremonies enforce UserVerificationRequired and ResidentKey: required (passkey service).

Step-by-Step Enrollment #

  1. Generate the Bootstrap Token before starting control-backendd (TSUBAME_PLATFORM_BOOTSTRAP_TOKEN=GENERATE_ME in .env).
  2. Call Bootstrap on Loopback from the host running control-backendd:
bash
curl -sS -X POST http://127.0.0.1:8080/v1/platform/bootstrap \
  -H "Authorization: Bearer <YOUR_BOOTSTRAP_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"login": "root-admin"}'

Response (201 Created):

json
{
  "account_id": "pa_0123456789abcdef...",
  "enrollment_token": "<one-time-24h-token>",
  "expires_in_seconds": 86400
}
  1. Complete Passkey Enrollment in Browser: - Open https://admin.<your-domain> and choose Complete Bootstrap / Enroll Passkey. - Enter the enrollment_token, set a strong backup password, and register your FIDO2/WebAuthn Passkey (Touch ID, Windows Hello, or hardware security key). - Behind the scenes, the console calls POST /v1/platform/enrollment/options and POST /v1/platform/enrollment/finish.
  2. Generate Offline Recovery Codes: Immediately after signing in with your new Passkey (AAL2), open MFA Recovery and generate your 10 single-use recovery codes (xxxx-xxxx-xxxx-xxxx). Store them in an offline vault.
CAUTION

Never expose control-backendd port 8080 directly to the public internet. Always route external administrative traffic through https-proxy on port 443.