Harden bootstrap user detection and managed user semantics

Author: pRizz

README.md

@@ -154,9 +154,10 @@ occ install
 occ start
 ```
 
-If this is the first startup with no configured users, the container logs will print an **Initial One-Time Password (IOTP)**.
+If this is the first startup with no configured managed users, the container logs will print an **Initial One-Time Password (IOTP)**.
 Open the login page, use the first-time setup panel, and enroll a passkey for the default `opencoder` account.
 The IOTP is invalidated after successful passkey enrollment.
+Built-in image users (for example `ubuntu`/`opencoder`) do not count as configured users for IOTP bootstrap.
 
 Quick IOTP extraction from logs:
 
@@ -359,12 +360,13 @@ occ config show
 opencode-cloud uses **PAM (Pluggable Authentication Modules)** for authentication.
 
 First boot path:
-- If no users are configured, startup logs print an Initial One-Time Password (IOTP).
+- If no managed users are configured, startup logs print an Initial One-Time Password (IOTP).
 - Extract only the IOTP quickly: `occ logs | grep -F "INITIAL ONE-TIME PASSWORD (IOTP): " | tail -n1 | sed 's/.*INITIAL ONE-TIME PASSWORD (IOTP): //'`
 - `occ setup` attempts to auto-detect and print the IOTP after starting/restarting the service.
 - Enter that IOTP in the web login page first-time setup panel.
 - Enroll a passkey for the default `opencoder` account.
 - The IOTP is deleted after successful passkey enrollment.
+- Built-in image users (for example `ubuntu`/`opencoder`) do not disable IOTP bootstrap.
 
 Admin path:
 - You can always create/manage users directly via `occ user add`, `occ user passwd`, and related user commands.
@@ -388,7 +390,7 @@ occ user add <username> --generate
 
 ### Managing Users
 
-- List users: `occ user list`
+- List users: `occ user list` (managed users only)
 - Change password: `occ user passwd <username>`
 - Remove user: `occ user remove <username>`
 - Enable/disable account: `occ user enable <username>` / `occ user disable <username>`
@@ -397,6 +399,7 @@ occ user add <username> --generate
 
 User accounts (including password hashes and lock status) persist across container updates and rebuilds.
 The CLI stores user records in a managed Docker volume mounted at `/var/lib/opencode-users` inside the container.
+This record store is the source of truth for configured users and bootstrap decisions.
 No plaintext passwords are stored on the host.
 
 ### Rebuilding the Docker Image

packages/cli-rust/src/commands/start.rs

@@ -575,34 +575,6 @@ fn display_network_exposure_warning(bind_addr: &str) {
     eprintln!();
 }
 
-fn display_bootstrap_mode_warning(bind_addr: &str) {
-    eprintln!();
-    eprintln!(
-        "{} {}",
-        style("Bootstrap mode enabled:").yellow().bold(),
-        style("no preconfigured users were found.").yellow()
-    );
-    eprintln!();
-    eprintln!(
-        "The service will start on {} and print an Initial One-Time Password (IOTP) in container logs.",
-        style(bind_addr).cyan()
-    );
-    eprintln!(
-        "{}",
-        style("Note: persisted users in /var/lib/opencode-users disable IOTP bootstrap.")
-            .yellow()
-            .dim()
-    );
-    eprintln!("Open the login page and use the first-time setup panel with that IOTP.");
-    eprintln!("The IOTP is invalidated immediately after the first successful passkey enrollment.");
-    eprintln!();
-    eprintln!(
-        "Admin alternative: {}",
-        style("occ user add <username>").dim()
-    );
-    eprintln!();
-}
-
 /// Start the opencode service
 ///
 /// This command:
@@ -715,12 +687,6 @@ pub async fn cmd_start(
     // Determine whether this is first container start
     let is_first_start = !container_exists(&client, CONTAINER_NAME).await?;
 
-    let bootstrap_mode =
-        is_first_start && config.users.is_empty() && !config.allow_unauthenticated_network;
-    if bootstrap_mode && !quiet {
-        display_bootstrap_mode_warning(bind_addr);
-    }
-
     // Check for port mismatch on existing container
     if !is_first_start
         && !recreate_container
@@ -874,7 +840,7 @@ pub async fn cmd_start(
         quiet,
         host_name.as_deref(),
     );
-    maybe_print_iotp_info(&client, host_name.as_deref(), &config, bootstrap_mode).await;
+    maybe_print_iotp_info(&client, host_name.as_deref(), &config).await;
     open_browser_if_requested(args.open, port, bind_addr);
 
     if args.no_daemon {
@@ -1204,12 +1170,13 @@ async fn maybe_print_iotp_info(
     client: &DockerClient,
     host: Option<&str>,
     config: &opencode_cloud_core::Config,
-    bootstrap_mode_hint: bool,
 ) {
     if config.allow_unauthenticated_network || !config.users.is_empty() {
         return;
     }
 
+    // The bootstrap helper is the source of truth after container startup.
+    // Do not infer onboarding state from pre-start config heuristics.
     let snapshot = fetch_iotp_snapshot(client).await;
 
     println!();
@@ -1234,23 +1201,16 @@ async fn maybe_print_iotp_info(
         "{}",
         style("Could not retrieve an IOTP from bootstrap state.").yellow()
     );
-    println!(
-        "Reason: {}",
-        iotp_unavailable_reason(&snapshot, bootstrap_mode_hint)
-    );
+    println!("Reason: {}", iotp_unavailable_reason(&snapshot));
     println!("Fetch logs with: {}", style("occ logs").cyan());
     println!("Try extracting IOTP with:\n  {IOTP_FALLBACK_COMMAND}");
 }
 
-fn iotp_unavailable_reason(snapshot: &IotpSnapshot, bootstrap_mode_hint: bool) -> String {
+fn iotp_unavailable_reason(snapshot: &IotpSnapshot) -> String {
     if let Some(reason) = snapshot.detail.as_deref() {
         return reason.to_string();
     }
 
-    if bootstrap_mode_hint {
-        return "bootstrap mode was requested but no active IOTP is available".to_string();
-    }
-
     format!("IOTP state is {}", snapshot.state_label)
 }
 
@@ -1519,20 +1479,21 @@ mod tests {
             otp: None,
             detail: Some("bootstrap helper unavailable".to_string()),
         };
-        let reason = super::iotp_unavailable_reason(&snapshot, true);
+        let reason = super::iotp_unavailable_reason(&snapshot);
         assert_eq!(reason, "bootstrap helper unavailable");
     }
 
     #[test]
-    fn iotp_unavailable_reason_uses_bootstrap_hint() {
+    fn iotp_unavailable_reason_does_not_invent_bootstrap_hint() {
         let snapshot = IotpSnapshot {
             state: IotpState::Unavailable,
             state_label: "unavailable".to_string(),
             otp: None,
             detail: None,
         };
-        let reason = super::iotp_unavailable_reason(&snapshot, true);
-        assert!(reason.contains("bootstrap mode was requested"));
+        let reason = super::iotp_unavailable_reason(&snapshot);
+        assert_eq!(reason, "IOTP state is unavailable");
+        assert!(!reason.contains("bootstrap mode was requested"));
     }
 
     #[test]
@@ -1543,7 +1504,7 @@ mod tests {
             otp: None,
             detail: None,
         };
-        let reason = super::iotp_unavailable_reason(&snapshot, false);
+        let reason = super::iotp_unavailable_reason(&snapshot);
         assert_eq!(reason, "IOTP state is inactive (users configured)");
     }
 }

packages/core/README.md

@@ -154,9 +154,10 @@ occ install
 occ start
 ```
 
-If this is the first startup with no configured users, the container logs will print an **Initial One-Time Password (IOTP)**.
+If this is the first startup with no configured managed users, the container logs will print an **Initial One-Time Password (IOTP)**.
 Open the login page, use the first-time setup panel, and enroll a passkey for the default `opencoder` account.
 The IOTP is invalidated after successful passkey enrollment.
+Built-in image users (for example `ubuntu`/`opencoder`) do not count as configured users for IOTP bootstrap.
 
 Quick IOTP extraction from logs:
 
@@ -359,12 +360,13 @@ occ config show
 opencode-cloud uses **PAM (Pluggable Authentication Modules)** for authentication.
 
 First boot path:
-- If no users are configured, startup logs print an Initial One-Time Password (IOTP).
+- If no managed users are configured, startup logs print an Initial One-Time Password (IOTP).
 - Extract only the IOTP quickly: `occ logs | grep -F "INITIAL ONE-TIME PASSWORD (IOTP): " | tail -n1 | sed 's/.*INITIAL ONE-TIME PASSWORD (IOTP): //'`
 - `occ setup` attempts to auto-detect and print the IOTP after starting/restarting the service.
 - Enter that IOTP in the web login page first-time setup panel.
 - Enroll a passkey for the default `opencoder` account.
 - The IOTP is deleted after successful passkey enrollment.
+- Built-in image users (for example `ubuntu`/`opencoder`) do not disable IOTP bootstrap.
 
 Admin path:
 - You can always create/manage users directly via `occ user add`, `occ user passwd`, and related user commands.
@@ -388,7 +390,7 @@ occ user add <username> --generate
 
 ### Managing Users
 
-- List users: `occ user list`
+- List users: `occ user list` (managed users only)
 - Change password: `occ user passwd <username>`
 - Remove user: `occ user remove <username>`
 - Enable/disable account: `occ user enable <username>` / `occ user disable <username>`
@@ -397,6 +399,7 @@ occ user add <username> --generate
 
 User accounts (including password hashes and lock status) persist across container updates and rebuilds.
 The CLI stores user records in a managed Docker volume mounted at `/var/lib/opencode-users` inside the container.
+This record store is the source of truth for configured users and bootstrap decisions.
 No plaintext passwords are stored on the host.
 
 ### Rebuilding the Docker Image

packages/core/src/docker/Dockerfile

@@ -162,7 +162,12 @@ RUN --mount=type=cache,target=/var/lib/apt/lists \
 # Create 'opencode' user with passwordless sudo
 RUN useradd -m -s /bin/bash -G sudo opencoder \
     && echo "opencoder ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/opencoder \
-    && chmod 0440 /etc/sudoers.d/opencoder
+    && chmod 0440 /etc/sudoers.d/opencoder \
+    # Snapshot built-in home users from the image so runtime auth logic can
+    # ignore defaults (e.g. ubuntu) when deciding if onboarding should run.
+    && install -d -m 0755 /etc/opencode-cloud \
+    && awk -F: '$6 ~ /^\/home\// {print $1}' /etc/passwd | sort -u > /etc/opencode-cloud/builtin-home-users.txt \
+    && chmod 0644 /etc/opencode-cloud/builtin-home-users.txt
 
 # Switch to opencode user for remaining setup
 USER opencoder

packages/core/src/docker/files/entrypoint.sh

@@ -92,6 +92,9 @@ export OPENCODE_PORT OPENCODE_HOST
 BOOTSTRAP_HELPER="/usr/local/bin/opencode-cloud-bootstrap"
 BOOTSTRAP_STATE_DIR="/var/lib/opencode-users"
 PROTECTED_USER="opencoder"
+BUILTIN_USERS_FILE="/etc/opencode-cloud/builtin-home-users.txt"
+FALLBACK_BUILTIN_HOME_USERS=("opencoder" "ubuntu")
+BUILTIN_HOME_USERS=()
 # NOTE: Do not change this prefix; admins may depend on it for log grep extraction.
 greppable_iotp_prefix="INITIAL ONE-TIME PASSWORD (IOTP): "
 
@@ -160,6 +163,43 @@ else
     # Ensure user records directory exists (ephemeral unless mounted)
     install -d -m 0700 /var/lib/opencode-users
 
+    load_builtin_home_users() {
+        BUILTIN_HOME_USERS=("${FALLBACK_BUILTIN_HOME_USERS[@]}")
+
+        if [ ! -r "${BUILTIN_USERS_FILE}" ]; then
+            return 0
+        fi
+
+        local username
+        while IFS= read -r username; do
+            username="$(printf "%s" "${username}" | tr -d '\r\n')"
+            if [ -n "${username}" ]; then
+                BUILTIN_HOME_USERS+=("${username}")
+            fi
+        done < "${BUILTIN_USERS_FILE}"
+    }
+
+    is_builtin_home_user() {
+        local username="$1"
+        local builtin
+        for builtin in "${BUILTIN_HOME_USERS[@]}"; do
+            if [ "${username}" = "${builtin}" ]; then
+                return 0
+            fi
+        done
+        return 1
+    }
+
+    user_record_path() {
+        local username="$1"
+        printf "/var/lib/opencode-users/%s.json" "${username}"
+    }
+
+    user_record_exists() {
+        local username="$1"
+        [ -f "$(user_record_path "${username}")" ]
+    }
+
     ensure_auth_config() {
         local config_dir="/home/opencoder/.config/opencode"
         local config_json="${config_dir}/opencode.json"
@@ -203,8 +243,8 @@ EOF
                 log "Skipping invalid user record: ${record}"
                 continue
             fi
-            if [ "${username}" = "${PROTECTED_USER}" ]; then
-                log "Skipping protected user record: ${record}"
+            if is_builtin_home_user "${username}"; then
+                log "Skipping built-in user record: ${record}"
                 continue
             fi
             if ! id -u "${username}" >/dev/null 2>&1; then
@@ -226,8 +266,8 @@ EOF
 
     persist_user_record() {
         local username="$1"
-        if [ "${username}" = "${PROTECTED_USER}" ]; then
-            log "Skipping persistence for protected user: ${username}"
+        if is_builtin_home_user "${username}"; then
+            log "Skipping persistence for built-in user: ${username}"
             return 0
         fi
         local shadow_hash
@@ -242,7 +282,8 @@ EOF
         if [ "${status}" = "L" ]; then
             locked="true"
         fi
-        local record_path="/var/lib/opencode-users/${username}.json"
+        local record_path
+        record_path="$(user_record_path "${username}")"
         umask 077
         jq -n --arg username "${username}" --arg hash "${shadow_hash}" --argjson locked "${locked}" '{username:$username,password_hash:$hash,locked:$locked}' > "${record_path}"
         chmod 600 "${record_path}"
@@ -275,26 +316,49 @@ EOF
     }
 
     has_non_protected_persisted_users() {
+        # Persisted records are the source of truth for managed login users.
+        # Built-in image users (e.g., ubuntu/opencoder) must not disable IOTP.
         shopt -s nullglob
         local records=(/var/lib/opencode-users/*.json)
         local record username
         for record in "${records[@]}"; do
             username="$(jq -r ".username // empty" "${record}" 2>/dev/null || true)"
-            if [ -n "${username}" ] && [ "${username}" != "${PROTECTED_USER}" ]; then
+            if [ -z "${username}" ]; then
+                continue
+            fi
+            if is_builtin_home_user "${username}"; then
+                continue
+            fi
+            if [ "${username}" != "${PROTECTED_USER}" ]; then
                 return 0
             fi
         done
 
-        local line home
+        return 1
+    }
+
+    migrate_unmanaged_home_users_to_records() {
+        # Migrate any non-built-in Linux users before bootstrap checks so real
+        # manually-created accounts disable IOTP in a consistent, managed way.
+        local line username home
         while IFS= read -r line; do
             username="$(cut -d: -f1 <<< "${line}")"
             home="$(cut -d: -f6 <<< "${line}")"
-            if [[ "${home}" == /home/* ]] && [ "${username}" != "${PROTECTED_USER}" ]; then
-                return 0
+            if [[ "${home}" != /home/* ]]; then
+                continue
+            fi
+            if is_builtin_home_user "${username}"; then
+                continue
+            fi
+            if user_record_exists "${username}"; then
+                continue
+            fi
+            if persist_user_record "${username}"; then
+                log "Migrated unmanaged user to managed records: ${username}"
+            else
+                log "WARNING: Failed to migrate unmanaged user to records: ${username}"
             fi
         done < <(getent passwd)
-
-        return 1
     }
 
     clear_bootstrap_state() {
@@ -381,8 +445,10 @@ EOF
         maybe_initialize_bootstrap_mode
     }
 
+    load_builtin_home_users
     ensure_auth_config
     restore_or_bootstrap_users
+    migrate_unmanaged_home_users_to_records
     sync_bootstrap_state
 
     log "Starting opencode on ${OPENCODE_HOST}:${OPENCODE_PORT}"