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/bootstrapchecksremoteIsLoopbackand comparesAuthorization: Bearer <TSUBAME_PLATFORM_BOOTSTRAP_TOKEN>in constant time. - Single-Use Consumption: Once consumed, the bootstrap token is permanently marked used (
ErrBootstrapConsumed); replaying it returns409 Conflictor403 Forbidden. - Mandatory User Verification: WebAuthn ceremonies enforce
UserVerificationRequiredandResidentKey: required(passkeyservice).
Step-by-Step Enrollment #
- Generate the Bootstrap Token before starting
control-backendd(TSUBAME_PLATFORM_BOOTSTRAP_TOKEN=GENERATE_MEin.env). - 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
}- Complete Passkey Enrollment in Browser: - Open
https://admin.<your-domain>and choose Complete Bootstrap / Enroll Passkey. - Enter theenrollment_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 callsPOST /v1/platform/enrollment/optionsandPOST /v1/platform/enrollment/finish. - 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.