Setup State Machine

Every Oore CI instance progresses through a fixed sequence of states during first-run configuration. This page documents the state machine, transitions, and enforcement rules.

States

State	Description
uninitialized	Fresh database, no bootstrap token generated yet
bootstrap_pending	Bootstrap token generated, waiting for verification
idp_configured	OIDC provider configured and discovery validated
owner_created	Owner account created via OIDC verification
ready	Setup complete, all setup endpoints permanently disabled

Transitions

uninitialized → bootstrap_pending → idp_configured → owner_created → ready

From	To	Triggered by
uninitialized	bootstrap_pending	oore setup token generates a bootstrap token
bootstrap_pending	idp_configured	POST /v1/setup/oidc/configure succeeds
idp_configured	owner_created	POST /v1/setup/owner/verify-oidc succeeds
owner_created	ready	POST /v1/setup/complete succeeds

Transitions are strictly forward-only. There is no rollback mechanism — if you need to restart setup, delete the database and start fresh.

Endpoint availability by state

Setup endpoints are gated by the current state. Calling an endpoint in the wrong state returns 409 Conflict with code invalid_state.

Endpoint	Required state	Auth
GET /v1/public/setup-status	Any	None (public)
POST /v1/setup/bootstrap-token/verify	Any except ready	None
POST /v1/setup/oidc/configure	bootstrap_pending	Setup session
POST /v1/setup/owner/start-oidc	idp_configured	Setup session
POST /v1/setup/owner/verify-oidc	idp_configured	Setup session
POST /v1/setup/complete	owner_created	Setup session

Once the state reaches ready, all /v1/setup/* endpoints return 409 Conflict with code already_configured.

Setup sessions

Setup sessions are created by verifying a bootstrap token and have a 30-minute sliding-window TTL. Each authenticated request refreshes the expiry. The session token is a 32-byte random value; only its SHA-256 hash is stored.

Bootstrap tokens

Bootstrap tokens are generated by oore setup token:

• Size: 32 bytes (256 bits) of randomness via OsRng, hex-encoded (64 characters)
• Storage: Only the SHA-256 hash is stored in the database
• TTL: Configurable via --ttl (default: 15 minutes)
• Single-use: Consumed on first successful verification
• Rate limiting: After 5 failed attempts, further verification is blocked (429 Too Many Requests)

Checking current state

The setup status endpoint is always available, even after setup completes:

curl http://127.0.0.1:8787/v1/public/setup-status

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "ready",
  "setup_mode": false,
  "is_configured": true
}

See the Setup API reference for the full endpoint documentation.