fix(M17): expire admin_mode after idle timeout, refresh on activity

admin_mode was cleared only by explicit logout and USB disconnect, never by
time. On a permanently attached host stdio_usb_connected() stays true, so one
login persisted indefinitely and anyone later reaching the host or cable
inherited admin.

Record an absolute time_us_64() deadline = now + ADMIN_IDLE_TIMEOUT_US (5 min)
whenever admin is granted (new commands_admin_grant(), called from every
cmd_login grant path). The dispatcher expires a stale session before honoring
any admin-gated command (clears admin_mode, refuses) and refreshes the deadline
after each successful admin command so active use extends the window. USB
disconnect now also clears the deadline. A zero deadline is treated as
never-expiring so direct admin_mode toggles (host harness) are not spuriously
logged out.

harness_commands gains an injectable time_us_64() and an assertion that an admin
command is allowed within the window (refreshing it) and refused + auto-cleared
after it. Host asan/valgrind/coverage/ci-check all 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Claude

serial/commands.c

@@ -3,6 +3,8 @@
 #include "hardware/buzzer.h"
 #include "storage/storage.h"
 #include "pico/stdlib.h"
+#include "pico/time.h"
+#include <stdint.h>
 #include <stdio.h>
 #include <string.h>
 #include <stdbool.h>
@@ -13,13 +15,37 @@
 
 bool admin_mode = false;
 
+// Absolute time_us_64() deadline at which an idle admin session auto-expires.
+// 0 means "no active session / no deadline armed" - the expiry check treats
+// that as never-expiring so code (or a host harness) that toggles admin_mode
+// directly without a login is not spuriously logged out.
+static uint64_t admin_deadline_us = 0;
+
 bool commands_is_admin(void) {
     return admin_mode;
 }
 
+void commands_admin_grant(void) {
+    admin_mode        = true;
+    admin_deadline_us = time_us_64() + ADMIN_IDLE_TIMEOUT_US;
+}
+
+// Expire a stale admin session: if admin mode is active, a deadline is armed,
+// and it has passed, clear admin mode (auto-logout) and report true so the
+// caller can refuse. Returns false if the session is still valid or inactive.
+static bool admin_session_expired(void) {
+    if (admin_mode && admin_deadline_us != 0 && time_us_64() >= admin_deadline_us) {
+        admin_mode        = false;
+        admin_deadline_us = 0;
+        return true;
+    }
+    return false;
+}
+
 void commands_on_disconnect(void) {
     if (admin_mode) {
-        admin_mode = false;
+        admin_mode        = false;
+        admin_deadline_us = 0;
         printf("[console] USB disconnected - admin session ended\r\n");
     }
 }
@@ -123,10 +149,19 @@ void commands_dispatch(int argc, char **argv) {
 
         const command_t *cmd = &COMMANDS[i];
 
-        if (cmd->requires_admin && !admin_mode) {
-            printf("error: '%s' requires admin mode - use login <otp>\r\n", cmd->name);
-            buzzer_play_command_ack();
-            return;
+        if (cmd->requires_admin) {
+            // Drop a session that has been idle too long before honoring it, so
+            // a long-attached host cannot inherit an old login.
+            if (admin_session_expired()) {
+                printf("error: admin session expired - use login <otp>\r\n");
+                buzzer_play_command_ack();
+                return;
+            }
+            if (!admin_mode) {
+                printf("error: '%s' requires admin mode - use login <otp>\r\n", cmd->name);
+                buzzer_play_command_ack();
+                return;
+            }
         }
 
         int user_args = argc - 1;
@@ -137,6 +172,10 @@ void commands_dispatch(int argc, char **argv) {
         }
 
         HANDLERS[i](argc, argv);
+
+        // Successful admin activity refreshes the idle window.
+        if (cmd->requires_admin && admin_mode)
+            commands_admin_grant();
         return;
     }
 

serial/commands.h

@@ -3,12 +3,21 @@
 
 #include <stdbool.h>
 
+// Admin sessions auto-expire after this many microseconds of inactivity. The
+// deadline is armed on login and refreshed by every successful admin command,
+// so an unattended-but-still-connected host cannot keep one login alive forever.
+#define ADMIN_IDLE_TIMEOUT_US (5ULL * 60 * 1000000ULL)
+
 // Dispatch a parsed command line
 void commands_dispatch(int argc, char **argv);
 
 // Returns true if currently in admin mode
 bool commands_is_admin(void);
 
+// Enter (or renew) admin mode and (re)arm the idle-timeout deadline. Called by
+// cmd_login on every successful grant and by the dispatcher on admin activity.
+void commands_admin_grant(void);
+
 // Called by console on USB disconnect - auto-logout
 void commands_on_disconnect(void);
 

serial/commands_system.c

@@ -1,3 +1,4 @@
+#include "commands.h"
 #include "commands_handlers.h"
 #include "commands.h"
 #include "hardware/buzzer.h"
@@ -154,7 +155,7 @@ void cmd_login(int argc, char **argv) {
     wifi_config_t wifi;
     if (storage_is_mounted() && !storage_wifi_get(&wifi)) {
         printf("warning: wifi not configured - open mode\r\n");
-        admin_mode = true;
+        commands_admin_grant();
         printf("login: admin mode enabled\r\n");
         buzzer_play_command_ack();
         return;
@@ -168,7 +169,7 @@ void cmd_login(int argc, char **argv) {
     if (!clock_get_unix_time(&now_unix)) {
         if (time_us_64() >= BOOT_BYPASS_WINDOW_US) {
             printf("warning: RTC not set - open mode\r\n");
-            admin_mode = true;
+            commands_admin_grant();
             printf("login: admin mode enabled\r\n");
             buzzer_play_command_ack();
         } else {
@@ -183,7 +184,7 @@ void cmd_login(int argc, char **argv) {
     // No admin keys - allow any credentials (bootstrap mode)
     if (!any_admin) {
         printf("warning: no admin keys configured - bootstrap mode\r\n");
-        admin_mode = true;
+        commands_admin_grant();
         printf("login: admin mode enabled\r\n");
         buzzer_play_command_ack();
         return;
@@ -213,7 +214,7 @@ void cmd_login(int argc, char **argv) {
         return;
     }
 
-    admin_mode = true;
+    commands_admin_grant();
     printf("login: admin mode enabled\r\n");
     secure_wipe(&key, sizeof(key));
     buzzer_play_command_ack();

test/harness_commands.c

@@ -25,6 +25,7 @@
 #include <assert.h>
 #include <fcntl.h>
 #include <stdbool.h>
+#include <stdint.h>
 #include <stdio.h>
 #include <string.h>
 #include <unistd.h>
@@ -33,6 +34,14 @@
 // test the admin gate without going through the real cmd_login/TOTP path.
 extern bool admin_mode;
 
+// Injectable host clock. commands.c calls time_us_64() to arm and check the
+// admin idle-timeout deadline; driving it here lets the idle-timeout test step
+// time deterministically instead of sleeping.
+static uint64_t g_now_us = 0;
+uint64_t        time_us_64(void) {
+    return g_now_us;
+}
+
 // ---------------------------------------------------------------------------
 // Spies
 // ---------------------------------------------------------------------------
@@ -261,6 +270,43 @@ static void test_on_disconnect_clears_admin(void) {
     assert(!commands_is_admin());
 }
 
+static void test_admin_session_idle_timeout(void) {
+    // A login arms a ~5-min idle window; admin commands inside it run and each
+    // refreshes the deadline, but a command issued after the window has elapsed
+    // is refused and the session is auto-cleared - so a permanently attached
+    // host cannot inherit an old login.
+    g_now_us = 1000;
+    commands_admin_grant(); // login path: enters admin + arms the deadline
+    assert(commands_is_admin());
+
+    // Just inside the window: an admin command runs (and refreshes the deadline).
+    g_now_us = 1000 + ADMIN_IDLE_TIMEOUT_US - 1;
+    run("list-keys", (const char *)NULL);
+    assert(g_last_handler != NULL && strcmp(g_last_handler, "cmd_list_keys") == 0);
+    assert(commands_is_admin());
+
+    // The refresh moved the deadline to now+timeout, so a second command another
+    // (almost) full window later is STILL allowed - total elapsed time already
+    // exceeds one window, proving activity extends the session.
+    g_now_us += ADMIN_IDLE_TIMEOUT_US - 1;
+    run("list-keys", (const char *)NULL);
+    assert(g_last_handler != NULL && strcmp(g_last_handler, "cmd_list_keys") == 0);
+    assert(commands_is_admin());
+
+    // Now go idle past the (refreshed) deadline: the next admin command is
+    // refused and admin mode is auto-cleared.
+    g_now_us += ADMIN_IDLE_TIMEOUT_US + 1;
+    run("list-keys", (const char *)NULL);
+    assert(g_last_handler == NULL); // handler did NOT run
+    assert(!commands_is_admin());   // auto-logged out
+    assert(out_has("expired"));
+
+    // Reset the injected clock to 0 so any deadline a later test's refresh arms
+    // stays in the future (the other tests toggle admin_mode directly).
+    g_now_us   = 0;
+    admin_mode = false;
+}
+
 int main(void) {
     test_routes_public_command();
     test_help_and_alias_route_same_handler();
@@ -275,6 +321,7 @@ int main(void) {
     test_admin_command_with_args_routes_when_admin();
     test_admin_gate_precedes_argc_check();
     test_on_disconnect_clears_admin();
+    test_admin_session_idle_timeout();
 
     printf("harness_commands: all assertions passed\n");
     return 0;