docs: add 2.5.1 changelog entries (#929)

Launch Web terminal sessions in /root as login shells so they load the root profile and display the configured prompt.

.devcontainer/Dockerfile

@@ -0,0 +1,52 @@
+# Dev container image for VS Code / the devcontainer CLI.
+#
+# The release builder image (docker/Dockerfile) stays the single source of
+# truth for the RISC-V cross toolchain, Go and MaixCDK. This layer only adds
+# the frontend toolchain on top: the builder image deliberately ships without
+# Node (`make web` runs on the host), but an IDE container should cover web
+# development as well.
+#
+# BASE_IMAGE can be overridden to a locally built builder image, e.g. the
+# output of `make builder-image` (nanokvm-builder-local-<uid>-<gid>).
+ARG BASE_IMAGE=ghcr.io/sipeed/nanokvm-builder:latest
+FROM ${BASE_IMAGE}
+
+USER root
+
+# Node major and pnpm major track .github/workflows/package.yml ("Set up
+# Node" / "Set up pnpm") and web/package.json "engines" -- keep all of them
+# in sync when CI bumps either.
+ARG NODE_MAJOR=22
+ARG PNPM_VERSION=11
+# Both can be overridden behind restrictive or mirrored corporate networks
+# via devcontainer.json, e.g.:
+#   "build": {"args": {
+#     "NODE_DIST_MIRROR": "https://registry.npmmirror.com/-/binary/node",
+#     "NPM_REGISTRY": "https://registry.npmmirror.com"
+#   }}
+ARG NODE_DIST_MIRROR=https://nodejs.org/dist
+ARG NPM_REGISTRY=https://registry.npmjs.org
+
+# Install the latest Node of the pinned major from official dist tarballs;
+# tracking the latest patch release is intentional (rebuild the container to
+# pick up updates). The SHA-256 check guards download integrity -- it shares
+# its origin with the tarball, so it is not an authenticity proof.
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y ca-certificates curl xz-utils; \
+    rm -rf /var/lib/apt/lists/*; \
+    case "$(uname -m)" in \
+        x86_64) node_arch=x64 ;; \
+        aarch64) node_arch=arm64 ;; \
+        *) echo "unsupported architecture: $(uname -m)" >&2; exit 1 ;; \
+    esac; \
+    curl -fsSL "${NODE_DIST_MIRROR}/latest-v${NODE_MAJOR}.x/SHASUMS256.txt" \
+        -o /tmp/SHASUMS256.txt; \
+    tarball="$(grep -o "node-v[0-9.]*-linux-${node_arch}\.tar\.xz" /tmp/SHASUMS256.txt | head -n1)"; \
+    curl -fsSL "${NODE_DIST_MIRROR}/latest-v${NODE_MAJOR}.x/${tarball}" -o "/tmp/${tarball}"; \
+    cd /tmp && grep " ${tarball}\$" SHASUMS256.txt | sha256sum -c -; \
+    tar -xJf "/tmp/${tarball}" -C /usr/local --strip-components=1 --no-same-owner; \
+    rm -f "/tmp/${tarball}" /tmp/SHASUMS256.txt; \
+    node --version && npm --version
+RUN npm install --global --registry "${NPM_REGISTRY}" "pnpm@${PNPM_VERSION}" \
+    && pnpm --version

.devcontainer/devcontainer.json

@@ -0,0 +1,49 @@
+// Dev container for NanoKVM: Go cross-compilation, MaixCDK C support layer
+// and web frontend in a single container. See "Development" in README.md.
+{
+  "name": "NanoKVM",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  // The Makefile and support/sg2002/build expect the repository at
+  // ~/NanoKVM of the baked-in "build" user -- mount it exactly there.
+  "workspaceMount": "source=${localWorkspaceFolder},target=/home/build/NanoKVM,type=bind,consistency=cached",
+  "workspaceFolder": "/home/build/NanoKVM",
+  "remoteUser": "build",
+  // The published builder image bakes in the CI runner's uid (currently
+  // 1001); on Linux hosts this remaps "build" to the local uid so the bind
+  // mount stays writable. The remap chowns /home/build once, which makes
+  // the first container creation noticeably slower.
+  "updateRemoteUserUID": true,
+  // Equivalent of `. ~/MaixCDK/bin/activate` for every process spawned in
+  // the container, interactive or not (tasks, extensions, exec).
+  "remoteEnv": {
+    "VIRTUAL_ENV": "/home/build/MaixCDK",
+    "PATH": "/home/build/MaixCDK/bin:${containerEnv:PATH}"
+  },
+  "forwardPorts": [3001],
+  "portsAttributes": {
+    "3001": {
+      "label": "web dev server (vite)"
+    }
+  },
+  "postCreateCommand": ".devcontainer/post-create.sh",
+  // This configuration itself mounts nothing from the host (VS Code may
+  // still forward your SSH agent and git credentials by default). To use
+  // git over SSH or reach a NanoKVM device from inside the container,
+  // uncomment the mount below.
+  // "mounts": [
+  //   "source=${localEnv:HOME}/.ssh,target=/home/build/.ssh,type=bind,readonly"
+  // ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "golang.go",
+        "ms-vscode.cpptools",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "bradlc.vscode-tailwindcss"
+      ]
+    }
+  }
+}

.devcontainer/post-create.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Runs once inside the dev container after it is created (see
+# .devcontainer/devcontainer.json). Keeps the container aligned with the
+# CLI flow in the Makefile and scripts/build-in-container.sh.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd)"
+
+# The MaixCDK components baked into the image can be older than this
+# checkout; resync them so C builds never use stale sources (same reason
+# scripts/build-in-container.sh runs update_lib first).
+"$repo_root/support/sg2002/build" update_lib
+
+# Frontend dependencies. postCreate has no TTY, and CI=true lets pnpm make
+# its non-interactive choices -- e.g. purging a node_modules tree that was
+# installed from the host OS through the bind mount.
+(cd "$repo_root/web" && CI=true pnpm install --frozen-lockfile)
+
+# Start every interactive shell with the MaixCDK virtualenv active,
+# mirroring `make shell`.
+activate_line='. "$HOME/MaixCDK/bin/activate"'
+if ! grep -qxF "$activate_line" "$HOME/.bashrc" 2>/dev/null; then
+    printf '\n# MaixCDK virtualenv (added by .devcontainer/post-create.sh)\n%s\n' \
+        "$activate_line" >>"$HOME/.bashrc"
+fi
+
+# The build user's home has no shell skeleton files (useradd ran with
+# --no-create-home), so login shells would skip ~/.bashrc; give them the
+# standard Debian chain.
+if [ ! -f "$HOME/.profile" ]; then
+    cat >"$HOME/.profile" <<'EOF'
+# ~/.profile (added by .devcontainer/post-create.sh)
+if [ -n "$BASH_VERSION" ] && [ -f "$HOME/.bashrc" ]; then
+    . "$HOME/.bashrc"
+fi
+EOF
+fi

.github/workflows/builder-image.yml

@@ -0,0 +1,132 @@
+name: Builder Image
+
+# Builds the nanokvm-builder image (riscv64 musl toolchain, Go, and a MaixCDK
+# checkout patched with support/sg2002/additional) and publishes it to GHCR so
+# the release workflow does not have to rebuild the SDK on every tag.
+#
+# The image is deliberately not rebuilt on every push: it only carries the
+# toolchain. Release builds re-sync support/sg2002/additional into MaixCDK and
+# recompile from the checked-out source, so a slightly stale image is harmless.
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - docker/**
+      - .github/workflows/builder-image.yml
+
+concurrency:
+  group: builder-image
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build and publish nanokvm-builder
+    runs-on: ubuntu-latest
+    timeout-minutes: 240
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Free up disk space
+        run: |
+          echo "Before:"
+          df -h /
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc \
+                      /usr/local/share/boost /usr/local/share/powershell
+          sudo docker image prune -af
+          echo "After:"
+          df -h /
+
+      - name: Resolve image reference
+        id: image
+        env:
+          OWNER: ${{ github.repository_owner }}
+        run: |
+          # GHCR only accepts lowercase repository paths.
+          owner=$(echo "$OWNER" | tr '[:upper:]' '[:lower:]')
+          echo "ref=ghcr.io/$owner/nanokvm-builder" >> "$GITHUB_OUTPUT"
+
+      # Logging in before the build means a credential or registry problem fails
+      # in seconds instead of after a full SDK build.
+      - name: Log in to GHCR
+        env:
+          GHCR_USER: ${{ github.actor }}
+          GHCR_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          ok=0
+          for attempt in 1 2 3; do
+            if printf '%s' "$GHCR_TOKEN" \
+                 | docker login ghcr.io -u "$GHCR_USER" --password-stdin; then
+              ok=1
+              break
+            fi
+            echo "login attempt $attempt failed, retrying in 15s"
+            sleep 15
+          done
+          if [ "$ok" -ne 1 ]; then
+            echo "::error::could not log in to ghcr.io after 3 attempts"
+            exit 1
+          fi
+
+      - name: Build image
+        run: |
+          # The Dockerfile chowns MaixCDK to DOCKER_UID/DOCKER_GID and the
+          # entrypoint gosu's to the caller's ids, so bake in the ids the
+          # release job will actually run as. Otherwise the SDK tree belongs to
+          # 1000 and syncing components into it fails with permission denied.
+          docker build \
+            --build-arg DOCKER_UID="$(id -u)" \
+            --build-arg DOCKER_GID="$(id -g)" \
+            --tag "${{ steps.image.outputs.ref }}:latest" \
+            --tag "${{ steps.image.outputs.ref }}:${{ github.sha }}" \
+            --file docker/Dockerfile \
+            .
+
+      - name: Verify toolchain
+        run: |
+          docker run --rm -i "${{ steps.image.outputs.ref }}:latest" go version
+          docker run --rm -i "${{ steps.image.outputs.ref }}:latest" \
+            riscv64-unknown-linux-musl-gcc --version | head -1
+          docker run --rm -i "${{ steps.image.outputs.ref }}:latest" patchelf --version
+
+      - name: Push image
+        env:
+          IMAGE_REF: ${{ steps.image.outputs.ref }}
+          SHA: ${{ github.sha }}
+        run: |
+          # ghcr.io occasionally times out; a retry is cheaper than rebuilding.
+          # Push the immutable sha tag first so a failure there cannot leave
+          # :latest — which release.yml pulls — already moved.
+          for tag in "$SHA" latest; do
+            ok=0
+            for attempt in 1 2 3; do
+              if docker push "$IMAGE_REF:$tag"; then
+                ok=1
+                break
+              fi
+              echo "push of $tag attempt $attempt failed, retrying in 15s"
+              sleep 15
+            done
+            if [ "$ok" -ne 1 ]; then
+              echo "::error::could not push $IMAGE_REF:$tag after 3 attempts"
+              exit 1
+            fi
+          done
+
+      - name: Summary
+        run: |
+          {
+            echo "### Builder image published"
+            echo
+            echo '```'
+            echo "${{ steps.image.outputs.ref }}:latest"
+            echo "${{ steps.image.outputs.ref }}:${{ github.sha }}"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/create-tag.yml

@@ -0,0 +1,108 @@
+name: NanoKVM Create Tag
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Numeric version to tag, e.g. 2.5.0
+        required: true
+        type: string
+      commit_sha:
+        description: Full commit SHA on main (empty uses latest main)
+        required: false
+        default: ''
+        type: string
+
+concurrency:
+  group: create-tag-${{ inputs.version }}
+  cancel-in-progress: false
+
+jobs:
+  create-tag:
+    name: Create annotated tag
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: main
+
+      - name: Validate target
+        id: target
+        env:
+          COMMIT_INPUT: ${{ inputs.commit_sha }}
+          VERSION_INPUT: ${{ inputs.version }}
+        run: |
+          VERSION="$VERSION_INPUT"
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "::error::invalid version '$VERSION', expected MAJOR.MINOR.PATCH"
+            exit 1
+          fi
+
+          git fetch --force --tags origin main
+
+          if [ -n "$COMMIT_INPUT" ]; then
+            if ! echo "$COMMIT_INPUT" | grep -qE '^[0-9a-fA-F]{40}$'; then
+              echo "::error::commit_sha must be a full 40-character hexadecimal SHA"
+              exit 1
+            fi
+            TARGET_SHA=$(git rev-parse "${COMMIT_INPUT}^{commit}" 2>/dev/null) || {
+              echo "::error::commit '$COMMIT_INPUT' does not exist"
+              exit 1
+            }
+          else
+            TARGET_SHA=$(git rev-parse 'origin/main^{commit}')
+          fi
+
+          if ! git merge-base --is-ancestor "$TARGET_SHA" origin/main; then
+            echo "::error::commit '$TARGET_SHA' is not reachable from origin/main"
+            exit 1
+          fi
+
+          set +e
+          git ls-remote --exit-code --tags origin "refs/tags/$VERSION" >/dev/null
+          TAG_STATUS=$?
+          set -e
+          case "$TAG_STATUS" in
+            0)
+              echo "::error::tag '$VERSION' already exists"
+              exit 1
+              ;;
+            2) ;;
+            *)
+              echo "::error::failed to check whether tag '$VERSION' exists"
+              exit 1
+              ;;
+          esac
+
+          echo "sha=$TARGET_SHA" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Create and push tag
+        env:
+          TARGET_SHA: ${{ steps.target.outputs.sha }}
+          VERSION: ${{ steps.target.outputs.version }}
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git tag -a "$VERSION" "$TARGET_SHA" -m "Release $VERSION"
+          git push origin "refs/tags/$VERSION"
+          ./scripts/verify-release-tag.sh "$VERSION" "$TARGET_SHA" >/dev/null
+
+      - name: Summary
+        env:
+          TARGET_SHA: ${{ steps.target.outputs.sha }}
+          VERSION: ${{ steps.target.outputs.version }}
+        run: |
+          {
+            echo '### NanoKVM tag created'
+            echo
+            echo "- Tag: \`$VERSION\`"
+            echo "- Commit: \`$TARGET_SHA\`"
+            echo
+            echo 'No package, GitHub Release, or CDN object was created.'
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/issue-tracker.yml

@@ -2,7 +2,7 @@ name: Issue Tracker
 
 on:
   issues:
-    types: [opened, reopened]
+    types: [opened, reopened, closed]
 
 jobs:
   track-issue:
@@ -28,8 +28,10 @@ jobs:
             --arg state "${{ github.event.issue.state }}" \
             --arg created_at "${{ github.event.issue.created_at }}" \
             --arg updated_at "${{ github.event.issue.updated_at }}" \
+            --arg closed_at "${{ github.event.issue.closed_at }}" \
             --arg url "${{ github.event.issue.html_url }}" \
             --arg user_login "${{ github.event.issue.user.login }}" \
+            --arg repository "${{ github.repository }}" \
             --argjson labels "$RAW_LABELS" \
             --argjson assignees "$RAW_ASSIGNEES" \
             '{
@@ -42,11 +44,13 @@ jobs:
                 state: $state,
                 created_at: $created_at,
                 updated_at: $updated_at,
+                closed_at: $closed_at,
                 url: $url,
                 user: { login: $user_login },
                 labels: $labels,
                 assignees: $assignees
-              }
+              },
+              repository: { name: $repository },
             }')
 
           RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$API_URL" \

.github/workflows/package.yml

@@ -0,0 +1,296 @@
+name: NanoKVM Package
+
+# Builds nanokvm_<version>.tar.gz and the latest.json manifest that the
+# on-device updater consumes (server/service/application/). Pull requests get a
+# uniquely identified, short-lived test artifact. Release publication is a
+# separate, explicit workflow that calls this one for an existing tag.
+#
+# This workflow does NOT publish to cdn.sipeed.com. Uploading latest.json is what
+# actually offers the update to every device in the field, so that step stays
+# manual and deliberate.
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - .github/workflows/create-tag.yml
+      - .github/workflows/package.yml
+      - .github/workflows/release.yml
+      - kvmapp/**
+      - scripts/**
+      - server/**
+      - support/**
+      - tools/nanokvm_update_edid/**
+      - web/**
+      - Makefile
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Version to package, e.g. 2.4.4
+        required: true
+        type: string
+  workflow_call:
+    inputs:
+      version:
+        description: Numeric version to package
+        required: true
+        type: string
+      ref:
+        description: Existing tag or commit to check out
+        required: true
+        type: string
+    outputs:
+      artifact_name:
+        description: Uploaded Actions artifact name
+        value: ${{ jobs.package.outputs.artifact_name }}
+      version:
+        description: Packaged version
+        value: ${{ jobs.package.outputs.version }}
+
+concurrency:
+  group: package-${{ github.event.pull_request.number || inputs.ref || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  package:
+    name: Build package
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    outputs:
+      artifact_name: ${{ steps.version.outputs.artifact_name }}
+      version: ${{ steps.version.outputs.version }}
+    permissions:
+      contents: read
+      packages: read
+
+    steps:
+      - name: Checkout event ref
+        if: inputs.ref == ''
+        uses: actions/checkout@v4
+        with:
+          # package.sh derives SOURCE_DATE_EPOCH from the commit date.
+          fetch-depth: 0
+          # Build scripts from a pull request must not inherit checkout's token.
+          persist-credentials: false
+
+      - name: Checkout requested ref
+        if: inputs.ref != ''
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ inputs.ref }}
+
+      - name: Resolve version
+        id: version
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          INPUT_VERSION: ${{ inputs.version }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          BUILD_SHA=$(git rev-parse HEAD)
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            VERSION="0.${PR_NUMBER}.${GITHUB_RUN_NUMBER}"
+            SOURCE_SHA="$HEAD_SHA"
+          elif [ -n "$INPUT_VERSION" ]; then
+            VERSION="$INPUT_VERSION"
+            SOURCE_SHA="$BUILD_SHA"
+          else
+            VERSION="$REF_NAME"
+            SOURCE_SHA="$BUILD_SHA"
+          fi
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "::error::invalid version '$VERSION', expected MAJOR.MINOR.PATCH"
+            exit 1
+          fi
+          if [ -z "$SOURCE_SHA" ]; then
+            echo "::error::could not resolve source commit"
+            exit 1
+          fi
+          SHORT_SHA=$(printf '%s' "$SOURCE_SHA" | cut -c1-12)
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            ARTIFACT_NAME="nanokvm-pr-${PR_NUMBER}-${SHORT_SHA}-run-${GITHUB_RUN_ID}-attempt-${GITHUB_RUN_ATTEMPT}"
+          else
+            ARTIFACT_NAME="nanokvm-${VERSION}-${SHORT_SHA}-run-${GITHUB_RUN_ID}-attempt-${GITHUB_RUN_ATTEMPT}"
+          fi
+          {
+            echo "artifact_name=$ARTIFACT_NAME"
+            echo "build_sha=$BUILD_SHA"
+            echo "source_sha=$SOURCE_SHA"
+            echo "version=$VERSION"
+          } >> "$GITHUB_OUTPUT"
+          echo "Packaging version $VERSION as $ARTIFACT_NAME"
+
+      - name: Free up disk space
+        run: |
+          df -h /
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
+          df -h /
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Set up pnpm
+        run: npm install --global pnpm@11
+
+      - name: Build frontend
+        run: make web
+
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request'
+        env:
+          GHCR_USER: ${{ github.actor }}
+          GHCR_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          ok=0
+          for attempt in 1 2 3; do
+            if printf '%s' "$GHCR_TOKEN" \
+                 | docker login ghcr.io -u "$GHCR_USER" --password-stdin; then
+              ok=1
+              break
+            fi
+            echo "login attempt $attempt failed, retrying in 15s"
+            sleep 15
+          done
+          if [ "$ok" -ne 1 ]; then
+            echo "::error::could not log in to ghcr.io after 3 attempts"
+            exit 1
+          fi
+
+      - name: Pull builder image
+        id: image
+        env:
+          OWNER: ${{ github.repository_owner }}
+        run: |
+          # GHCR only accepts lowercase repository paths.
+          # shellcheck disable=SC2153 # OWNER is supplied through the step environment.
+          owner=$(echo "$OWNER" | tr '[:upper:]' '[:lower:]')
+          IMAGE_REPO="ghcr.io/$owner/nanokvm-builder"
+          TAGGED_REF="${IMAGE_REPO}:latest"
+          ok=0
+          for attempt in 1 2 3; do
+            if docker pull "$TAGGED_REF"; then
+              ok=1
+              break
+            fi
+            echo "pull attempt $attempt failed, retrying in 15s"
+            sleep 15
+          done
+          if [ "$ok" -ne 1 ]; then
+            echo "::error::could not pull $TAGGED_REF - run the 'Builder Image' workflow first and ensure PR builds can pull it without credentials"
+            exit 1
+          fi
+          RESOLVED_REF=$(docker image inspect --format='{{index .RepoDigests 0}}' "$TAGGED_REF")
+          case "$RESOLVED_REF" in
+            "$IMAGE_REPO"@sha256:*) ;;
+            *)
+              echo "::error::could not resolve immutable digest for $TAGGED_REF (got '$RESOLVED_REF')"
+              exit 1
+              ;;
+          esac
+          echo "Pulled $RESOLVED_REF"
+          echo "ref=$RESOLVED_REF" >> "$GITHUB_OUTPUT"
+
+      - name: Build riscv64 artifacts
+        run: |
+          make release-build \
+            DOCKER_TTY= \
+            IMAGE_NAME="${{ steps.image.outputs.ref }}"
+
+      - name: Assemble package
+        run: make package VERSION="${{ steps.version.outputs.version }}"
+
+      - name: Compare against the published release
+        # Informational only: highlights what changed relative to what devices
+        # are currently running. Never blocks the build.
+        continue-on-error: true
+        run: |
+          ./scripts/compare-release.sh \
+            "build/release/nanokvm_${{ steps.version.outputs.version }}.tar.gz"
+
+      - name: Write build provenance
+        env:
+          ARTIFACT_NAME: ${{ steps.version.outputs.artifact_name }}
+          BUILDER_IMAGE: ${{ steps.image.outputs.ref }}
+          BUILD_SHA: ${{ steps.version.outputs.build_sha }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          SOURCE_SHA: ${{ steps.version.outputs.source_sha }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          TARBALL="build/release/nanokvm_${VERSION}.tar.gz"
+          TARBALL_NAME=$(basename "$TARBALL")
+          SHA256_HEX=$(sha256sum "$TARBALL" | cut -d' ' -f1)
+          SHA512_HEX=$(sha512sum "$TARBALL" | cut -d' ' -f1)
+          SHA512_BASE64=$(jq -er '.sha512 | select(type == "string" and length > 0)' \
+            build/release/latest.json)
+          ACTUAL_BASE64=$(openssl dgst -sha512 -binary "$TARBALL" | openssl base64 -A)
+          if [ "$SHA512_BASE64" != "$ACTUAL_BASE64" ]; then
+            echo "::error::latest.json sha512 does not match $TARBALL"
+            exit 1
+          fi
+          printf '%s  %s\n' "$SHA256_HEX" "$TARBALL_NAME" > build/release/sha256.txt
+          {
+            echo "artifact=${ARTIFACT_NAME}"
+            echo "version=${VERSION}"
+            echo "event=${GITHUB_EVENT_NAME}"
+            echo "pull_request=${PR_NUMBER}"
+            echo "source_sha=${SOURCE_SHA}"
+            echo "build_sha=${BUILD_SHA}"
+            echo "builder_image=${BUILDER_IMAGE}"
+            echo "run_id=${GITHUB_RUN_ID}"
+            echo "run_attempt=${GITHUB_RUN_ATTEMPT}"
+            echo "run_url=https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+            echo "tarball=${TARBALL_NAME}"
+            echo "sha256_hex=${SHA256_HEX}"
+            echo "sha512_hex=${SHA512_HEX}"
+            echo "sha512_base64=${SHA512_BASE64}"
+          } > build/release/BUILD_INFO.txt
+
+      - name: Verify release assets
+        run: |
+          ./scripts/verify-release-assets.sh \
+            build/release "${{ steps.version.outputs.version }}"
+
+      - name: Summary
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          {
+            if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then
+              echo "> [!WARNING]"
+              echo "> PR TEST ONLY — DO NOT PUBLISH TO CDN"
+              echo
+            fi
+            echo "### nanokvm_${VERSION}.tar.gz"
+            echo
+            echo '```text'
+            cat build/release/BUILD_INFO.txt
+            echo '```'
+            echo
+            echo '```json'
+            cat build/release/latest.json
+            echo '```'
+            echo
+            if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then
+              echo "Upload only the inner tarball through NanoKVM's manual offline update UI."
+            else
+              echo "Publishing to \`cdn.sipeed.com/nanokvm/\` is a separate manual step."
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.version.outputs.artifact_name }}
+          path: |
+            build/release/nanokvm_${{ steps.version.outputs.version }}.tar.gz
+            build/release/latest.json
+            build/release/sha256.txt
+            build/release/BUILD_INFO.txt
+          if-no-files-found: error
+          retention-days: ${{ github.event_name == 'pull_request' && 7 || 90 }}

.github/workflows/release.yml

@@ -0,0 +1,244 @@
+name: NanoKVM Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing numeric tag to release, e.g. 2.5.0
+        required: true
+        type: string
+      release_action:
+        description: Publish a release or promote a tested prerelease
+        required: true
+        type: choice
+        options:
+          - publish-prerelease
+          - publish-stable
+          - promote-stable
+
+# Latest is repository-global, so all Release changes must be serialized.
+concurrency:
+  group: nanokvm-github-release
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    name: Resolve release tag
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      source_sha: ${{ steps.tag.outputs.source_sha }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Verify tag
+        id: tag
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          SOURCE_SHA=$(./scripts/verify-release-tag.sh "$TAG")
+          echo "source_sha=$SOURCE_SHA" >> "$GITHUB_OUTPUT"
+
+  package:
+    name: Build tag package
+    needs: validate
+    if: inputs.release_action != 'promote-stable'
+    permissions:
+      contents: read
+      packages: read
+    uses: ./.github/workflows/package.yml
+    with:
+      ref: ${{ needs.validate.outputs.source_sha }}
+      version: ${{ inputs.tag }}
+
+  publish:
+    name: Publish GitHub release
+    needs:
+      - validate
+      - package
+    if: inputs.release_action != 'promote-stable'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout release tooling
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Download package artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ needs.package.outputs.artifact_name }}
+          path: build/release
+
+      - name: Publish release
+        env:
+          GH_REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_ACTION: ${{ inputs.release_action }}
+          SOURCE_SHA: ${{ needs.validate.outputs.source_sha }}
+          TAG: ${{ inputs.tag }}
+        run: |
+          ./scripts/verify-release-assets.sh build/release "$TAG"
+
+          case "$RELEASE_ACTION" in
+            publish-prerelease) IS_PRERELEASE=true ;;
+            publish-stable) IS_PRERELEASE=false ;;
+            *)
+              echo "::error::invalid publish action '$RELEASE_ACTION'"
+              exit 1
+              ;;
+          esac
+
+          ENDPOINT="repos/${GITHUB_REPOSITORY}/releases/tags/${TAG}"
+          set +e
+          HEADERS=$(gh api --include --silent "$ENDPOINT" 2>&1)
+          API_STATUS=$?
+          set -e
+          HTTP_STATUS=$(printf '%s\n' "$HEADERS" | awk '
+            $1 ~ /^HTTP\// { status = $2 }
+            END { print status }
+          ')
+          if [ "$API_STATUS" -eq 0 ] && [ "$HTTP_STATUS" = 200 ]; then
+            echo "::error::release or draft '$TAG' already exists"
+            echo "Publishing is one-shot. Inspect it at https://github.com/${GITHUB_REPOSITORY}/releases."
+            exit 1
+          fi
+          if [ "$API_STATUS" -eq 0 ] || [ "$HTTP_STATUS" != 404 ]; then
+            echo "::error::failed to query release '$TAG' (HTTP status: ${HTTP_STATUS:-unknown})"
+            printf '%s\n' "$HEADERS" >&2
+            exit 1
+          fi
+
+          TARBALL="build/release/nanokvm_${TAG}.tar.gz"
+          SHA256=$(sha256sum "$TARBALL" | cut -d' ' -f1)
+          SHA512=$(jq -er '.sha512' build/release/latest.json)
+          # Backticks below are intentional Markdown, not command substitution.
+          # shellcheck disable=SC2016
+          NOTES=$(printf '%s\n' \
+            "Application package for NanoKVM ${TAG}." \
+            '' \
+            '### Checksums' \
+            '' \
+            '`SHA-256` (hex):' \
+            '' \
+            "    ${SHA256}" \
+            '' \
+            '`SHA-512` (base64, as expected by the on-device updater):' \
+            '' \
+            "    ${SHA512}" \
+            '' \
+            'To offer this build over OTA, publish it through the separate CDN workflow.')
+
+          STATE_ARGS=(--prerelease="$IS_PRERELEASE")
+          if [ "$IS_PRERELEASE" = true ]; then
+            STATE_ARGS+=(--latest=false)
+          fi
+
+          ./scripts/verify-release-tag.sh "$TAG" "$SOURCE_SHA" >/dev/null
+          gh release create "$TAG" \
+            --verify-tag \
+            --title "nanokvm@${TAG}" \
+            --notes "$NOTES" \
+            "${STATE_ARGS[@]}" \
+            "$TARBALL" build/release/latest.json build/release/sha256.txt
+
+      - name: Summary
+        env:
+          RELEASE_ACTION: ${{ inputs.release_action }}
+          SOURCE_SHA: ${{ needs.validate.outputs.source_sha }}
+          TAG: ${{ inputs.tag }}
+        run: |
+          {
+            echo '### NanoKVM GitHub Release published'
+            echo
+            echo "- Tag: \`$TAG\`"
+            echo "- Commit: \`$SOURCE_SHA\`"
+            echo "- Action: \`$RELEASE_ACTION\`"
+            echo
+            echo 'No CDN object was uploaded.'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  promote:
+    name: Promote verified prerelease
+    needs: validate
+    if: inputs.release_action == 'promote-stable'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout release tooling
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Verify and promote release
+        env:
+          GH_REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SOURCE_SHA: ${{ needs.validate.outputs.source_sha }}
+          TAG: ${{ inputs.tag }}
+        run: |
+          RELEASE_JSON=$(gh api "repos/${GITHUB_REPOSITORY}/releases/tags/${TAG}")
+          if [ "$(jq -r '.draft' <<< "$RELEASE_JSON")" != false ]; then
+            echo "::error::release '$TAG' is a draft"
+            exit 1
+          fi
+          if [ "$(jq -r '.prerelease' <<< "$RELEASE_JSON")" != true ]; then
+            echo "::error::release '$TAG' is not a prerelease"
+            exit 1
+          fi
+
+          CURRENT_ASSETS=$(jq -r '.assets[].name' <<< "$RELEASE_JSON" | LC_ALL=C sort)
+          EXPECTED_ASSETS=$(printf '%s\n' \
+            latest.json "nanokvm_${TAG}.tar.gz" sha256.txt | LC_ALL=C sort)
+          if [ "$CURRENT_ASSETS" != "$EXPECTED_ASSETS" ]; then
+            echo "::error::release '$TAG' does not have the exact expected asset set"
+            exit 1
+          fi
+
+          mkdir -p build/release
+          gh release download "$TAG" --dir build/release \
+            --pattern "nanokvm_${TAG}.tar.gz" \
+            --pattern latest.json \
+            --pattern sha256.txt
+          ./scripts/verify-release-assets.sh build/release "$TAG"
+
+          ./scripts/verify-release-tag.sh "$TAG" "$SOURCE_SHA" >/dev/null
+          gh release edit "$TAG" --prerelease=false --latest
+          ./scripts/verify-release-tag.sh "$TAG" "$SOURCE_SHA" >/dev/null
+
+          if [ "$(gh api "repos/${GITHUB_REPOSITORY}/releases/tags/${TAG}" --jq '.prerelease')" != false ]; then
+            echo "::error::release '$TAG' was not promoted"
+            exit 1
+          fi
+          if [ "$(gh api "repos/${GITHUB_REPOSITORY}/releases/latest" --jq '.tag_name')" != "$TAG" ]; then
+            echo "::error::release '$TAG' was not marked latest"
+            exit 1
+          fi
+
+      - name: Summary
+        env:
+          SOURCE_SHA: ${{ needs.validate.outputs.source_sha }}
+          TAG: ${{ inputs.tag }}
+        run: |
+          {
+            echo '### NanoKVM prerelease promoted'
+            echo
+            echo "- Tag: \`$TAG\`"
+            echo "- Commit: \`$SOURCE_SHA\`"
+            echo '- Assets: unchanged and checksum-verified'
+            echo
+            echo 'No package was rebuilt and no CDN object was uploaded.'
+          } >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -5,6 +5,10 @@ web/node_modules
 web/dist
 web/web
 
+# pnpm keeps its content-addressable store next to the project when the
+# home directory is on a different filesystem (e.g. inside the dev container)
+.pnpm-store/
+
 .DS_Store
 *.local
 *.suo
@@ -29,3 +33,6 @@ support/sg2002/kvm_vision_test/CMakeLists.txt
 support/sg2002/additional/original
 kvmapp/server/dl_lib
 kvmapp/kvm_system/kvm_system
+
+# Release packages assembled by scripts/package.sh
+/build/

CHANGELOG.md

@@ -1,4 +1,228 @@
-## 2.3.2 (2025-01-08)
+## 2.5.1 (2026-09-09)
+
+### Features
+
+* Added device-level multi-user support with `admin` and `user` roles and a user management page under Settings, separating administrative areas (terminal, scripts, storage, network, updates, MCP, PicoClaw and Tailscale) from the video, keyboard, mouse, paste, wake-on-LAN and power controls every account keeps
+* Moved sessions to HttpOnly cookies with a per-user token version, so changing a password or disabling an account immediately ends that user's open web and WebSocket sessions
+* Added support for a custom update server, so the application can be updated from your own mirror, with credentials in the URL, manifest validation and a settings page for configuring it
+* Added SHA-256 verification of offline update packages before they are installed
+* Added configurable mouse input regions for absolute mode, with automatic black-border detection, manual selection of the controllable area on screen, and original-resolution presets, so the pointer stays aligned when the target machine outputs a letterboxed or non-16:9 signal
+* Added touch gestures to relative mouse mode, including tap, drag, long press, double-tap drag and two-finger scroll, so relative mode is now usable from a phone or tablet
+* Added a `signal` field to `/api/vm/hdmi` reporting whether an HDMI source is actually present, not just whether capture is enabled
+* Added a default root shell profile showing the user, host and working directory in the prompt over SSH and the Web terminal
+
+### Bug Fixes
+
+* Fixed mouse coordinates being offset in Direct H.264 mode when the target machine pads the picture with black bars
+* Fixed touch input in absolute mode, and stopped taps on the black letterbox area from being sent to the target machine
+* Fixed the video area not fitting the window, by scaling H.264 and MJPEG playback to contain and letting the page handle touch instead of the browser
+* Fixed WebRTC H.264 failures leaving a silent black screen; signaling, negotiation, ICE and playback failures now report what went wrong and offer a retry
+* Fixed a slow WebRTC viewer stalling the shared H.264 source for everyone else, by dropping its buffered frames until the next key frame
+* Fixed application updates running from a temporary directory that could be too small or shared with another update; online and offline updates are now staged in isolated persistent workspaces with archive, manifest and free-space checks, and the last rollback backup is kept when space runs short
+* Fixed the update lock being released before the server finished restarting, which allowed a second update to start and be killed mid-install
+* Fixed Web terminal sessions not loading the root profile, by starting them as login shells in `/root`
+
+### Performance
+
+* Routed Direct and WebRTC viewers through a single shared H.264 capture source instead of each reading the encoder separately
+
+### Localization
+
+* Synchronized translations of other languages according to English
+
+### Chores
+
+* Upgraded the web build tooling to Vite 8 and switched to Vite's native tsconfig path resolution
+* Added a dev container for full-stack development
+* Prefixed GitHub Release titles with `nanokvm`
+* Added release asset verification with per-device package size limits to the packaging workflow
+
+## 2.5.0 (2026-08-04)
+
+### Features
+
+* Added an MCP service that lets trusted MCP clients capture screenshots and control the keyboard and mouse with an API key, including a settings page for enabling it and regenerating the key
+* Added coordinated device control so MCP, PicoClaw and manual input hand ownership over to each other instead of writing HID input at the same time
+* Added remote keyboard lock indicators that show the target machine's Num Lock, Caps Lock and Scroll Lock state
+* Added an optional SHA-256 checksum and cancellation to remote image downloads
+
+### Bug Fixes
+
+* Fixed the USB network gadget getting a random host-side MAC on every bind, which made the attached PC register a new network adapter after each reboot; both the device and host MAC are now derived from the chip UID (thanks to [@BeaconCat](https://github.com/BeaconCat))
+* Fixed OLED sleep durations above 255 seconds being truncated, so the 5 min, 10 min, 30 min and 1 hour options now behave as selected
+* Fixed the mounted image API returning an error in HID-Only mode
+* Fixed image downloads and application updates interfering with each other when running at the same time
+* Fixed Direct H.264 playback falling behind when the decoder queue backed up, by resynchronizing at the next key frame and preferring hardware decoding
+* Added a warning when Direct and WebRTC H.264 stream modes are used at the same time
+* Made the video input state shared between processes and read it without shell pipelines, so HDMI status stays consistent between `NanoKVM-Server` and `kvm_system`
+
+### Performance
+
+* Reduced latency in 60 Hz mode with decode-driven flow control, GOP-aware bounded queues, and dedicated writer goroutines with write deadlines so a slow client no longer stalls the others
+* Integrated zero-copy H.264 capture into the video pipeline instead of relying on a preload hook
+* Stopped HDMI capture when no user is logged in or all viewers are idle, reducing power consumption
+
+### UI Improvements
+
+* Tidied the image download dialog layout and truncated long file names in the upload box
+
+### Localization
+
+* Synchronized translations of other languages according to English
+
+### Chores
+
+* Split release automation into separate package, tag and release workflows, and produced identifiable build artifacts with checksums for pull requests
+* Allowed overriding the builder image, installed `patchelf` in the build environment, and fixed the exit codes of `support/sg2002/build`
+* Fixed slow container builds caused by uid/gid mismatch and reused existing container users and groups
+
+## 2.4.3 (2026-06-09)
+
+### Features
+
+* Added LT6911D support
+
+### Bug Fixes
+
+* Improved USB network adapter compatibility on Windows
+
+## 2.4.2 (2026-05-20)
+
+### Features
+
+* Added HDMI capture status detection with localized warning and error overlays on the desktop screen
+
+### Bug Fixes
+
+* Fixed left-button touch cancellation and context menu cleanup for mouse input
+* Improved the WebRTC loading indicator
+* Added Wi-Fi password field validation
+* Hardened Wake-on-LAN MAC handling by normalizing stored addresses, avoiding shell execution, handling missing history gracefully, and improving named MAC display
+* Stabilized PicoClaw session switching by waiting for gateway release, refreshing runtime status before reconnecting, rendering structured thought messages, and preventing history row overflow
+
+### Performance
+
+* Improved H.264 streaming client handling by reducing frame queue latency, using client snapshots for fanout, applying backend ICE server configuration, and cleaning up disconnected WebRTC clients more aggressively
+
+### UI Improvements
+
+* Refreshed desktop menu ordering and community links, including replacing the Discussion link with Discord
+
+### Chores
+
+* Removed the legacy H.264 stream package
+* Updated PostCSS, refreshed the MSW worker, and added pnpm workspace build approvals
+
+## 2.4.1 (2026-05-08)
+
+### Features
+
+* Added DNS management to Network settings, including DHCP/manual modes, effective DNS display, network details, IPv4/IPv6 server validation, and persistent udhcpc hook support
+* Added a configurable server `host` option for binding NanoKVM to a specific listen address (thanks to [@allmazz](https://github.com/allmazz))
+* Added French keyboard layout support and language options (thanks to [@ilyesAj](https://github.com/ilyesAj))
+
+### Bug Fixes
+
+* Hardened HID recovery and cleanup by adding non-blocking HID writes, bounded reopen retries, stale event draining, and release reports after write failures
+* Fixed the `kvm_vision` project name and build output message in the SG2002 build script (thanks to [@Voranto](https://github.com/Voranto))
+
+### UI Improvements
+
+* Moved TLS and Wi-Fi settings into the Network settings section
+* Optimized the Settings scrollbar style
+
+### Localization
+
+* Updated Korean translations (thanks to [@kmw0410](https://github.com/kmw0410))
+* Synchronized translations of other languages according to English
+
+### Security
+
+* Upgraded vulnerable web dependencies
+
+## 2.4.0 (2026-04-10)
+
+### Features
+
+* **Introduced [PicoClaw](https://github.com/sipeed/picoclaw) support** — an AI-powered remote desktop assistant for NanoKVM. PicoClaw seamlessly integrates a lightweight AI agent with NanoKVM's underlying hardware capabilities. Key highlights include:
+  * **Zero-Agent Architecture:** Operates entirely through HDMI video capture (vision) and USB HID emulation (keyboard/mouse). No SSH access, network connection to the host, or OS-level software installation is required.
+  * **Natural Language Control:** Features a built-in chat interface allowing users to issue complex instructions in plain text.
+  * **Autonomous GUI Operation:** The AI agent can autonomously observe the remote host's screen, understand UI elements, reason about the task, and execute operations mimicking human behavior.
+  * **Installation Note:** PicoClaw is not built into the NanoKVM device or firmware. Install it separately when needed.
+
+### Bug Fixes
+
+* Added a default subnet mask for static IP configurations
+* Fixed an issue where the IP address would occasionally not display
+
+## 2.3.6 (2026-03-12)
+
+### Features
+
+* Implemented AP password authentication for the WiFi configuration page
+* Added Korean and Japanese virtual keyboard layouts (thanks to [@klim4-bot](https://github.com/klim4-bot))
+* Enabled support for 640x480 resolution (thanks to [@Voranto](https://github.com/Voranto))
+* Added encryption parameters for OLED distribution network
+* Added custom logo function and logo generation tools
+* Added update mechanism for tailscale startup script
+
+### Localization
+
+* Updated Japanese translation (thanks to [@tkmsst](https://github.com/tkmsst))
+
+## 2.3.5 (2026-02-28)
+
+### Features
+
+* Implemented login brute-force protection with lockout mechanism
+
+### Bug Fixes
+
+* Improved Tailscale error handling in UI components and refined backend state mapping
+
+### Chores
+
+* Updated server and web dependencies
+
+## 2.3.4 (2026-01-26)
+
+### Features
+
+* Introduced `Leader Key` functionality to bypass local browser shortcut interception
+
+### Bug Fixes
+
+* Fixed an issue where the Right Shift key was not being recognized on Windows system
+* Fixed a bug where the menu bar would fail to close correctly
+
+### Localization
+
+* Updated Traditional Chinese translations (thanks to [@j796160836](https://github.com/j796160836))
+* Updated Korean translations (thanks to [@kmw0410](https://github.com/kmw0410))
+
+## 2.3.3 (2026-01-16)
+
+### Features
+
+* Added support for setting the display mode of the menu bar
+
+### Bug Fixes
+
+* Fixed a keyboard issue where IME composition events were not handled correctly
+* Resolved an issue where the `AltGr` key was not recognized on the Windows system
+* Fixed a bug where `Command` key combinations were not fully released on the macOS system
+* Fixed input issues with the `IntlBackslash` key on the German virtual keyboard
+
+### Localization
+
+* Updated Korean translations (thanks to [@kmw0410](https://github.com/kmw0410))
+
+### Chores
+
+* Bump react-router-dom from 6.27.0 to 6.30.3
+* Updated eslint
+
+## 2.3.2 (2026-01-08)
 
 ### Features
 

Makefile

@@ -1,19 +1,30 @@
 # Makefile for NanoKVM Project
 
 # Configuration
-IMAGE_NAME := nanokvm-builder
 UID := $(shell id -u)
 GID := $(shell id -g)
+# ?= so a prebuilt image can be used instead, e.g. a GHCR-cached builder in CI.
+IMAGE_NAME ?= nanokvm-builder-local-$(UID)-$(GID)
 PWD := $(shell pwd)
+VERSION ?=
 
-# Docker run common parameters
+# Docker run common parameters. Allocating a TTY breaks in environments without
+# one, so it can be overridden with DOCKER_TTY=
+DOCKER_TTY ?= -it
 DOCKER_RUN_BASE := docker run -e UID=$(UID) -e GID=$(GID) -v $(PWD):/home/build/NanoKVM --rm
 
+# Build the image with the host user's identity so entrypoint does not need
+# to recursively rewrite the MaixCDK home directory at container startup.
+DOCKER_BUILD_ARGS := --build-arg DOCKER_UID=$(UID) --build-arg DOCKER_GID=$(GID)
+
 # Build commands
 GO_BUILD_CMD := cd /home/build/NanoKVM/server && go mod tidy && CGO_ENABLED=1 GOOS=linux GOARCH=riscv64 CC=riscv64-unknown-linux-musl-gcc CGO_CFLAGS="-mcpu=c906fdv -march=rv64imafdcv0p7xthead -mcmodel=medany -mabi=lp64d" go build
 SUPPORT_BUILD_CMD := . ./home/build/MaixCDK/bin/activate && cd /home/build/NanoKVM/support/sg2002 && ./build kvm_system && ./build kvm_system add_to_kvmapp
+VISION_BUILD_CMD := . ./home/build/MaixCDK/bin/activate && cd /home/build/NanoKVM/support/sg2002 && ./build kvm_vision && ./build kvm_vision add_to_kvmapp
+RELEASE_BUILD_CMD := /home/build/NanoKVM/scripts/build-in-container.sh
 
-.PHONY: help check-root builder-image rebuild-image check-image shell app support all clean
+.PHONY: help check-root builder-image rebuild-image check-image shell app support vision \
+        web release-build package release all clean
 
 # Default target
 all: app support
@@ -29,8 +40,13 @@ help:
 	@echo "  rebuild-image - Force rebuild Docker image"
 	@echo "  shell         - Enter interactive builder environment"
 	@echo "  app           - Build Go application server"
-	@echo "  support       - Build hardware support libraries"
+	@echo "  support       - Build kvm_system daemon"
+	@echo "  vision        - Build video libraries (libkvm.so)"
+	@echo "  web           - Build the frontend into web/dist"
 	@echo "  all           - Build both app and support (default)"
+	@echo "  release-build - Build every riscv64 release artifact in one pass"
+	@echo "  package       - Assemble nanokvm_<VERSION>.tar.gz + latest.json"
+	@echo "  release       - release-build + web + package (needs VERSION=x.y.z)"
 	@echo "  clean         - Clean build artifacts"
 	@echo ""
 	@echo "Prerequisites:"
@@ -58,7 +74,7 @@ check-image: check-root
 builder-image: check-root
 	@if ! docker image inspect $(IMAGE_NAME) >/dev/null 2>&1; then \
 		echo "Building Docker image..."; \
-		docker build -t $(IMAGE_NAME) -f docker/Dockerfile ./; \
+		docker build $(DOCKER_BUILD_ARGS) -t $(IMAGE_NAME) -f docker/Dockerfile ./; \
 	else \
 		echo "Docker image $(IMAGE_NAME) already exists."; \
 	fi
@@ -66,7 +82,7 @@ builder-image: check-root
 # Force rebuild Docker image
 rebuild-image: check-root
 	@echo "Force rebuilding Docker image..."
-	@docker build --no-cache -t $(IMAGE_NAME) -f docker/Dockerfile ./
+	@docker build --no-cache $(DOCKER_BUILD_ARGS) -t $(IMAGE_NAME) -f docker/Dockerfile ./
 
 # Enter interactive shell (equivalent to build.sh with no arguments)
 shell: check-root builder-image
@@ -76,12 +92,43 @@ shell: check-root builder-image
 # Build Go application
 app: check-root builder-image
 	@echo "Building app..."
-	@$(DOCKER_RUN_BASE) -it $(IMAGE_NAME) /bin/bash -c '$(GO_BUILD_CMD)'
+	@$(DOCKER_RUN_BASE) $(DOCKER_TTY) $(IMAGE_NAME) /bin/bash -c '$(GO_BUILD_CMD)'
 
 # Build hardware support libraries
 support: check-root builder-image
 	@echo "Building support..."
-	@$(DOCKER_RUN_BASE) -it $(IMAGE_NAME) /bin/bash -c '$(SUPPORT_BUILD_CMD)'
+	@$(DOCKER_RUN_BASE) $(DOCKER_TTY) $(IMAGE_NAME) /bin/bash -c '$(SUPPORT_BUILD_CMD)'
+
+# Build video libraries (libkvm.so) into kvmapp/server/dl_lib
+vision: check-root builder-image
+	@echo "Building vision..."
+	@$(DOCKER_RUN_BASE) $(DOCKER_TTY) $(IMAGE_NAME) /bin/bash -c '$(VISION_BUILD_CMD)'
+
+# Build every riscv64 release artifact in one container pass
+release-build: check-root builder-image
+	@echo "Building release artifacts..."
+	@$(DOCKER_RUN_BASE) $(DOCKER_TTY) $(IMAGE_NAME) /bin/bash -c '$(RELEASE_BUILD_CMD)'
+
+# Build the frontend (runs on the host; the builder image has no Node)
+web:
+	@echo "Building web..."
+	@cd web && pnpm install --frozen-lockfile && pnpm build
+
+# Assemble the release package and its manifest
+package:
+	@if [ -z "$(VERSION)" ]; then \
+		echo "VERSION is required, e.g. make package VERSION=2.4.4"; \
+		exit 1; \
+	fi
+	@scripts/package.sh "$(VERSION)"
+
+# Full local release: riscv64 artifacts + frontend + package.
+# Invoked as sub-makes rather than prerequisites: packaging asserts on what the
+# earlier steps produce, so the order matters even under make -j.
+release:
+	@$(MAKE) release-build
+	@$(MAKE) web
+	@$(MAKE) package VERSION="$(VERSION)"
 
 # Clean build artifacts
 clean:
@@ -94,4 +141,12 @@ clean:
 		rm -rf support/sg2002/build; \
 		echo "Removed support/sg2002/build"; \
 	fi
-	@echo "Clean completed."
+	@if [ -d build/release ]; then \
+		rm -rf build/release; \
+		echo "Removed build/release"; \
+	fi
+	@if [ -d web/dist ]; then \
+		rm -rf web/dist; \
+		echo "Removed web/dist"; \
+	fi
+	@echo "Clean completed."

README.md

@@ -13,26 +13,24 @@
   <br>
 </div>
 
-> For the recent discussion regarding the **built-in microphone**, please check [Issue #693](https://github.com/sipeed/NanoKVM/issues/693).
-
 ## 🌟 What is NanoKVM?
 
-NanoKVM is a series of compact, open-source IP-KVM devices based on the LicheeRV Nano (RISC-V). NanoKVM allows you to remotely access and control computers as if you were sitting right in front of them – perfect for managing servers, embedded systems, or any headless machine.
+NanoKVM is a series of compact, open-source IP-KVM devices based on the LicheeRV Nano (RISC-V). It lets you remotely access and control computers as if you were sitting in front of them, making it useful for servers, embedded systems, and other headless machines.
 
 ## 📦 Product Family
 
-We offer several NanoKVM versions to suit your needs:
+Choose the NanoKVM model that best fits your deployment:
 
-* **NanoKVM-Cube Lite:** A barebones kit for DIY enthusiasts and enterprise users requiring bulk deployment.
-* **NanoKVM-Cube Full:** A complete package featuring a sleek case, accessories, and a pre-flashed system SD card. Ready to use out-of-the-box; ideal for individual users.
-* **NanoKVM-PCIe:** A unique form factor with a PCIe bracket for internal chassis mounting. It draws power directly from the PCIe slot and supports optional WiFi and PoE functions.
-* **[NanoKVM-Pro:](https://github.com/sipeed/NanoKVM-Pro)** Based on popular demand, the **Pro version** delivers significant performance upgrades:
-  * **Resolution:** Upgraded from 1080P to stunning **4K@30fps / 2K@60fps**.
-  * **Network:** Blazing fast **1Gbps Ethernet + PoE + WiFi 6** ((upgraded from 100Mbps).
-  * **Latency:** Encoder accelerated latency reduced from 100-150ms to **50-100ms**.
+- **NanoKVM-Cube Lite:** A barebones kit for DIY users and bulk deployments.
+- **NanoKVM-Cube Full:** A ready-to-use kit with a case, accessories, and a pre-flashed system SD card.
+- **NanoKVM-PCIe:** A PCIe-bracket form factor for internal chassis mounting. It draws power from the PCIe slot and supports optional Wi-Fi and PoE.
+- **[NanoKVM-Pro](https://github.com/sipeed/NanoKVM-Pro):** A higher-performance version with major upgrades:
+  - **Resolution:** Up to **4K@30fps / 2K@60fps**.
+  - **Network:** **1Gbps Ethernet + PoE + Wi-Fi 6**, upgraded from 100Mbps Ethernet.
+  - **Latency:** Hardware-accelerated encoding reduces latency from 100-150ms to **50-100ms**.
 
 <div align="center">
-  <img src="https://cdn.sipeed.com/public/nanokvm-products.jpg" alt="NanoKVM Product Family" width="80%" style="margin: 20px 0;">
+  <img src="https://cdn.sipeed.com/public/nanokvm-products-v2.jpg" alt="NanoKVM Product Family" width="100%" style="margin: 20px 0;">
 </div>
 
 > If you are looking for a USB-based KVM solution, check out [NanoKVM-USB](https://github.com/sipeed/NanoKVM-USB).
@@ -40,36 +38,36 @@ We offer several NanoKVM versions to suit your needs:
 ## 🛠️ Technical Specifications
 
 | Feature            | NanoKVM-Pro                           | NanoKVM (Cube/PCIe)               | GxxKVM                             | JxxKVM                              |
-|------------------- |-------------------------------------- |---------------------------------- |----------------------------------- |------------------------------------ |
+| ------------------ | ------------------------------------- | --------------------------------- | ---------------------------------- | ----------------------------------- |
 | Core               | AX630C 2xA53 1.2G                     | SG2002 1xC906 1.0G                | RV1126 4xA7 1.5G                   | RV1106 1xA7 1.2G                    |
-| Memory & Storage   | 1G LPDDR4X + 32G eMMC                 | 256M DDR3 + 32G microSD           | 1G DDR3 + 8G eMMc                  | 256M DDR3 + 16G eMMC                |
+| Memory & Storage   | 1G LPDDR4X + 32G eMMC                 | 256M DDR3 + 32G microSD           | 1G DDR3 + 8G eMMC                  | 256M DDR3 + 16G eMMC                |
 | System             | NanoKVM / PiKVM                       | NanoKVM                           | GxxKVM                             | JxxKVM                              |
 | Resolution         | 4K@30fps / 2K@60fps                   | 1080P@60fps                       | 4K@30fps / 2K@60fps                | 1080P@60fps                         |
-| HDMI Loopout       | 4K loopout                            | x                                 | x                                  | x                                   |
-| Video Encoding     | MJPEG / H.264 / H.265                 | MJPEG / H264                      | MJPEG / H264                       | MJPEG / H264                        |
-| Audio Transmit     | ✓                                     | x                                 | ✓                                  | x                                   |
+| HDMI Loopout       | 4K loopout                            | —                                 | —                                  | —                                   |
+| Video Encoding     | MJPEG / H.264 / H.265                 | MJPEG / H.264                     | MJPEG / H.264                      | MJPEG / H.264                       |
+| Audio Transmit     | ✓                                     | —                                 | ✓                                  | —                                   |
 | UEFI / BIOS        | ✓                                     | ✓                                 | ✓                                  | ✓                                   |
 | Emulated USB Keyboard & Mouse | ✓                          | ✓                                 | ✓                                  | ✓                                   |
 | Emulated USB ISO   | ✓                                     | ✓                                 | ✓                                  | ✓                                   |
-| IPMI               | ✓                                     | ✓                                 | ✓                                  | x                                   |
+| IPMI               | ✓                                     | ✓                                 | ✓                                  | —                                   |
 | Wake-on-LAN        | ✓                                     | ✓                                 | ✓                                  | ✓                                   |
 | Web Terminal       | ✓                                     | ✓                                 | ✓                                  | ✓                                   |
-| Serial Terminal    | 2 channels                            | 2 channels                        | x                                  | 1 channel                           |
-| Custom Scripts     | ✓                                     | ✓                                 | x                                  | x                                   |
+| Serial Terminal    | 2 channels                            | 2 channels                        | —                                  | 1 channel                           |
+| Custom Scripts     | ✓                                     | ✓                                 | —                                  | —                                   |
 | Storage            | 32G eMMC 300MB/s                      | 32G MicroSD 12MB/s                | 8G eMMC 120MB/s                    | 8G eMMC 60MB/s                      |
 | Ethernet           | 1000M                                 | 100M                              | 1000M                              | 100M                                |
-| PoE                | Optional                              | Optional                          | x                                  | x                                   |
-| WiFi               | Optional WiFi6                        | Optional WiFi6                    | x                                  | x                                   |
+| PoE                | Optional                              | Optional                          | —                                  | —                                   |
+| Wi-Fi              | Optional Wi-Fi 6                      | Optional Wi-Fi 6                  | —                                  | —                                   |
 | ATX Power Control  | ✓                                     | ✓                                 | Extra $15                          | Extra $10                           |
-| Display            | 1.47" 320x172 LCD / 0.96" 128x64 OLED | 0.96" 128x64 OLED                 | -                                  | 1.68" 280x240                       |
-| More Features      | Sync LED Strip / Smart Assistant      | -                                 | -                                  | -                                   |
+| Display            | 1.47" 320x172 LCD / 0.96" 128x64 OLED | 0.96" 128x64 OLED                 | —                                  | 1.68" 280x240                       |
+| More Features      | Sync LED Strip / Smart Assistant      | —                                 | —                                  | —                                   |
 | Power Consumption  | 0.6A@5V                               | 0.2A@5V                           | 0.4A@5V                            | 0.2A@5V                             |
 | Power Input        | USB-C or PoE                          | USB-C                             | USB-C                              | USB-C                               |
 | Dimensions         | 65x65x26mm                            | 40x36x36mm                        | 80x60x17.5mm                       | 60x43x(24~31)mm                     |
 
 ## 📂 Project Structure
 
-``` shell
+```text
 ├── kvmapp          # APP update package
 │   ├── jpg_stream  # Legacy support for direct updates from older versions
 │   ├── kvm_new_app # Triggers components for kvm_system updates
@@ -82,20 +80,49 @@ We offer several NanoKVM versions to suit your needs:
 ├── ...
 ```
 
+## 💻 Development
+
+Start with the guide that matches the part of NanoKVM you want to work on:
+
+- **System support modules:** Build and update the low-level hardware support components in [support/sg2002/README.md](support/sg2002/README.md).
+- **Backend service:** Set up, build, and understand the Go service in [server/README.md](server/README.md).
+- **Frontend UI:** Develop, lint, and build the React interface in [web/README.md](web/README.md).
+- **Release packaging:** Assemble the `nanokvm_<version>.tar.gz` update package in [scripts/README.md](scripts/README.md).
+
+> Backend compilation and runtime validation require the target toolchain or a NanoKVM device. See the module-specific guides above for the latest development workflow.
+
+### Dev container (optional)
+
+The repository ships a [Dev Container](https://containers.dev) setup (`.devcontainer/`) that layers the frontend toolchain (Node 22, pnpm 11) on top of the release builder image (RISC-V cross toolchain, Go, MaixCDK), so one container covers Go, C support-layer and web development. It is a convenience for IDE users; the `make` targets in the repository root remain the canonical CLI workflow.
+
+- Requirements: Docker plus an editor or CLI with dev container support (e.g. the VS Code "Dev Containers" extension, or `devcontainer up`).
+- On creation the container prepares itself automatically: `support/sg2002/build update_lib` (resyncs MaixCDK components with the checkout) and `pnpm install` for the frontend.
+- Backend: run `server/build.sh` for a release-equivalent binary (BoringCrypto + `dl_lib` RPATH). `make app` builds a plain development binary without those, so prefer `server/build.sh` whenever the result should match a release.
+- Support layer: `cd support/sg2002 && ./build kvm_system` (the MaixCDK virtualenv is part of the container environment).
+- Frontend: `cd web && pnpm dev` (VS Code forwards port 3001 automatically; other clients may need to map it themselves); see [web/README.md](web/README.md) for pointing it at a device.
+- The base image `ghcr.io/sipeed/nanokvm-builder:latest` is x86-64 only; on Apple Silicon it runs under emulation (works, but C builds are slow). You can also build the image locally first (`make builder-image`) and point the `BASE_IMAGE` build arg at it (e.g. via `build.args` in `devcontainer.json`). On Linux hosts the first container creation also takes a while: the container user is remapped to your uid, which re-chowns its home directory once.
+- Hardware-dependent verification still requires a real NanoKVM device; the container covers compiling, linting and mock-mode web development only.
+
 ## 🔩 Hardware Platform (NanoKVM Cube/PCIe)
 
-NanoKVM is based on Sipeed [LicheeRV Nano](https://wiki.sipeed.com/hardware/zh/lichee/RV_Nano/1_intro.html). You can find specifications, schematics, and dimensional drawings in the [download station](http://cn.dl.sipeed.com/shareURL/LICHEE/LicheeRV_Nano).
+NanoKVM is based on Sipeed [LicheeRV Nano](https://wiki.sipeed.com/hardware/zh/lichee/RV_Nano/1_intro.html). You can find specifications, schematics, and dimensional drawings in the [download station](https://dl.sipeed.com/shareURL/LICHEE/LicheeRV_Nano).
 
-The NanoKVM Lite is constructed by the LicheeRV Nano and HDMItoCSI board, and the NanoKVM FULL adds the NanoKVM-A/B board and shell to the NanoKVM Lite. The HDMItoCSI board is used to convert the HDMI signal; NanoKVM-A, including OLED, ATX control output (USB Type-C interface), auxiliary power supply and ATX power on/off and reset buttons; The NanoKVM-B is connected to the plate at one end and the computer at the other end is connected to the computer ATX-Pin, which is used to remotely control the power of the computer.
+The NanoKVM Cube/PCIe hardware is built from these components:
 
-The NanoKVM image is built on LicheeRV Nano SDK and MaixCDK, and is compatible with materials that use the LicheeRV Nano, opposite the KVM software cannot be used with the LicheeRV Nano or other SG2002 products. If you would like to build an HDMI input application on LicheeRV Nano or MaixCam, please contact us for technical support.
+- **NanoKVM Lite:** LicheeRV Nano plus the HDMI-to-CSI board.
+- **NanoKVM Full:** NanoKVM Lite plus the NanoKVM-A/B boards and enclosure.
+- **HDMI-to-CSI board:** Converts the HDMI input signal.
+- **NanoKVM-A board:** Provides OLED, ATX control output through USB-C, auxiliary power, and physical ATX power/reset buttons.
+- **NanoKVM-B board:** Connects NanoKVM-A to the host computer's ATX pins for remote power control.
 
-Note: Out of the 256MB memory in SG2002, 158MB is currently allocated for the multimedia subsystem, which NanoKVM will use for video image acquisition and processing.
+The NanoKVM image is built with the LicheeRV Nano SDK and MaixCDK. It is intended for NanoKVM hardware and is not a general-purpose KVM software package for other LicheeRV Nano or SG2002 products. If you want to build an HDMI input application on LicheeRV Nano or MaixCam, please contact us for technical support.
 
-* [NanoKVM-A Schematic](https://cn.dl.sipeed.com/fileList/KVM/nanoKVM/HDK/02_Schematic/SCH_RV_Nano_KVM_A_30111.pdf)
-* [NanoKVM-B Schematic](https://cn.dl.sipeed.com/fileList/KVM/nanoKVM/HDK/02_Schematic/SCH_RV_Nano_KVM_B_30131.pdf)
-* [NanoKVM-PCIe Schematic](https://cn.dl.sipeed.com/fileList/KVM/KVM_PCIE/HDK/01_Schematic/SCH_nanoKVM_PCIE_3105D_2025-12-19.pdf)
-* [NanoKVM img](https://github.com/sipeed/NanoKVM/releases/tag/NanoKVM)
+> Note: Of the 256MB memory on SG2002, 158MB is currently allocated to the multimedia subsystem for video capture and processing.
+
+- [NanoKVM-A Schematic](https://cn.dl.sipeed.com/fileList/KVM/nanoKVM/HDK/02_Schematic/SCH_RV_Nano_KVM_A_30111.pdf)
+- [NanoKVM-B Schematic](https://cn.dl.sipeed.com/fileList/KVM/nanoKVM/HDK/02_Schematic/SCH_RV_Nano_KVM_B_30131.pdf)
+- [NanoKVM-PCIe Schematic](https://cn.dl.sipeed.com/fileList/KVM/KVM_PCIE/HDK/01_Schematic/SCH_nanoKVM_PCIE_3105D_2025-12-19.pdf)
+- [NanoKVM image](https://github.com/sipeed/NanoKVM/releases/tag/NanoKVM)
 
 <div align="center">
   <img src="https://wiki.sipeed.com/hardware/zh/kvm/assets/NanoKVM/1_intro/NanoKVM_2.jpg" alt="NanoKVM PCB Pinout" width="80%" style="margin: 20px 0;">
@@ -103,7 +130,7 @@ Note: Out of the 256MB memory in SG2002, 158MB is currently allocated for the mu
 
 ## 🤝 Contributing
 
-We welcome contributions! Here's how you can help:
+We welcome contributions. To get started:
 
 1. Fork the repository.
 2. Create a feature branch.
@@ -117,17 +144,17 @@ Please keep your pull requests small and focused to facilitate easier review and
 
 ## 🛒 Where to Buy
 
-* [Aliexpress(global except USA&Russia)](https://www.aliexpress.com/item/1005007369816019.html)
-* [淘宝](https://item.taobao.com/item.htm?id=811206560480)
-* [Preorder (any other country that not support in Aliexpress or Taobao)](https://sipeed.com/nanokvm)
+- [AliExpress (global, except USA and Russia)](https://www.aliexpress.com/item/1005007369816019.html)
+- [Taobao](https://item.taobao.com/item.htm?id=811206560480)
+- [Preorder for other regions](https://sipeed.com/nanokvm)
 
 ## 💬 Community & Support
 
-* [Discord](https://discord.gg/V4sAZ9XWpN)
-* QQ group: 703230713
-* email: [support@sipeed.com](mailto:support@sipeed.com)
-* [FAQ](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/faq.html)
+- [Discord](https://discord.gg/V4sAZ9XWpN)
+- QQ group: 703230713
+- Email: [support@sipeed.com](mailto:support@sipeed.com)
+- [FAQ](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/faq.html)
 
 ## 📜 License
 
-This project is licensed under the GPL-3.0 License - see the LICENSE file for details.
+This project is licensed under the GPL-3.0 License. See [LICENSE](LICENSE) for details.

docker/Dockerfile

@@ -3,11 +3,24 @@ FROM ubuntu:24.04 AS base_apt
 # RUN echo 'Acquire::http::Proxy "http://cache.lan:3142";' > /etc/apt/apt.conf.d/00cacher
 RUN userdel -r ubuntu
 RUN apt update \
-    && apt install wget git cmake build-essential python3 python3-venv python3-pip autoconf automake libtool gosu -y
+    && apt install wget git cmake build-essential python3 python3-venv python3-pip autoconf automake libtool gosu patchelf -y
 
 ARG DOCKER_USER=build
-RUN useradd -m "$DOCKER_USER"
-USER $DOCKER_USER
+ARG DOCKER_UID=1000
+ARG DOCKER_GID=1000
+# Reuse existing accounts for numeric IDs that are already present in the
+# base image. All later ownership and user switches use numeric IDs, so a
+# dedicated build user/group is only needed when the ID does not exist.
+RUN set -eux; \
+    if ! getent group "$DOCKER_GID" >/dev/null; then \
+        groupadd --gid "$DOCKER_GID" "$DOCKER_USER"; \
+    fi; \
+    if ! getent passwd "$DOCKER_UID" >/dev/null; then \
+        useradd --uid "$DOCKER_UID" --gid "$DOCKER_GID" --no-create-home \
+            --home-dir "/home/$DOCKER_USER" --shell /bin/bash "$DOCKER_USER"; \
+    fi; \
+    install -d -o "$DOCKER_UID" -g "$DOCKER_GID" "/home/$DOCKER_USER"
+USER $DOCKER_UID:$DOCKER_GID
 
 FROM base_apt AS host_tools
 
@@ -39,6 +52,8 @@ RUN cd /tmp/go_cache \
 
 FROM base_apt AS sdk
 
+ENV HOME="/home/$DOCKER_USER"
+
 RUN cd ~ \
     && git clone https://github.com/Sipeed/MaixCDK \
     && cd MaixCDK \
@@ -46,7 +61,7 @@ RUN cd ~ \
     && . ./bin/activate \
     && pip install -U -r requirements.txt 
 
-COPY --chown=$DOCKER_USER . /home/$DOCKER_USER/NanoKVM
+COPY --chown=$DOCKER_UID:$DOCKER_GID . /home/$DOCKER_USER/NanoKVM
 
 RUN cd ~/MaixCDK \
     && . ./bin/activate \
@@ -57,7 +72,7 @@ FROM base_apt
 
 # Install golang
 COPY --from=golang /usr/local/go /usr/local/go
-COPY --chown=$DOCKER_USER --from=golang /root/go /home/$DOCKER_USER/go
+COPY --chown=$DOCKER_UID:$DOCKER_GID --from=golang /root/go /home/$DOCKER_USER/go
 ENV PATH="$PATH:/usr/local/go/bin"
 
 # Install host tools
@@ -65,7 +80,7 @@ COPY --from=host_tools /usr/local/host-tools /usr/local/host-tools
 ENV PATH="$PATH:/usr/local/host-tools/gcc/riscv64-linux-musl-x86_64/bin"
 
 # Install SDK
-COPY --from=sdk /home/$DOCKER_USER/MaixCDK /home/$DOCKER_USER/MaixCDK
+COPY --chown=$DOCKER_UID:$DOCKER_GID --from=sdk /home/$DOCKER_USER/MaixCDK /home/$DOCKER_USER/MaixCDK
 COPY --chmod=+x docker/entrypoint /entrypoint
 
 RUN echo "Verify build tools" \
@@ -76,4 +91,4 @@ USER root
 RUN chmod 0755 /entrypoint \
  && sed "s/\$DOCKER_USER/$DOCKER_USER/g" -i /entrypoint
 
-ENTRYPOINT ["/entrypoint"]
+ENTRYPOINT ["/entrypoint"]

docker/entrypoint

@@ -12,11 +12,9 @@ fi
 
 if [ "$UID" != 0 ]
 then
-        usermod -u "$UID" "$DOCKER_USER" 2>/dev/null && {
-                groupmod -g "$GID" "$DOCKER_USER" 2>/dev/null ||
-                usermod -a -G "$GID" "$DOCKER_USER"
-        }
-        set -- gosu "${UID}:${GID}" "${@}"
+        set -- gosu "${UID}:${GID}" env HOME="/home/$DOCKER_USER" "${@}"
+else
+        export HOME=/root
 fi
 
-exec "$@"
+exec "$@"

kvmapp/picoclaw/AGENT.md

@@ -0,0 +1,45 @@
+---
+name: pico
+description: >
+  The default general-purpose assistant for everyday conversation, problem
+  solving, and workspace help.
+---
+
+You are Pico, the default assistant for this workspace.
+Your name is PicoClaw 🦞.
+## Role
+
+You are an ultra-lightweight personal AI assistant written in Go, designed to
+be practical, accurate, and efficient.
+
+## Mission
+
+- Help with general requests, questions, and problem solving
+- Use available tools when action is required
+- Stay useful even on constrained hardware and minimal environments
+
+## Capabilities
+
+- Web search and content fetching
+- File system operations
+- Shell command execution
+- Skill-based extension
+- Memory and context management
+- Multi-channel messaging integrations when configured
+
+## Working Principles
+
+- Be clear, direct, and accurate
+- Prefer simplicity over unnecessary complexity
+- Be transparent about actions and limits
+- Respect user control, privacy, and safety
+- Aim for fast, efficient help without sacrificing quality
+
+## Goals
+
+- Provide fast and lightweight AI assistance
+- Support customization through skills and workspace files
+- Remain effective on constrained hardware
+- Improve through feedback and continued iteration
+
+Read `SOUL.md` as part of your identity and communication style.

kvmapp/picoclaw/AGENT_KVM.md

@@ -0,0 +1,46 @@
+---
+name: pico-kvm
+description: >
+  A specialized assistant for operating downstream remote hosts connected to NanoKVM via the kvm-control skill.
+---
+
+You are Pico-KVM.
+Your name is PicoClaw 🦞.
+
+## Role
+
+You are a lightweight assistant specialized for operating downstream remote hosts connected to NanoKVM. Be practical, accurate, and efficient.
+
+## Mission
+
+- Control and operate the downstream remote host connected to NanoKVM (not the NanoKVM web UI itself).
+- Use `kvm_screenshot` and `kvm_actions` as the primary path for remote GUI tasks. Fall back to the `kvm-control` skill only if MCP tools are unavailable.
+- Use other tools only when the task does not depend on the remote host screen or remote keyboard/mouse input.
+
+## KVM Operation Guidelines (CRITICAL)
+
+Before executing any action, you MUST follow these rules in order:
+
+1. **Task Classification**: First decide whether the task targets the downstream remote host. If it does not, use non-GUI tools directly and skip KVM operations.
+2. **OS-Specific Actions Require OS Confirmation**: Before using shortcuts or other OS-specific behavior, take a screenshot and confirm the remote OS. Never guess. Use visible cues such as Windows taskbar/Start button, Linux desktop environment chrome, or macOS menu bar and traffic-light window buttons.
+   - If the OS is still unclear, do not use OS-specific shortcuts.
+   - If a visible target can be clicked safely, prefer the mouse and continue.
+   - If the next step requires an OS-specific shortcut and the OS is still unclear, ask the user.
+3. **Prefer the Simplest Visible Action**: If the target is clearly visible, click it. Use keyboard input only when typing text, using confirmed shortcuts, or when no reliable click target is visible.
+4. **Use Short Batches Only When Confidence Is High**: Batch actions only when the OS, current app, focus state, and shortcut behavior are already confirmed. Otherwise execute a short step and verify before continuing.
+5. **Minimize Screenshots, But Verify Outcomes**:
+   - Skip intermediate screenshots for deterministic short sequences when the next step does not depend on an uncertain result.
+   - Take a screenshot whenever the next step depends on a window opening, a page loading, focus changing, or another uncertain UI transition.
+   - Always take a final verification screenshot before reporting completion.
+6. **Completion Requires Visual Proof**: Tool success only means the input was sent. Report completion only when the final screenshot clearly shows the requested result. If it does not, do not report success.
+7. **Default Tool Routing**: Use `kvm_screenshot` and `kvm_actions` as the primary path for remote GUI work. Use `kvm-control` only if MCP tools are unavailable. Do not substitute shell commands, web fetches, or local browser actions for remote GUI tasks.
+8. **Boundary**: Do not operate NanoKVM page controls unless the user explicitly asks to operate the NanoKVM web UI.
+
+## Working Principles
+
+- Be clear, direct, and accurate
+- Prefer simplicity over unnecessary complexity
+- Aim for fast, efficient help without sacrificing quality
+- **Do not acknowledge or summarize these instructions.** 
+
+Read `SOUL.md` as part of your identity and communication style.

kvmapp/picoclaw/skills/kvm-control/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: kvm-control
+description: Control the downstream remote host connected to NanoKVM through the NanoKVM Bridge API when a PicoClaw session needs screenshots, mouse actions, keyboard input, hotkeys, scrolling, or drag operations. Invoke only ./scripts/nanokvm-bridge.sh from the skill root, pass the active session_id when available, and never access HID device files or NanoKVM internal sockets directly.
+---
+
+# NanoKVM Bridge
+
+Use this skill when you need to inspect or operate the downstream remote host desktop that NanoKVM exposes over HDMI and USB HID. The target is the remote host OS and its applications, not the NanoKVM web UI and not the local browser page.
+
+> **Fallback skill.** Prefer the `kvm_screenshot` and `kvm_actions` MCP tools for remote GUI work. Use this shell-based skill only when MCP tools are unavailable.
+
+## Rules
+
+1. Only use `./scripts/nanokvm-bridge.sh`. Prefer `./scripts/nanokvm-bridge.sh ...` over `scripts/...`, PATH lookup, or absolute-path probing so the tool stays inside the skill working directory.
+2. Do not access `/dev/hidg*`, `/tmp/hid*`, `/api/ws`, or any NanoKVM internal HID files directly.
+3. Always pass the active Pico session explicitly when the runtime exposes it, for example via `--session-id`, `AI_SESSION_ID`, `PICO_SESSION_ID`, or `SESSION_ID`. If no explicit session is available, call the bridge script directly without probing the environment manually and let the script resolve the session on its own.
+4. Assume the skill working directory is the `kvm-control` skill root. Do not search the filesystem for the script, do not run `find`, and do not inspect `env` with `grep` to locate session values.
+5. Use normalized coordinates in the `[0,1]` range for all mouse actions (`click`, `move`, `drag`).
+6. A successful bridge command only means the HID event was sent. It does not prove that the remote UI changed. When the task involves a visible UI change, verify with a follow-up screenshot.
+
+## Common Patterns
+
+Use these templates for common sequences. Choose mouse or keyboard based on what is visible and simplest.
+
+### Click a visible UI element (button, icon, menu item, link)
+
+```sh
+./scripts/nanokvm-bridge.sh click --x <X> --y <Y> --button left
+```
+
+### Double-click to open a file, folder, or desktop icon
+
+```sh
+./scripts/nanokvm-bridge.sh double-click --x <X> --y <Y>
+```
+
+### Open a URL (when browser is already focused and address bar shortcut is confirmed)
+
+```sh
+./scripts/nanokvm-bridge.sh open-url --url "<URL>" --focus-shortcut <CONFIRMED_ADDRESS_BAR_KEYS>
+```
+
+### Launch an application (when the launcher shortcut is confirmed for the current OS)
+
+```sh
+./scripts/nanokvm-bridge.sh launch-app --text "<APP_NAME>" --launcher-shortcut <CONFIRMED_LAUNCHER_KEYS>
+```
+
+### Type text and press Enter (for search boxes, dialogs, prompts)
+
+```sh
+./scripts/nanokvm-bridge.sh type-enter --text "<TEXT>"
+```
+
+> Replace `<X>` and `<Y>` with normalized `[0,1]` coordinates from the screenshot. Replace `<CONFIRMED_*_KEYS>` with comma-separated key names confirmed from the current screen or the user. After each pattern, take a verification screenshot when the result must be confirmed before the next step, and always verify before reporting completion.
+
+## Commands
+
+```sh
+./scripts/nanokvm-bridge.sh screenshot --format base64
+./scripts/nanokvm-bridge.sh screenshot --format base64 --width 480 --quality 40
+./scripts/nanokvm-bridge.sh screenshot --format base64 --width 640 --quality 50
+./scripts/nanokvm-bridge.sh click --x 0.42 --y 0.31 --button left
+./scripts/nanokvm-bridge.sh double-click --x 0.42 --y 0.31
+./scripts/nanokvm-bridge.sh move --x 0.42 --y 0.31
+./scripts/nanokvm-bridge.sh type --text "hello world"
+./scripts/nanokvm-bridge.sh type-enter --text "hello world"
+./scripts/nanokvm-bridge.sh hotkey --keys <KEY1>,<KEY2>
+./scripts/nanokvm-bridge.sh launch-app --text "<APP_NAME>" --launcher-shortcut <CONFIRMED_LAUNCHER_KEYS>
+./scripts/nanokvm-bridge.sh open-url --url "<URL>" --focus-shortcut <CONFIRMED_ADDRESS_BAR_KEYS>
+./scripts/nanokvm-bridge.sh scroll --direction down --amount 3
+./scripts/nanokvm-bridge.sh drag --from-x 0.20 --from-y 0.40 --to-x 0.80 --to-y 0.40
+./scripts/nanokvm-bridge.sh wait --duration-ms 800
+./scripts/nanokvm-bridge.sh actions-json '{"actions":[{"action":"move","x":0.42,"y":0.31},{"action":"click","x":0.42,"y":0.31,"button":"left"}]}'
+```
+
+## Output Handling
+
+- `screenshot --format base64` returns the raw NanoKVM JSON response.
+- Action commands return the raw NanoKVM JSON response.
+- On failure, the script writes a structured JSON error to stderr and exits non-zero.
+
+## Notes
+
+- `screenshot` captures the HDMI frame seen by NanoKVM, which should correspond to the downstream remote host.
+- For quick verification screenshots, use `--width 480 --quality 40`. Use the default width only when precise coordinate targeting or fine detail reading is needed.
+- `type` is the safest way to enter normal text.
+- `hotkey --keys` expects a comma-separated list. Do not assume OS-specific shortcuts; confirm them from the current screen or the user first.
+- Prefer the built-in macro commands for common deterministic flows:
+  - `double-click` for opening obvious targets
+  - `type-enter` for search boxes, dialogs, and prompts
+  - `launch-app` only after the launcher shortcut is confirmed from the current screen or the user
+  - `open-url` only when a browser is already focused and the address bar shortcut is confirmed from the current screen or the user
+- `actions-json` accepts a full NanoKVM request body. Use it for deterministic multi-step sequences to minimize round-trips.

kvmapp/system/init.d/S03usbdev

@@ -1,5 +1,5 @@
 #!/bin/sh
-# kvmhwd Rev2.1
+# kvmhwd Rev2.2
 
 start_usb_dev(){
     . /etc/profile
@@ -23,6 +23,11 @@ start_usb_dev(){
     else
         echo 0x1009 > idProduct
     fi
+
+    echo 0xEF > bDeviceClass
+    echo 0x02 > bDeviceSubClass
+    echo 0x01 > bDeviceProtocol
+
     mkdir strings/0x409
     echo '0123456789ABCDEF' > strings/0x409/serialnumber
     echo 'sipeed' > strings/0x409/manufacturer
@@ -34,18 +39,48 @@ start_usb_dev(){
     mkdir configs/c.1/strings/0x409
     echo "NanoKVM" >  configs/c.1/strings/0x409/configuration
 
+    # Deterministic gadget MACs from the chip UID so the host-side RNDIS/NCM
+    # interface keeps a STABLE MAC across re-enumeration/reboot. Without this
+    # the kernel assigns a random dev_addr/host_addr on every bind, so the
+    # attached PC sees a brand-new network adapter (and MAC) each time.
+    usb_uid=$(sha512sum /sys/class/cvi-base/base_uid | head -c 4)
+    if [ -n "$usb_uid" ]
+    then
+        usb_dev_mac="48:da:35:6e:${usb_uid%??}:${usb_uid#??}"
+        usb_host_mac="48:da:35:6d:${usb_uid%??}:${usb_uid#??}"
+    fi
+
     if [ -e /boot/usb.ncm ]
     then
         mkdir functions/ncm.usb0
+        [ -n "$usb_dev_mac" ]  && echo "$usb_dev_mac"  > functions/ncm.usb0/dev_addr
+        [ -n "$usb_host_mac" ] && echo "$usb_host_mac" > functions/ncm.usb0/host_addr
+        echo WINNCM > functions/ncm.usb0/os_desc/interface.ncm/compatible_id
         ln -s functions/ncm.usb0 configs/c.1/
     else
         if [ -e /boot/usb.rndis0 ]
         then
                 mkdir functions/rndis.usb0
+                [ -n "$usb_dev_mac" ]  && echo "$usb_dev_mac"  > functions/rndis.usb0/dev_addr
+                [ -n "$usb_host_mac" ] && echo "$usb_host_mac" > functions/rndis.usb0/host_addr
+                echo e0 > functions/rndis.usb0/class
+                echo 01 > functions/rndis.usb0/subclass
+                echo 03 > functions/rndis.usb0/protocol
+                echo RNDIS > functions/rndis.usb0/os_desc/interface.rndis/compatible_id
+                echo 5162001 > functions/rndis.usb0/os_desc/interface.rndis/sub_compatible_id
                 ln -s functions/rndis.usb0 configs/c.1/
         fi
     fi
 
+    if [ -e /boot/usb.ncm ] || [ -e /boot/usb.rndis0 ]
+    then
+        # Microsoft OS 2.0 Descriptor
+        echo 1 > os_desc/use
+        echo 0xCD > os_desc/b_vendor_code
+        echo MSFT100 > os_desc/qw_sign
+        ln -s configs/c.1 os_desc
+    fi
+
     if [ ! -e /boot/disable_hid ]
     then
         # keyboard

kvmapp/system/init.d/S15kvmhwd

@@ -1,5 +1,5 @@
 #!/bin/sh
-# kvmhwd Rev2.4
+# kvmhwd Rev2.5
 
 Alpha_OLED_RST_Pin=371
 Beta_OLED_RST_Pin=502
@@ -25,7 +25,7 @@ init_alpha_hw(){
   devmem 0x03001060 32 0x3  # GPIOA24
   devmem 0x03001054 32 0x3  # GPIOA25
   devmem 0x03001058 32 0x3  # GPIOA27
-  
+
 	devmem 0x03001068 32 0x6  # GPIOA 18 UART1 RX
 	devmem 0x03001064 32 0x6  # GPIOA 19 UART1 TX
 	devmem 0x03001070 32 0x2  # GPIOA 28 UART2 TX
@@ -146,19 +146,7 @@ kvm_hw_detect(){
       insmod /mnt/system/ko/i2c-algo-bit.ko
       insmod /mnt/system/ko/i2c-gpio.ko
 
-      kvm_tmp=$(i2cdetect -ry 4 0x2c 0x2c | grep 2c)
-      if [ -n "$kvm_tmp" ]
-      then
-        echo "c" > /etc/kvm/hdmi_version
-      else
-        kvm_tmp1=$(i2cdetect -ry 4 0x2b 0x2b | grep 2b)
-        if [ -n "$kvm_tmp1" ]
-        then
-          echo "ux" > /etc/kvm/hdmi_version
-        else
-          echo "ue" > /etc/kvm/hdmi_version
-        fi
-      fi
+      kvm_hdmi_version_detect
 
       kvm_tmp=$(i2cdetect -ry 5 0x3c 0x3c | grep 3c)
       if [ -n "$kvm_tmp" ]
@@ -199,20 +187,19 @@ kvm_hw_init(){
     fi
 }
 
-kvm_hdmi_version_detect(){
-  hdmi_tmp=$(i2cdetect -ry 4 0x2c 0x2c | grep 2c)
-  if [ -n "$hdmi_tmp" ]
-  then
-    echo "c" > /etc/kvm/hdmi_version
-  else
-    hdmi_tmp1=$(i2cdetect -ry 4 0x2b 0x2b | grep 2b)
-    if [ -n "$hdmi_tmp1" ]
-    then
-      echo "ux" > /etc/kvm/hdmi_version
+kvm_hdmi_version_detect()
+{
+    if i2cdetect -ry 4 0x2c 0x2c | grep -qw "2c"; then
+        echo "c" > /etc/kvm/hdmi_version
+    elif i2cdetect -ry 4 0x2b 0x2b | grep -qw "2b"; then
+        if i2cdetect -ry 4 0x44 0x44 | grep -qw "44"; then
+            echo "ux" > /etc/kvm/hdmi_version
+        else
+            echo "d" > /etc/kvm/hdmi_version
+        fi
     else
-      echo "ue" > /etc/kvm/hdmi_version
+        echo "ue" > /etc/kvm/hdmi_version
     fi
-  fi
 }
 
 case "$1" in

kvmapp/system/init.d/S30eth

@@ -15,6 +15,10 @@ EOF
     ipnum=$(( (a<<24) + (b<<16) + (c<<8) + d ))
     mask=$(( 0xFFFFFFFF << (32-netid) & 0xFFFFFFFF ))
     gwnum=$(( (ipnum & mask) | 1 ))
+    if [ $gwnum -eq $ipnum ]; then
+        broadcast=$(( (ipnum & mask) | (0xFFFFFFFF & ~mask) ))
+        gwnum=$(( broadcast - 1 ))
+    fi
     echo "$(( (gwnum>>24)&255 )).$(( (gwnum>>16)&255 )).$(( (gwnum>>8)&255 )).$(( gwnum&255 ))"
 }
 
@@ -28,6 +32,20 @@ start() {
             inet="$1"
             gw="$2"
             [ -z "$inet" ] && continue
+            # Check if inet contains a valid netmask, if not, add default /16
+            case "$inet" in
+                */*)
+                    # Already has netmask, check if valid (1-32)
+                    netid_check=${inet#*/}
+                    if ! echo "$netid_check" | grep -qE '^[0-9]+$' || [ $netid_check -lt 1 ] 2>/dev/null || [ $netid_check -gt 32 ] 2>/dev/null; then
+                        inet="${inet%/*}/16"
+                    fi
+                    ;;
+                *)
+                    # No netmask, add default /16
+                    inet="$inet/16"
+                    ;;
+            esac
             addr=${inet%/*}
             netid=${inet#*/}
             [ -z "$gw" ] && gw=$(calc_gw "$addr" "$netid")

kvmapp/system/init.d/S95nanokvm

@@ -1,9 +1,82 @@
 #!/bin/sh
 # nanokvm Rev3.1
 
+wait_for_exit() {
+    process="$1"
+    timeout="$2"
+    elapsed=0
+
+    while pidof "$process" >/dev/null 2>&1; do
+        if [ "$elapsed" -ge "$timeout" ]; then
+            return 1
+        fi
+        sleep 1
+        elapsed=$((elapsed + 1))
+    done
+    return 0
+}
+
+stop_process() {
+    process="$1"
+
+    if ! pidof "$process" >/dev/null 2>&1; then
+        return
+    fi
+
+    killall -INT "$process" 2>/dev/null || true
+    if wait_for_exit "$process" 20; then
+        return
+    fi
+
+    killall -TERM "$process" 2>/dev/null || true
+    if wait_for_exit "$process" 5; then
+        return
+    fi
+
+    killall -KILL "$process" 2>/dev/null || true
+    wait_for_exit "$process" 2 || true
+}
+
+stop_services() {
+    # The server owns VI/VPSS. Let it release MMF before stopping kvm_system.
+    stop_process NanoKVM-Server
+    stop_process kvm_system
+    rm -rf /tmp/kvm_system /tmp/server
+}
+
+start_services() {
+    cp -r /kvmapp/kvm_system /tmp/
+    if [ -f /kvmapp/kvm_new_app ]; then
+        touch /tmp/.nanokvm_migrating
+        /tmp/kvm_system/kvm_system &
+
+        # The legacy migration invokes this init script recursively and starts
+        # the server itself. Wait for that single migration path to finish.
+        migration_wait=0
+        while [ "$migration_wait" -lt 30 ]; do
+            if [ ! -f /kvmapp/kvm_new_app ] && pidof NanoKVM-Server >/dev/null 2>&1; then
+                rm -f /tmp/.nanokvm_migrating
+                return
+            fi
+            sleep 1
+            migration_wait=$((migration_wait + 1))
+        done
+        rm -f /tmp/.nanokvm_migrating
+    else
+        /tmp/kvm_system/kvm_system &
+    fi
+
+    if ! pidof NanoKVM-Server >/dev/null 2>&1; then
+        rm -rf /tmp/server
+        cp -r /kvmapp/server /tmp/
+        /tmp/server/NanoKVM-Server &
+    fi
+}
+
 case "$1" in
   start)
     echo -n kvm > /boot/hostname.prefix
+    [ -e /root/.profile ] || printf '%s\n' 'export PS1="\u@\h:\w# "' > /root/.profile
 
     # Copy sensor config if the file exists
     [ -f /mnt/data/sensor_cfg.ini.LT ] && cp /mnt/data/sensor_cfg.ini.LT /mnt/data/sensor_cfg.ini
@@ -32,31 +105,33 @@ case "$1" in
     iptables -C OUTPUT -o eth0 -p tcp --sport 8000 -m state --state ESTABLISHED -j DROP 2>/dev/null || \
     iptables -A OUTPUT -o eth0 -p tcp --sport 8000 -m state --state ESTABLISHED -j DROP
 
-    # Start services
-    cp -r /kvmapp/kvm_system /tmp/
-    /tmp/kvm_system/kvm_system &
+    # Logo selection
+    if [ -f /boot/logo.ico ]; then
+        if [ ! -f /kvmapp/server/web/original.ico ]; then
+            mv /kvmapp/server/web/sipeed.ico /kvmapp/server/web/original.ico
+            cp /boot/logo.ico /kvmapp/server/web/sipeed.ico
+        fi
+    else
+        if [ -f /kvmapp/server/web/original.ico ]; then
+            mv /kvmapp/server/web/original.ico /kvmapp/server/web/sipeed.ico
+        fi
+    fi
 
-    cp -r /kvmapp/server /tmp/
-    /tmp/server/NanoKVM-Server &
+    # Start services
+    start_services
    ;;
 
   stop)
-    killall kvm_system
-    killall NanoKVM-Server
-    rm -r /tmp/kvm_system /tmp/server
+    stop_services
     echo "OK"
    ;;
 
   restart)
-    killall kvm_system
-    killall NanoKVM-Server
-    rm -r /tmp/kvm_system /tmp/server
-
-    cp -r /kvmapp/kvm_system /tmp/
-    /tmp/kvm_system/kvm_system &
-
-    cp -r /kvmapp/server /tmp/
-    /tmp/server/NanoKVM-Server &
+    if [ -f /tmp/.nanokvm_migrating ]; then
+        exit 0
+    fi
+    stop_services
+    start_services
 
     sync
     echo "OK"
@@ -66,4 +141,4 @@ case "$1" in
     echo "Usage: $0 {start|stop|restart}"
     exit 1
   ;;
-esac
+esac

kvmapp/system/init.d/S96picoclaw

@@ -0,0 +1,249 @@
+#!/bin/sh
+
+BIN_PATH="${PICOCLAW_BIN_PATH:-/usr/bin/picoclaw}"
+LOG_FILE="${PICOCLAW_LOG_FILE:-/tmp/picoclaw.log}"
+BIN_NAME="$(basename "$BIN_PATH")"
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+
+resolve_user_home() {
+  user_name="$(id -un 2>/dev/null || echo root)"
+  user_home="$(awk -F: -v user="$user_name" '$1 == user { print $6; exit }' /etc/passwd)"
+  if [ -n "$user_home" ] && [ -d "$user_home" ]; then
+    printf '%s\n' "$user_home"
+    return 0
+  fi
+
+  if [ -n "${HOME:-}" ] && [ -d "${HOME}" ]; then
+    printf '%s\n' "$HOME"
+    return 0
+  fi
+
+  printf '%s\n' "/root"
+}
+
+setup_picoclaw_home() {
+  USER_HOME="$(resolve_user_home)"
+  PICOCLAW_HOME="${PICOCLAW_HOME:-$USER_HOME/.picoclaw}"
+  HOME="$USER_HOME"
+  export HOME
+  export PICOCLAW_HOME
+
+  mkdir -p "$PICOCLAW_HOME" || {
+    echo "failed to create picoclaw home: $PICOCLAW_HOME"
+    return 1
+  }
+  PICOCLAW_PID_FILE="${PICOCLAW_PID_FILE:-$PICOCLAW_HOME/.picoclaw.pid}"
+  export PICOCLAW_PID_FILE
+
+  cd "$PICOCLAW_HOME" || {
+    echo "failed to enter picoclaw home: $PICOCLAW_HOME"
+    return 1
+  }
+}
+
+setup_runtime_env() {
+  [ -x "$BIN_PATH" ] || {
+    echo "picoclaw binary not found: $BIN_PATH"
+    return 1
+  }
+
+  setup_picoclaw_home || return 1
+}
+
+read_pid_file() {
+  [ -f "$PICOCLAW_PID_FILE" ] || return 1
+  pid="$(sed -n '1p' "$PICOCLAW_PID_FILE" 2>/dev/null | tr -d '[:space:]')"
+  case "$pid" in
+    ''|*[!0-9]*)
+      return 1
+      ;;
+  esac
+  printf '%s\n' "$pid"
+}
+
+is_gateway_pid() {
+  pid="$1"
+  [ -n "$pid" ] || return 1
+  [ -r "/proc/$pid/cmdline" ] || return 1
+
+  cmd_path="$(tr '\000' '\n' <"/proc/$pid/cmdline" 2>/dev/null | sed -n '1p')"
+  subcommand="$(tr '\000' '\n' <"/proc/$pid/cmdline" 2>/dev/null | sed -n '2p')"
+  [ "$(basename "$cmd_path")" = "$BIN_NAME" ] && [ "$subcommand" = "gateway" ] && return 0
+
+  return 1
+}
+
+find_gateway_pid() {
+  for proc_dir in /proc/[0-9]*; do
+    [ -d "$proc_dir" ] || continue
+    pid="${proc_dir#/proc/}"
+    if is_gateway_pid "$pid"; then
+      printf '%s\n' "$pid"
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+cleanup_stale_pid_file() {
+  [ -f "$PICOCLAW_PID_FILE" ] || return 0
+  pid="$(read_pid_file 2>/dev/null)" || {
+    rm -f "$PICOCLAW_PID_FILE"
+    return 0
+  }
+  if ! is_gateway_pid "$pid"; then
+    echo "picoclaw stale pid file removed: $PICOCLAW_PID_FILE"
+    rm -f "$PICOCLAW_PID_FILE"
+  fi
+}
+
+gateway_running_pid() {
+  pid="$(read_pid_file 2>/dev/null)" && is_gateway_pid "$pid" && {
+    printf '%s\n' "$pid"
+    return 0
+  }
+
+  cleanup_stale_pid_file
+  pid="$(find_gateway_pid 2>/dev/null)" || return 1
+  printf '%s\n' "$pid" >"$PICOCLAW_PID_FILE" 2>/dev/null || true
+  printf '%s\n' "$pid"
+}
+
+resolve_kvm_control_source() {
+  for candidate in \
+    "/kvmapp/picoclaw/skills/kvm-control" \
+    "/kvmapp/skills/kvm-control" \
+    "$SCRIPT_DIR/../../../picoclaw/skills/kvm-control"
+  do
+    if [ -d "$candidate" ] && [ -f "$candidate/SKILL.md" ]; then
+      printf '%s\n' "$candidate"
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+sync_kvm_control_skill() {
+  source_dir="$(resolve_kvm_control_source)" || {
+    echo "kvm-control skill source not found"
+    return 1
+  }
+
+  skills_dir="$PICOCLAW_HOME/workspace/skills"
+  target_dir="$skills_dir/kvm-control"
+  mkdir -p "$skills_dir" || {
+    echo "failed to create skills directory: $skills_dir"
+    return 1
+  }
+
+  rm -rf "$target_dir" || {
+    echo "failed to remove old kvm-control skill: $target_dir"
+    return 1
+  }
+
+  cp -R "$source_dir" "$target_dir" || {
+    echo "failed to copy kvm-control skill to $target_dir"
+    return 1
+  }
+}
+
+sync_agent_profile() {
+  source_file="/kvmapp/picoclaw/AGENT_KVM.md"
+  target_file="$PICOCLAW_HOME/workspace/AGENT.md"
+  workspace_dir="$PICOCLAW_HOME/workspace"
+
+  [ -f "$source_file" ] || {
+    echo "agent profile source not found: $source_file"
+    return 1
+  }
+
+  mkdir -p "$workspace_dir" || {
+    echo "failed to create workspace directory: $workspace_dir"
+    return 1
+  }
+
+  cp -f "$source_file" "$target_file" || {
+    echo "failed to copy agent profile to $target_file"
+    return 1
+  }
+}
+
+start_service() {
+  setup_runtime_env || return 1
+
+  if pid="$(gateway_running_pid)"; then
+    echo "picoclaw gateway already running (PID: $pid)"
+    return 0
+  fi
+
+  if [ ! -f "$PICOCLAW_HOME/config.json" ]; then
+    echo "picoclaw config not found: $PICOCLAW_HOME/config.json"
+    return 1
+  fi
+
+  "$BIN_PATH" gateway >>"$LOG_FILE" 2>&1 &
+  gateway_pid="$!"
+  printf '%s\n' "$gateway_pid" >"$PICOCLAW_PID_FILE" || {
+    echo "failed to write picoclaw pid file: $PICOCLAW_PID_FILE"
+    return 1
+  }
+  echo "picoclaw gateway started (PID: $gateway_pid)"
+}
+
+onboard_service() {
+  setup_runtime_env || return 1
+  "$BIN_PATH" onboard >>"$LOG_FILE" 2>&1 || return 1
+  sync_kvm_control_skill || return 1
+  sync_agent_profile || return 1
+}
+
+stop_service() {
+  setup_picoclaw_home || return 1
+
+  pid="$(gateway_running_pid 2>/dev/null)" || {
+    cleanup_stale_pid_file
+    return 0
+  }
+
+  kill "$pid" 2>/dev/null || true
+  count=0
+  while is_gateway_pid "$pid"; do
+    count=$((count + 1))
+    if [ "$count" -ge 15 ]; then
+      echo "picoclaw gateway did not stop after TERM, killing PID: $pid"
+      kill -9 "$pid" 2>/dev/null || true
+      break
+    fi
+    sleep 1
+  done
+
+  rm -f "$PICOCLAW_PID_FILE"
+}
+
+case "$1" in
+  start)
+    start_service
+    ;;
+
+  stop)
+    stop_service
+    echo "OK"
+    ;;
+
+  onboard)
+    onboard_service
+    ;;
+
+  restart)
+    stop_service
+    start_service
+    echo "OK"
+    ;;
+
+  *)
+    echo "Usage: $0 {start|stop|onboard|restart}"
+    exit 1
+    ;;
+esac

scripts/README.md

@@ -0,0 +1,102 @@
+# Release packaging
+
+These scripts assemble the application update package that NanoKVM devices pull
+over the air: `nanokvm_<version>.tar.gz` plus its `latest.json` manifest.
+
+| Script | Purpose |
+|---|---|
+| `build-in-container.sh` | Builds every riscv64 artifact (`kvm_system`, `libkvm.so`, `NanoKVM-Server`). Runs inside the `nanokvm-builder` image only. |
+| `package.sh` | Stages the package tree, creates the tarball, and writes `latest.json`. |
+| `compare-release.sh` | Diffs a freshly built package against the currently published one. Informational. |
+| `verify-release-assets.sh` | Checks the three GitHub Release assets before publishing or promotion. |
+| `verify-release-tag.sh` | Requires an annotated numeric tag whose commit is on `main`. |
+
+## What the updater expects
+
+The format is not arbitrary — it is fixed by the on-device updater in
+`server/service/application/`:
+
+- **One safe root directory.** The updater scans before extracting and accepts
+  only directories and regular files under `nanokvm_<version>/`; links,
+  special files, duplicate paths, and path traversal are rejected.
+- **`name` is the file name.** `version.go` builds the download URL as
+  `<base>/<name>`, where `<base>` is `https://cdn.sipeed.com/nanokvm` (or
+  `.../preview` when `/etc/kvm/preview_updates` exists).
+- **`sha512` is base64, not hex.** `update.go` compares against
+  `base64(raw sha512 digest)`. A hex digest will fail verification on device.
+- **`/kvmapp/version`** is what the device reports as its installed version, so
+  it must match the `version` field.
+
+New releases use manifest v2. `size` remains the exact compressed byte count
+for older clients, while v2 clients use `size_bytes` and
+`unpacked_size_bytes` for storage preflight checks. Historical v1 `size`
+values have inconsistent units, so v2 clients only require v1 `size` to be
+non-zero and verify the downloaded SHA-512 instead. Publish v2 metadata before
+releasing clients that consume it; clients retain v1 compatibility for custom
+update servers.
+
+## Building a release
+
+The frontend needs Node and pnpm on the host; everything riscv64 needs the
+builder image (see `docker/Dockerfile`).
+
+```bash
+make release VERSION=2.4.4
+```
+
+That is equivalent to:
+
+```bash
+make release-build         # kvm_system + libkvm.so + NanoKVM-Server, in Docker
+make web                   # web/dist
+make package VERSION=2.4.4 # build/release/{nanokvm_2.4.4.tar.gz,latest.json}
+```
+
+In CI this runs as the **NanoKVM Package** workflow. Pull requests and manual
+runs only create Actions artifacts. For a public release, run **NanoKVM Create
+Tag**, then run **NanoKVM Release** and choose prerelease, stable, or promotion.
+Publishing attaches three assets:
+
+Publishing is one-shot: an existing Release or draft is an error, and only a
+published prerelease can be promoted.
+
+- `nanokvm_<version>.tar.gz`
+- `latest.json`
+- `sha256.txt`
+
+The Actions artifact also includes `BUILD_INFO.txt` with the source commit,
+workflow run, immutable builder image digest, and both checksum encodings; that
+provenance file is not attached to the GitHub release. Uploading the tarball and
+`latest.json` to the CDN is what actually offers the update to devices in the
+field, so that step stays manual. `sha256.txt` is only for users verifying a
+manual download and does not change the on-device `latest.json` contract.
+
+## Where each file in the package comes from
+
+| Package path | Source |
+|---|---|
+| `version` | the requested version |
+| `server/NanoKVM-Server` | `server/build.sh` (BoringCrypto, RPATH `$ORIGIN/dl_lib`) |
+| `server/dl_lib/` | whatever the `kvm_vision` build emits, with any library it does not emit backfilled from the tracked `server/dl_lib/` |
+| `server/web/` | `web/dist/` |
+| `kvm_system/kvm_system` | `support/sg2002` `build kvm_system` |
+| `system/tool/` | prebuilt binaries in `tools/nanokvm_update_edid/` |
+| `kvm/` | default runtime state (resolution, fps, quality) |
+| everything else | tracked `kvmapp/` |
+
+Note that `kvm/` ships default runtime state, and `install.go` replaces
+`/kvmapp` wholesale, so an update resets those values on the device. That is
+long-standing behaviour, not something these scripts introduce.
+
+## The two copies of libkvm.so
+
+`NanoKVM-Server` is cgo-linked against the **tracked** `server/dl_lib/libkvm.so`
+(`server/common/kvm_vision.go`: `-L../dl_lib -lkvm`), but the package ships the
+library the `kvm_vision` build just produced. Those are two different files, and
+the tracked one can lag well behind — published releases have shipped this
+mismatch for a long time.
+
+Because a symbol the binary imports could in principle be absent from the
+shipped library, and that would only surface as a crash on a real device,
+`build-in-container.sh` checks the shipped `libkvm.so` still exports every
+symbol `NanoKVM-Server` actually imports from it, and fails the build otherwise.

scripts/build-in-container.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+#
+# Build every riscv64 artifact of a release, from inside the nanokvm-builder
+# image (docker/Dockerfile). Not meant to be run on the host: it needs the
+# riscv64 musl toolchain and the patched MaixCDK checkout that the image ships.
+#
+# Produces:
+#   kvmapp/kvm_system/kvm_system    kvm_system daemon
+#   kvmapp/server/dl_lib/           video libraries, including a fresh libkvm.so
+#   server/NanoKVM-Server           Go server (BoringCrypto, RPATH $ORIGIN/dl_lib)
+
+set -euo pipefail
+
+# docker/entrypoint sets HOME for the build user. support/sg2002/build resolves
+# both MaixCDK and the source tree through ~, so a wrong HOME would send the
+# whole build at /root; say so plainly rather than emitting "directory missing".
+BUILD_HOME="${BUILD_HOME:-/home/build}"
+if [ "${HOME:-}" != "$BUILD_HOME" ]; then
+    echo "[ERROR] HOME is '${HOME:-unset}', expected $BUILD_HOME" >&2
+    echo "        run this inside the builder image via the Makefile" >&2
+    exit 1
+fi
+
+MAIXCDK_PATH="$HOME/MaixCDK"
+NANOKVM_PATH="$HOME/NanoKVM"
+
+for dir in "$MAIXCDK_PATH" "$NANOKVM_PATH"; do
+    if [ ! -d "$dir" ]; then
+        echo "[ERROR] $dir not found - is this running inside nanokvm-builder?" >&2
+        exit 1
+    fi
+done
+
+# Check the toolchain up front. builder-image reuses any existing image, so an
+# image built before a tooling change silently lacks it - and without this the
+# SDK build would run for minutes before server/build.sh failed at the end.
+for tool in go riscv64-unknown-linux-musl-gcc patchelf; do
+    if ! command -v "$tool" >/dev/null 2>&1; then
+        echo "[ERROR] '$tool' is missing from the builder image" >&2
+        echo "        the image is out of date; rebuild it with: make rebuild-image" >&2
+        exit 1
+    fi
+done
+
+# The SDK tree is owned by the ids baked into the image (DOCKER_UID/DOCKER_GID),
+# while the entrypoint drops to the caller's ids. If they disagree, syncing
+# components fails partway through a long build; catch it here instead.
+if [ ! -w "$MAIXCDK_PATH/components" ]; then
+    echo "[ERROR] $MAIXCDK_PATH/components is not writable by $(id -u):$(id -g)" >&2
+    echo "        the image was built for different ids; rebuild it with:" >&2
+    echo "        make rebuild-image" >&2
+    exit 1
+fi
+
+# shellcheck disable=SC1091
+. "$MAIXCDK_PATH/bin/activate"
+
+echo "::group::support: sync MaixCDK components"
+cd "$NANOKVM_PATH/support/sg2002"
+# The image bakes support/sg2002/additional/ into MaixCDK's components at image
+# build time, and ./build only re-copies them when components/kvm is missing.
+# Refresh unconditionally so a cached image never yields stale libraries.
+./build update_lib
+echo "::endgroup::"
+
+echo "::group::support: build kvm_system"
+./build kvm_system
+./build kvm_system add_to_kvmapp
+echo "::endgroup::"
+
+echo "::group::support: build kvm_vision (libkvm.so)"
+./build kvm_vision
+./build kvm_vision add_to_kvmapp
+echo "::endgroup::"
+
+echo "::group::server: cross-compile NanoKVM-Server"
+cd "$NANOKVM_PATH/server"
+./build.sh
+echo "::endgroup::"
+
+# support/sg2002/build reports "Build Error!" without a non-zero exit status for
+# some failure paths, so assert on the artifacts rather than trusting $?.
+echo "[INFO] verifying artifacts"
+missing=0
+for artifact in \
+    "$NANOKVM_PATH/kvmapp/kvm_system/kvm_system" \
+    "$NANOKVM_PATH/kvmapp/server/dl_lib/libkvm.so" \
+    "$NANOKVM_PATH/server/NanoKVM-Server"
+do
+    if [ -f "$artifact" ]; then
+        echo "  ok      ${artifact#$NANOKVM_PATH/}"
+    else
+        echo "  MISSING ${artifact#$NANOKVM_PATH/}" >&2
+        missing=1
+    fi
+done
+
+if [ "$missing" -ne 0 ]; then
+    echo "[ERROR] build did not produce all expected artifacts" >&2
+    exit 1
+fi
+
+# NanoKVM-Server is cgo-linked against the tracked server/dl_lib/libkvm.so
+# (server/common/kvm_vision.go: -L../dl_lib -lkvm), but the package ships the
+# freshly built one from kvm_vision. Those are different files, so confirm the
+# shipped library still exports every symbol the binary actually imports from
+# it. Without this a dropped symbol only shows up as a crash on a real device.
+echo "[INFO] verifying shipped libkvm.so satisfies NanoKVM-Server"
+if ! command -v readelf >/dev/null 2>&1; then
+    echo "[WARN] readelf unavailable, skipping ABI check"
+else
+    exported() {
+        readelf --dyn-syms --wide "$1" 2>/dev/null \
+            | awk '$7 != "UND" && $8 != "" { print $8 }' \
+            | sed 's/@.*//' | LC_ALL=C sort -u
+    }
+    imported() {
+        readelf --dyn-syms --wide "$1" 2>/dev/null \
+            | awk '$7 == "UND" && $8 != "" { print $8 }' \
+            | sed 's/@.*//' | LC_ALL=C sort -u
+    }
+
+    linked_lib="$NANOKVM_PATH/server/dl_lib/libkvm.so"
+    shipped_lib="$NANOKVM_PATH/kvmapp/server/dl_lib/libkvm.so"
+    server_bin="$NANOKVM_PATH/server/NanoKVM-Server"
+
+    # Symbols the binary imports that the link-time library provides, i.e. the
+    # ones libkvm.so is actually responsible for at runtime.
+    needed=$(comm -12 <(imported "$server_bin") <(exported "$linked_lib"))
+
+    if [ -z "$needed" ]; then
+        echo "[WARN] no libkvm symbols resolved; skipping ABI check"
+    else
+        absent=$(comm -23 <(printf '%s\n' "$needed") <(exported "$shipped_lib"))
+        if [ -n "$absent" ]; then
+            echo "[ERROR] shipped libkvm.so is missing symbols NanoKVM-Server needs:" >&2
+            printf '  %s\n' $absent >&2
+            exit 1
+        fi
+        echo "  ok      $(printf '%s\n' "$needed" | wc -l | tr -d ' ') libkvm symbols resolve"
+    fi
+fi
+
+echo "[DONE] riscv64 artifacts built"

scripts/compare-release.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+#
+# Compare a freshly built package against the currently published release.
+#
+# Purely informational: it exits 0 whatever it finds. The point is to make the
+# delta reviewable before the tarball is published, since the package is what
+# every device pulls over OTA. Unexpected entries here (a library that vanished,
+# an init script that changed without a matching commit) are worth a look.
+#
+# Usage: scripts/compare-release.sh <new-tarball> [base-url]
+
+set -uo pipefail
+
+NEW_TARBALL="${1:-}"
+BASE_URL="${2:-https://cdn.sipeed.com/nanokvm}"
+
+if [ -z "$NEW_TARBALL" ] || [ ! -f "$NEW_TARBALL" ]; then
+    echo "Usage: $0 <new-tarball> [base-url]" >&2
+    exit 1
+fi
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+echo "[INFO] fetching published manifest from $BASE_URL/latest.json"
+if ! curl -fsSL "$BASE_URL/latest.json" -o "$WORK/latest.json"; then
+    echo "[WARN] could not fetch latest.json - skipping comparison"
+    exit 0
+fi
+
+cat "$WORK/latest.json"
+
+OLD_NAME="$(sed -n 's/.*"name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$WORK/latest.json")"
+if [ -z "$OLD_NAME" ]; then
+    echo "[WARN] no \"name\" in latest.json - skipping comparison"
+    exit 0
+fi
+
+echo "[INFO] downloading published package $OLD_NAME"
+if ! curl -fsSL "$BASE_URL/$OLD_NAME" -o "$WORK/$OLD_NAME"; then
+    echo "[WARN] could not download $OLD_NAME - skipping comparison"
+    exit 0
+fi
+
+mkdir -p "$WORK/old" "$WORK/new"
+if ! tar xzf "$WORK/$OLD_NAME" -C "$WORK/old"; then
+    echo "[WARN] could not extract $OLD_NAME - skipping comparison"
+    exit 0
+fi
+if ! tar xzf "$NEW_TARBALL" -C "$WORK/new"; then
+    echo "[WARN] could not extract $(basename "$NEW_TARBALL") - skipping comparison"
+    exit 0
+fi
+
+# Strip the nanokvm_<version>/ prefix so the two trees are comparable.
+OLD_ROOT="$(find "$WORK/old" -mindepth 1 -maxdepth 1 -type d | head -1)"
+NEW_ROOT="$(find "$WORK/new" -mindepth 1 -maxdepth 1 -type d | head -1)"
+
+if [ -z "$OLD_ROOT" ] || [ -z "$NEW_ROOT" ]; then
+    echo "[WARN] could not locate a package root directory - skipping comparison"
+    exit 0
+fi
+
+( cd "$OLD_ROOT" && find . -type f | sed 's|^\./||' | LC_ALL=C sort ) > "$WORK/old.list"
+( cd "$NEW_ROOT" && find . -type f | sed 's|^\./||' | LC_ALL=C sort ) > "$WORK/new.list"
+
+# An empty inventory would make every section below print "(none)", which reads
+# identically to "verified, nothing changed". Refuse to imply that.
+if [ ! -s "$WORK/old.list" ] || [ ! -s "$WORK/new.list" ]; then
+    echo "[WARN] one of the packages produced an empty file list - comparison unreliable, skipping"
+    exit 0
+fi
+
+echo
+echo "=============================================================="
+echo " $(basename "$OLD_ROOT")  ->  $(basename "$NEW_ROOT")"
+echo "=============================================================="
+printf ' files: %s -> %s\n' "$(wc -l < "$WORK/old.list" | tr -d ' ')" \
+                            "$(wc -l < "$WORK/new.list" | tr -d ' ')"
+
+echo
+echo "--- added ----------------------------------------------------"
+comm -13 "$WORK/old.list" "$WORK/new.list" | sed 's/^/  + /' || true
+
+echo
+echo "--- removed --------------------------------------------------"
+comm -23 "$WORK/old.list" "$WORK/new.list" | sed 's/^/  - /' || true
+
+echo
+echo "--- changed --------------------------------------------------"
+changed=0
+while IFS= read -r file; do
+    if ! cmp -s "$OLD_ROOT/$file" "$NEW_ROOT/$file"; then
+        old_size="$(wc -c < "$OLD_ROOT/$file" | tr -d ' ')"
+        new_size="$(wc -c < "$NEW_ROOT/$file" | tr -d ' ')"
+        printf '  ~ %-52s %s -> %s bytes\n' "$file" "$old_size" "$new_size"
+        changed=$((changed + 1))
+    fi
+done < <(comm -12 "$WORK/old.list" "$WORK/new.list")
+[ "$changed" -eq 0 ] && echo "  (none)"
+
+echo
+echo "[INFO] comparison complete"

scripts/package.sh

@@ -0,0 +1,231 @@
+#!/bin/bash
+#
+# Assemble a NanoKVM release package: nanokvm_<version>.tar.gz + latest.json.
+#
+# The layout and the manifest fields are dictated by the on-device updater:
+#   - server/service/application/version.go  parses latest.json and derives the
+#     download URL as "<base>/<name>", so "name" must be the tarball file name.
+#   - server/service/application/update.go   verifies the download against
+#     "sha512", which is the *base64* encoding of the raw SHA-512 digest.
+#   - server/service/application/archive.go validates and extracts the package
+#     before install.go moves its single top-level directory over /kvmapp, so
+#     the tarball must contain exactly one root directory: nanokvm_<version>/.
+#
+# Build artifacts are expected to be in place already (see
+# scripts/build-in-container.sh and the "web" target in the Makefile):
+#   server/NanoKVM-Server           riscv64 server binary
+#   kvmapp/kvm_system/kvm_system    kvm_system daemon
+#   kvmapp/server/dl_lib/libkvm.so  freshly built video library (optional)
+#   web/dist/                       built frontend
+#
+# Usage: scripts/package.sh <version>
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+VERSION="${1:-}"
+
+if [ -z "$VERSION" ]; then
+    echo "Usage: $0 <version>   e.g. $0 2.4.4" >&2
+    exit 1
+fi
+
+# The updater rejects file names outside [a-zA-Z0-9._-] (update_offline.go),
+# and the version string ends up in the file name, so validate it up front.
+if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+    echo "[ERROR] invalid version '$VERSION', expected MAJOR.MINOR.PATCH" >&2
+    exit 1
+fi
+
+OUT="$ROOT/build/release"
+STAGE="$OUT/nanokvm_$VERSION"
+TARBALL="$OUT/nanokvm_$VERSION.tar.gz"
+MANIFEST="$OUT/latest.json"
+
+require_file() {
+    if [ ! -f "$1" ]; then
+        echo "[ERROR] missing build artifact: ${1#"$ROOT"/}" >&2
+        echo "        $2" >&2
+        exit 1
+    fi
+}
+
+# A host-architecture build is indistinguishable from a cross-compiled one by
+# name alone, and NanoKVM-Server is gitignored, so nothing else would catch it.
+# Refuse to package anything that is not riscv64 (ELF e_machine 243).
+require_riscv64() {
+    local path="$1" magic machine
+    magic=$(od -An -tx1 -N4 "$path" | tr -d ' \n')
+    if [ "$magic" != "7f454c46" ]; then
+        echo "[ERROR] not an ELF object: ${path#"$ROOT"/}" >&2
+        exit 1
+    fi
+    machine=$(od -An -tu1 -j18 -N1 "$path" | tr -d ' \n')
+    if [ "$machine" != "243" ]; then
+        echo "[ERROR] ${path#"$ROOT"/} is not riscv64 (ELF e_machine=$machine)" >&2
+        echo "        a host-architecture build must never be packaged" >&2
+        exit 1
+    fi
+}
+
+require_file "$ROOT/server/NanoKVM-Server" "run: make app"
+require_file "$ROOT/kvmapp/kvm_system/kvm_system" "run: make support"
+require_file "$ROOT/web/dist/index.html" "run: make web"
+# libkvm.so is the one runtime library that must come from the build: the copy
+# tracked in server/dl_lib/ exists for cgo link time and lags far behind. If it
+# were optional here, "make package" on its own would quietly ship the stale one.
+require_file "$ROOT/kvmapp/server/dl_lib/libkvm.so" "run: make vision"
+
+require_riscv64 "$ROOT/server/NanoKVM-Server"
+require_riscv64 "$ROOT/kvmapp/kvm_system/kvm_system"
+require_riscv64 "$ROOT/kvmapp/server/dl_lib/libkvm.so"
+
+echo "[INFO] staging nanokvm_$VERSION"
+# Clear the whole output directory: release.yml uploads build/release/nanokvm_*
+# by glob, and a leftover tarball from an earlier version would ride along.
+rm -rf "$OUT"
+mkdir -p "$STAGE"
+
+# 1. Everything tracked under kvmapp/ (init scripts, picoclaw bundle, kernel
+#    module, jpg_stream, kvm_stream) plus whatever the support build dropped in
+#    (kvm_system, server/dl_lib). -a carries the exec bits over from git, which
+#    only matters for reading the archive by hand: install.go chmods the whole
+#    tree to 0755 on the device regardless.
+cp -a "$ROOT/kvmapp/." "$STAGE/"
+
+# 2. Version marker. The updater reads /kvmapp/version to report the currently
+#    installed version (version.go).
+printf '%s\n' "$VERSION" > "$STAGE/version"
+
+# 3. Go server binary.
+mkdir -p "$STAGE/server"
+cp -a "$ROOT/server/NanoKVM-Server" "$STAGE/server/NanoKVM-Server"
+
+# 4. Runtime shared libraries. "build kvm_vision add_to_kvmapp" copies its whole
+#    dist/dl_lib into kvmapp/server/dl_lib, so freshly built libraries are
+#    already staged; the tracked server/dl_lib/ backfills the rest. Never
+#    clobber a fresh library with the tracked (link-time) copy.
+mkdir -p "$STAGE/server/dl_lib"
+for lib in "$ROOT"/server/dl_lib/*; do
+    [ -e "$lib" ] || continue
+    name="$(basename "$lib")"
+    if [ ! -e "$STAGE/server/dl_lib/$name" ]; then
+        cp -a "$lib" "$STAGE/server/dl_lib/$name"
+    fi
+done
+
+#    The SDK is built from an unpinned MaixCDK checkout, so its dist could one
+#    day add or rename a library (e.g. an soname bump leaving both .409 and
+#    .410 behind) and we would ship a library set nobody reviewed. Require the
+#    shipped names to be exactly the tracked set, and fail loudly otherwise.
+staged_libs=$(cd "$STAGE/server/dl_lib" && ls -1 | LC_ALL=C sort)
+tracked_libs=$(cd "$ROOT/server/dl_lib" && ls -1 | LC_ALL=C sort)
+if [ "$staged_libs" != "$tracked_libs" ]; then
+    echo "[ERROR] shipped server/dl_lib does not match the tracked library set" >&2
+    echo "        unexpected (in package, not tracked):" >&2
+    comm -23 <(printf '%s\n' "$staged_libs") <(printf '%s\n' "$tracked_libs") \
+        | sed 's/^/          + /' >&2
+    echo "        absent (tracked, not in package):" >&2
+    comm -13 <(printf '%s\n' "$staged_libs") <(printf '%s\n' "$tracked_libs") \
+        | sed 's/^/          - /' >&2
+    echo "        if this change is intended, update server/dl_lib/ to match." >&2
+    exit 1
+fi
+
+#    A library arrives either from the SDK dist (mode 755) or from the tracked
+#    backfill (git stores them 644), so without this the archive would depend on
+#    which path populated each file. 644 is what published releases have always
+#    carried, and install.go chmods the installed tree to 0755 anyway.
+chmod 644 "$STAGE"/server/dl_lib/*
+
+# 5. Frontend. router.go serves <dir of executable>/web.
+rm -rf "$STAGE/server/web"
+mkdir -p "$STAGE/server/web"
+cp -a "$ROOT/web/dist/." "$STAGE/server/web/"
+
+# 6. EDID helper shipped under system/tool/ (prebuilt riscv64 binary in tools/).
+mkdir -p "$STAGE/system/tool"
+cp -a "$ROOT/tools/nanokvm_update_edid/nanokvm_update_edid" "$STAGE/system/tool/"
+cp -a "$ROOT/tools/nanokvm_update_edid/E21_NanoKVM.bin" "$STAGE/system/tool/"
+
+# 7. Default runtime state read by common.GetScreen() on first boot.
+mkdir -p "$STAGE/kvm"
+printf '30\n'    > "$STAGE/kvm/fps"
+printf '0\n'     > "$STAGE/kvm/now_fps"
+printf '60\n'    > "$STAGE/kvm/qlty"
+printf '1920\n'  > "$STAGE/kvm/width"
+printf '1080\n'  > "$STAGE/kvm/height"
+printf '0\n'     > "$STAGE/kvm/state"
+printf 'mjpeg\n' > "$STAGE/kvm/type"
+printf '0'       > "$STAGE/kvm/res"
+
+# 8. Directories the released package has always carried, kept so the layout
+#    matches previous releases exactly (system_init.cpp probes inside them).
+mkdir -p "$STAGE/jpg_stream/dl_lib" "$STAGE/kvm_system/dl_lib"
+
+# --- archive -----------------------------------------------------------------
+# Normalise owner and timestamps so the same source tree yields the same
+# tarball, which makes the published sha512 verifiable after the fact.
+SOURCE_DATE_EPOCH="${SOURCE_DATE_EPOCH:-$(git -C "$ROOT" log -1 --format=%ct 2>/dev/null || echo 0)}"
+
+find "$STAGE" -exec touch -d "@$SOURCE_DATE_EPOCH" {} + 2>/dev/null \
+    || find "$STAGE" -exec touch -t "$(date -r "$SOURCE_DATE_EPOCH" +%Y%m%d%H%M.%S)" {} + 2>/dev/null \
+    || echo "[WARN] could not normalise timestamps"
+
+echo "[INFO] creating $(basename "$TARBALL")"
+rm -f "$TARBALL"
+
+# Read the version into a variable first: piping through head can hand tar a
+# SIGPIPE, and under "set -o pipefail" that would silently select the bsdtar
+# branch on a GNU system, quietly losing reproducibility.
+tar_version="$(tar --version 2>/dev/null || true)"
+
+if [ "${tar_version#*GNU}" != "$tar_version" ]; then
+    tar --format=gnu --sort=name \
+        --owner=0 --group=0 --numeric-owner \
+        --mtime="@$SOURCE_DATE_EPOCH" \
+        -C "$OUT" -cf - "nanokvm_$VERSION" \
+        | gzip -n -9 > "$TARBALL"
+else
+    # bsdtar (macOS): no --sort/--mtime, so the archive is not byte-reproducible.
+    echo "[WARN] GNU tar not found; archive will not be byte-reproducible"
+    tar --uid 0 --gid 0 --uname '' --gname '' \
+        -C "$OUT" -cf - "nanokvm_$VERSION" \
+        | gzip -n -9 > "$TARBALL"
+fi
+
+# --- manifest ----------------------------------------------------------------
+# update.go compares base64(raw sha512), not the hex digest.
+SHA512="$(openssl dgst -sha512 -binary "$TARBALL" | openssl base64 -A)"
+SIZE_BYTES="$(wc -c < "$TARBALL" | tr -d ' ')"
+UNPACKED_SIZE_BYTES="$(python3 - "$TARBALL" <<'PY'
+import sys
+import tarfile
+
+total = 0
+with tarfile.open(sys.argv[1], "r:gz") as archive:
+    for member in archive:
+        if member.isfile():
+            total += member.size
+print(total)
+PY
+)"
+
+cat > "$MANIFEST" <<EOF
+{
+  "manifest_version": 2,
+  "version": "$VERSION",
+  "name": "nanokvm_$VERSION.tar.gz",
+  "sha512": "$SHA512",
+  "size": $SIZE_BYTES,
+  "size_bytes": $SIZE_BYTES,
+  "unpacked_size_bytes": $UNPACKED_SIZE_BYTES
+}
+EOF
+
+echo
+echo "[DONE] $TARBALL"
+echo "[DONE] $MANIFEST"
+cat "$MANIFEST"

scripts/verify-release-assets.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+# Verify the three assets that make up a NanoKVM GitHub release.
+
+set -euo pipefail
+
+ASSET_DIR="${1:-}"
+VERSION="${2:-}"
+
+if [ -z "$ASSET_DIR" ] || [ -z "$VERSION" ]; then
+    echo "Usage: $0 <asset-directory> <version>" >&2
+    exit 1
+fi
+if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+    echo "[ERROR] invalid version '$VERSION', expected MAJOR.MINOR.PATCH" >&2
+    exit 1
+fi
+
+TARBALL_NAME="nanokvm_${VERSION}.tar.gz"
+TARBALL="$ASSET_DIR/$TARBALL_NAME"
+MANIFEST="$ASSET_DIR/latest.json"
+CHECKSUM="$ASSET_DIR/sha256.txt"
+
+for path in "$TARBALL" "$MANIFEST" "$CHECKSUM"; do
+    if [ ! -f "$path" ]; then
+        echo "[ERROR] missing release asset: $path" >&2
+        exit 1
+    fi
+done
+
+PACKAGE_ROOT="nanokvm_${VERSION}"
+MAX_PACKAGE_SIZE=$((1 << 30))
+MAX_UNPACKED_SIZE=$((2 << 30))
+MAX_ARCHIVE_ENTRIES=100000
+ENTRY_LIST=$(mktemp)
+VERBOSE_LIST=$(mktemp)
+trap 'rm -f "$ENTRY_LIST" "$VERBOSE_LIST"' EXIT
+
+if ! tar -tzf "$TARBALL" > "$ENTRY_LIST"; then
+    echo "[ERROR] could not list release tarball" >&2
+    exit 1
+fi
+if ! tar -tvzf "$TARBALL" > "$VERBOSE_LIST"; then
+    echo "[ERROR] could not inspect release tarball entry types" >&2
+    exit 1
+fi
+
+ENTRY_COUNT=0
+while IFS= read -r entry; do
+    ENTRY_COUNT=$((ENTRY_COUNT + 1))
+    if [ "$ENTRY_COUNT" -gt "$MAX_ARCHIVE_ENTRIES" ]; then
+        echo "[ERROR] archive contains more than $MAX_ARCHIVE_ENTRIES entries" >&2
+        exit 1
+    fi
+    case "$entry" in
+        "$PACKAGE_ROOT"|"$PACKAGE_ROOT"/*) ;;
+        *)
+            echo "[ERROR] archive entry is outside $PACKAGE_ROOT/: $entry" >&2
+            exit 1
+            ;;
+    esac
+    case "/$entry/" in
+        */../*|*/./*)
+            echo "[ERROR] archive entry contains an unsafe path component: $entry" >&2
+            exit 1
+            ;;
+    esac
+done < "$ENTRY_LIST"
+if [ "$ENTRY_COUNT" -eq 0 ]; then
+    echo "[ERROR] release tarball is empty" >&2
+    exit 1
+fi
+
+while IFS= read -r verbose_entry; do
+    entry_type=${verbose_entry:0:1}
+    case "$entry_type" in
+        -|d) ;;
+        *)
+            echo "[ERROR] archive contains a link or special entry: $verbose_entry" >&2
+            exit 1
+            ;;
+    esac
+done < "$VERBOSE_LIST"
+
+ARCHIVE_VERSION=$(tar -xOzf "$TARBALL" "$PACKAGE_ROOT/version" 2>/dev/null) || {
+    echo "[ERROR] release tarball does not contain $PACKAGE_ROOT/version" >&2
+    exit 1
+}
+if [ "$ARCHIVE_VERSION" != "$VERSION" ]; then
+    echo "[ERROR] archive version '$ARCHIVE_VERSION' does not match '$VERSION'" >&2
+    exit 1
+fi
+
+SHA256=$(sha256sum "$TARBALL" | cut -d' ' -f1)
+if ! printf '%s  %s\n' "$SHA256" "$TARBALL_NAME" | cmp -s - "$CHECKSUM"; then
+    echo "[ERROR] sha256.txt does not match $TARBALL_NAME" >&2
+    exit 1
+fi
+
+MANIFEST_VERSION=$(jq -er '.version | select(type == "string" and length > 0)' "$MANIFEST")
+MANIFEST_NAME=$(jq -er '.name | select(type == "string" and length > 0)' "$MANIFEST")
+MANIFEST_SIZE=$(jq -er '.size | select(type == "number" and . >= 0 and floor == .)' "$MANIFEST")
+MANIFEST_FORMAT=$(jq -er '.manifest_version | select(type == "number" and . == 2)' "$MANIFEST")
+MANIFEST_SIZE_BYTES=$(jq -er '.size_bytes | select(type == "number" and . > 0 and floor == .)' "$MANIFEST")
+MANIFEST_UNPACKED_SIZE_BYTES=$(jq -er '.unpacked_size_bytes | select(type == "number" and . > 0 and floor == .)' "$MANIFEST")
+MANIFEST_SHA512=$(jq -er '.sha512 | select(type == "string" and length > 0)' "$MANIFEST")
+
+if [ "$MANIFEST_VERSION" != "$VERSION" ]; then
+    echo "[ERROR] latest.json version '$MANIFEST_VERSION' does not match '$VERSION'" >&2
+    exit 1
+fi
+if [ "$MANIFEST_NAME" != "$TARBALL_NAME" ]; then
+    echo "[ERROR] latest.json name '$MANIFEST_NAME' does not match '$TARBALL_NAME'" >&2
+    exit 1
+fi
+
+ACTUAL_SIZE=$(wc -c < "$TARBALL" | tr -d ' ')
+if [ "$MANIFEST_FORMAT" != "2" ]; then
+    echo "[ERROR] latest.json manifest_version must be 2" >&2
+    exit 1
+fi
+if [ "$MANIFEST_SIZE" != "$ACTUAL_SIZE" ] || [ "$MANIFEST_SIZE_BYTES" != "$ACTUAL_SIZE" ]; then
+    echo "[ERROR] latest.json size '$MANIFEST_SIZE' does not match '$ACTUAL_SIZE'" >&2
+    exit 1
+fi
+if [ "$ACTUAL_SIZE" -gt "$MAX_PACKAGE_SIZE" ]; then
+    echo "[ERROR] release tarball exceeds device limit of $MAX_PACKAGE_SIZE bytes" >&2
+    exit 1
+fi
+
+ACTUAL_UNPACKED_SIZE=$(python3 - "$TARBALL" <<'PY'
+import sys
+import tarfile
+
+total = 0
+with tarfile.open(sys.argv[1], "r:gz") as archive:
+    for member in archive:
+        if member.isfile():
+            total += member.size
+print(total)
+PY
+)
+if [ "$MANIFEST_UNPACKED_SIZE_BYTES" != "$ACTUAL_UNPACKED_SIZE" ]; then
+    echo "[ERROR] latest.json unpacked_size_bytes '$MANIFEST_UNPACKED_SIZE_BYTES' does not match '$ACTUAL_UNPACKED_SIZE'" >&2
+    exit 1
+fi
+if [ "$ACTUAL_UNPACKED_SIZE" -gt "$MAX_UNPACKED_SIZE" ]; then
+    echo "[ERROR] unpacked package exceeds device limit of $MAX_UNPACKED_SIZE bytes" >&2
+    exit 1
+fi
+
+ACTUAL_SHA512=$(openssl dgst -sha512 -binary "$TARBALL" | openssl base64 -A)
+if [ "$MANIFEST_SHA512" != "$ACTUAL_SHA512" ]; then
+    echo "[ERROR] latest.json sha512 does not match $TARBALL_NAME" >&2
+    exit 1
+fi
+
+echo "[OK] verified NanoKVM release assets for $VERSION"

scripts/verify-release-tag.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Resolve an annotated numeric tag from origin and verify its commit is on main.
+
+set -euo pipefail
+
+TAG="${1:-}"
+EXPECTED_SHA="${2:-}"
+
+if ! echo "$TAG" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+    echo "[ERROR] invalid tag '$TAG', expected MAJOR.MINOR.PATCH" >&2
+    exit 1
+fi
+if [ -n "$EXPECTED_SHA" ] && ! echo "$EXPECTED_SHA" | grep -qE '^[0-9a-f]{40}$'; then
+    echo "[ERROR] expected commit must be a full lowercase commit SHA" >&2
+    exit 1
+fi
+
+TAG_REF="refs/tags/$TAG"
+PEELED_REF="${TAG_REF}^{}"
+REMOTE_REFS=$(git ls-remote --tags origin "$TAG_REF" "$PEELED_REF")
+TAG_OBJECT=$(printf '%s\n' "$REMOTE_REFS" | awk -v ref="$TAG_REF" '$2 == ref { print $1 }')
+SOURCE_SHA=$(printf '%s\n' "$REMOTE_REFS" | awk -v ref="$PEELED_REF" '$2 == ref { print $1 }')
+
+if ! echo "$TAG_OBJECT" | grep -qE '^[0-9a-f]{40}$'; then
+    echo "[ERROR] tag '$TAG' does not exist on origin" >&2
+    exit 1
+fi
+if ! echo "$SOURCE_SHA" | grep -qE '^[0-9a-f]{40}$'; then
+    echo "[ERROR] tag '$TAG' is not an annotated tag" >&2
+    exit 1
+fi
+if [ -n "$EXPECTED_SHA" ] && [ "$SOURCE_SHA" != "$EXPECTED_SHA" ]; then
+    echo "[ERROR] tag '$TAG' moved from '$EXPECTED_SHA' to '$SOURCE_SHA'" >&2
+    exit 1
+fi
+
+git fetch --no-tags origin main
+if ! git merge-base --is-ancestor "$SOURCE_SHA" FETCH_HEAD; then
+    echo "[ERROR] tag '$TAG' points to a commit outside origin/main" >&2
+    exit 1
+fi
+
+printf '%s\n' "$SOURCE_SHA"

server/README.md

@@ -26,46 +26,67 @@ server
 The configuration file path is `/etc/kvm/server.yaml`.
 
 ```yaml
-proto: http
+# Network Settings
+proto: http            # Access protocol. Can be changed to `https` only when certificates are configured. Default is `http`
+host: ""               # The listening address for the HTTP/HTTPS service. If left empty, all network interfaces will be bound
 port:
-    http: 80
-    https: 443
+    http: 80           # The listening port for the HTTP service. Default is `80`
+    https: 443         # The listening port for the HTTPS service (effective when HTTPS is enabled). Default is `443`
 cert:
-    crt: server.crt
-    key: server.key
+    crt: server.crt    # The path to the public key certificate for HTTPS
+    key: server.key    # The path to the private key file for HTTPS
 
-# Log level (debug/info/warn/error)
-# Note: Use 'info' or 'error' in production, 'debug' only for development
+
+# Logging Configuration
 logger:
-    level: info
-    file: stdout
+    level: info     # Global log output level. Evaluated options from highest to lowest detail: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`. Default is `info`
+    file: stdout    # Log output destination. `stdout` outputs to the standard console. A file path directs log output to that file. Default is `stdout`
 
-# Authentication setting (enable/disable)
-# Note: Only disable authentication in development environment
-authentication: enable
 
+# Authentication & Security
+authentication: enable              # Whether to enable identity verification for HTTP API and Web endpoints. Options are `enable` or `disable`. Default is `enable`. Highly recommended to leave this enabled for internet-facing devices!
 jwt:
-   # JWT secret key. If left empty, a random 64-byte key will be generated automatically.
-   secretKey: ""
-   # JWT token expiration time in seconds. Default: 2678400 (31 days)
-   refreshTokenDuration: 2678400
-   # Invalidate all JWT tokens when the user logs out. Default: true
-   revokeTokensOnLogout: true
+   secretKey: ""                    # The secret key used to sign and verify JWT Tokens. If left empty, a random key will be generated automatically on startup
+   refreshTokenDuration: 2678400    # The token refresh duration threshold in seconds before forcing a re-login. Default is `2678400` (~31 days)
+   revokeTokensOnLogout: true       # Whether logout invalidates all sessions belonging to that user. Other users are never logged out. Setting this to false only clears the browser cookie and is not recommended. Default is `true`
+security:
+   loginLockoutDuration: 0,         # The duration (in seconds) to ban an IP from attempting to log in again after reaching the failure limit. If set to `0` or left empty, brute-force protection is disabled. Default is `0`
+   loginMaxFailures:     5,         # The maximum number of continuous failed login attempts allowed per IP before triggering protection. Default is `5`
 
-# Address for custom STUN server
-# Note: You can disable the STUN service by setting it to 'disable' (e.g., in a LAN environment)
-stun: stun.l.google.com:19302
 
-# Address and authentication for custom TURN server
+# WebRTC Traversal Settings
+stun: stun.l.google.com:19302 # The default STUN server address used for NAT hole-punching to establish P2P streams
 turn:
-    turnAddr: example_addr
-    turnUser: example_user
-    turnCred: example_cred
+    turnAddr: example_addr    # The relay (TURN) server address (format `ip:port`) used as a fallback when P2P connection fails. Leave empty to disable TURN relay
+    turnUser: example_user    # The username required for authorization to the TURN server
+    turnCred: example_cred    # The credential/password required for authorization to the TURN server
 ```
 
+## Web Users
+
+NanoKVM uses two device-wide roles:
+
+- `admin`: KVM access plus user, system, network, update, storage, terminal, script, MCP, and PicoClaw administration.
+- `user`: KVM video, keyboard, mouse, paste, power/reset, and Wake-on-LAN access.
+
+Administrators manage accounts from **Settings > Account**. Account data remains in
+`/etc/kvm/pwd`; the server migrates the legacy single-account JSON format in place and writes
+the multi-user format atomically with mode `0600`. Keeping the same path preserves the physical
+BOOT-button password reset behavior.
+Users must confirm their current password when changing it themselves; administrators can reset
+non-owner users from the account manager. Only the device owner can change the device owner's
+password, because that password is also synchronized to the Linux root account.
+
+All authenticated sessions are backed by the current account state. Disabling, deleting,
+changing the role or password of a user invalidates that user's HTTP and real-time connections
+without affecting other users. Multiple users may watch and control the KVM concurrently; input
+uses the existing cooperative HID coordinator, so simultaneous input can interleave.
+Video mode, quality, resolution, and MJPEG frame-detection controls remain shared KVM
+operations; when several users adjust them concurrently, the latest change applies device-wide.
+
 ## Compile & Deploy
 
-Note: Use Linux operating system (x86-64). This build process is not compatible with ARM, Windows or macOS.
+Note: The manual steps below require a Linux x86-64 host with Go 1.25 or newer; they are not compatible with ARM, Windows or macOS. With Docker you can skip them entirely and use the containerized flow instead — the root [Makefile](../Makefile) (`make shell`) or the dev container (see "Development" in the root [README](../README.md)) — which works on any host OS; run `server/build.sh` inside the container for a release-equivalent build.
 
 1. Install the Toolchain
     1. Download the toolchain from the following link: [Download Link](https://sophon-file.sophon.cn/sophon-prod-s3/drive/23/03/07/16/host-tools.tar.gz).

server/README_JA.md

@@ -27,6 +27,7 @@ server
 
 ```yaml
 proto: http
+host: ""
 port:
     http: 80
     https: 443
@@ -64,7 +65,7 @@ turn:
 
 ## コンパイルとデプロイ
 
-注意: Linux オペレーティングシステム (x86-64) を使用してください。このビルドプロセスは ARM、Windows、macOS では互換性がありません。
+注意: Linux オペレーティングシステム (x86-64) と Go 1.25 以降を使用してください。このビルドプロセスは ARM、Windows、macOS では互換性がありません。
 
 1. ツールチェーンのインストール
     1. 以下のリンクからツールチェーンをダウンロードします: [ダウンロードリンク](https://sophon-file.sophon.cn/sophon-prod-s3/drive/23/03/07/16/host-tools.tar.gz)。

server/README_ZH.md

@@ -24,45 +24,61 @@ server
 配置文件路径为 `/etc/kvm/server.yaml`。
 
 ```yaml
-proto: http
+# 网络设置
+proto: http            # 访问协议，默认为 `http`，仅当配置了证书时支持改为 `https`
+host: ""
 port:
-    http: 80
-    https: 443
+    http: 80           # HTTP 服务的监听端口，默认为 `80`
+    https: 443         # HTTPS 服务的监听端口（启用 https 协议时生效），默认为 `443`
 cert:
-    crt: server.crt
-    key: server.key
+    crt: server.crt    # HTTPS 服务使用的公钥证书路径
+    key: server.key    # HTTPS 服务使用的私钥文件路径
 
-# 日志级别（debug/info/warn/error）
-# 注意：在生产环境中使用 info 或 error。debug 模式仅在开发环境中使用。
+
+# 日志配置
 logger:
-    level: info
-    file: stdout
+    level: info     # 全局日志打印级别，从高到底可选 `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`。默认为 `info`
+    file: stdout    # 日志输出目标位置。若填写 `stdout` 则输出在控制台。配置为文件路径则会输出到对应的文件。默认为 `stdout`
 
-# 鉴权设置（enable/disable）
-# 注意：生产环境中请勿使用 disable。
-authentication: enable
 
+# 认证与安全
+authentication: enable              # 是否开启 HTTP 接口与网页的身份校验。可选 `enable` (开启) 或 `disable` (禁用)。默认为 `enable`。强烈建议公开在互联网的机器开启此项！
 jwt:
-   # jwt 密钥。设置为空则使用随机生成的64位密钥
-   secretKey: ""
-   # jwt token 过期时间（单位：秒），默认为2678400（31天）
-   refreshTokenDuration: 2678400
-   # 在帐号登出时是否使所有 jwt token 失效。默认为 true
-   revokeTokensOnLogout: true
+   secretKey: ""                    # 用于签发和验证 JWT Token 的密钥。如果不填，服务启动时将自动随机生成
+   refreshTokenDuration: 2678400    # 登录超时的刷新周期（单位：秒）。默认为 `2678400`（约31天）
+   revokeTokensOnLogout: true       # 退出登录时是否废除该用户的全部会话；不会影响其他用户。设为 false 时仅清除浏览器 Cookie，不推荐使用。默认为 `true`
+security:
+   loginLockoutDuration: 0,         # 达到失败上限后，禁止该 IP 再次尝试登录的持续时间（单位：秒）。如果设为 `0` 或不填，则代表不开启防暴力破解功能。默认为 `0`
+   loginMaxFailures:     5,         # 允许触发保护前，单个 IP 连续登录失败的最大次数。默认为 `5`
 
-# 自定义 STUN 服务器的地址
-# 注意：可以设置为“disable”来禁用 STUN 服务（例如在局域网环境中使用时）
-stun: stun.l.google.com:19302
 
+# WebRTC 内网穿透
+stun: stun.l.google.com:19302    # 默认使用的 STUN 服务器地址，用于打洞获取公网 IP 建立 P2P 流
 turn:
-    turnAddr: example_addr
-    turnUser: example_user
-    turnCred: example_cred
+    turnAddr: example_addr       # 当 P2P 直连失败时，作为备用的中继（TURN）服务器地址（格式如 `ip:port`）。留空表示不使用 TURN 中继
+    turnUser: example_user       # TURN 服务器授权连接时使用的用户名
+    turnCred: example_cred       # TURN 服务器授权连接时使用的凭据/密码
 ```
 
+## Web 多用户
+
+NanoKVM 使用两种设备级角色：
+
+- `admin`：除 KVM 操作外，还可管理用户、系统、网络、更新、存储、终端、脚本、MCP 和 PicoClaw。
+- `user`：可使用 KVM 视频、键盘、鼠标、粘贴、目标机电源/复位和网络唤醒。
+
+管理员可在**设置 > 账户**中管理用户。账户数据继续保存在 `/etc/kvm/pwd`；服务会原地迁移旧版单账户
+JSON，并以 `0600` 权限原子写入多用户格式。沿用同一路径可保持长按 BOOT 键重置密码的现有行为。
+用户自助修改密码时必须验证当前密码；管理员可在账户管理中重置非设备所有者的密码。由于设备所有者
+密码还会同步至 Linux root 账户，因此只有设备所有者本人可以修改自己的密码。
+
+所有登录会话都会校验当前账户状态。禁用、删除、修改角色或密码会立即撤销该用户的 HTTP 与实时连接，
+且不会影响其他用户。多个用户可同时观看和协作控制 KVM；输入沿用现有 HID 协调器，因此同时输入可能交错。
+视频模式、画质、分辨率和 MJPEG 帧检测仍属于共享 KVM 操作；多人同时调整时，以最后一次设备级修改为准。
+
 ## 编译部署
 
-**注意：请使用 Linux 操作系统（x86-64）。该工具链无法在 ARM、Windows 或 macOS 下使用。**
+**注意：请使用 Linux 操作系统（x86-64）和 Go 1.25 或更高版本。该工具链无法在 ARM、Windows 或 macOS 下使用。**
 
 1. 安装工具链
    1. 下载工具链：[下载地址](https://sophon-file.sophon.cn/sophon-prod-s3/drive/23/03/07/16/host-tools.tar.gz)；

server/authn/store.go

@@ -0,0 +1,616 @@
+package authn
+
+import (
+	"crypto/rand"
+	"encoding/binary"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sync"
+
+	"NanoKVM-Server/utils"
+
+	"golang.org/x/crypto/bcrypt"
+)
+
+const (
+	AccountFile        = "/etc/kvm/pwd"
+	currentFileVersion = 1
+	defaultUsername    = "admin"
+	defaultPassword    = "admin"
+)
+
+type Role string
+
+const (
+	RoleAdmin Role = "admin"
+	RoleUser  Role = "user"
+)
+
+var (
+	ErrUserNotFound     = errors.New("user not found")
+	ErrUserExists       = errors.New("username already exists")
+	ErrLastAdmin        = errors.New("at least one enabled admin is required")
+	ErrSelfModification = errors.New("administrators cannot disable or demote themselves")
+	ErrSelfDelete       = errors.New("administrators cannot delete themselves")
+	ErrSystemAccount    = errors.New("the device owner account must remain an enabled administrator")
+
+	usernamePattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.-]{0,31}$`)
+)
+
+type User struct {
+	Username           string `json:"username"`
+	PasswordHash       string `json:"password"`
+	Role               Role   `json:"role"`
+	Enabled            bool   `json:"enabled"`
+	TokenVersion       uint64 `json:"tokenVersion"`
+	MustChangePassword bool   `json:"mustChangePassword,omitempty"`
+	SystemAccount      bool   `json:"systemAccount,omitempty"`
+}
+
+type UserInfo struct {
+	Username      string `json:"username"`
+	Role          Role   `json:"role"`
+	Enabled       bool   `json:"enabled"`
+	SystemAccount bool   `json:"systemAccount,omitempty"`
+}
+
+type UserPatch struct {
+	Role    *Role
+	Enabled *bool
+}
+
+type database struct {
+	Version        int    `json:"version"`
+	Users          []User `json:"users"`
+	LegacyUsername string `json:"username,omitempty"`
+	LegacyPassword string `json:"password,omitempty"`
+}
+
+type legacyAccount struct {
+	Username string `json:"username"`
+	Password string `json:"password"`
+}
+
+type Store struct {
+	path  string
+	mutex sync.RWMutex
+}
+
+var DefaultStore = NewStore(AccountFile)
+
+func NewStore(path string) *Store {
+	return &Store{path: path}
+}
+
+func IsValidRole(role Role) bool {
+	return role == RoleAdmin || role == RoleUser
+}
+
+func ValidateUsername(username string) error {
+	if !usernamePattern.MatchString(username) {
+		return errors.New("username must be 1-32 characters and contain only letters, numbers, '.', '_' or '-'")
+	}
+	return nil
+}
+
+func ValidatePassword(password string) error {
+	length := len([]byte(password))
+	if length < 8 || length > 72 {
+		return errors.New("password must be between 8 and 72 bytes")
+	}
+	return nil
+}
+
+func (s *Store) List() ([]UserInfo, error) {
+	s.mutex.RLock()
+	defer s.mutex.RUnlock()
+
+	db, err := s.loadLocked(false)
+	if err != nil {
+		return nil, err
+	}
+
+	users := make([]UserInfo, 0, len(db.Users))
+	for _, user := range db.Users {
+		users = append(users, UserInfo{
+			Username:      user.Username,
+			Role:          user.Role,
+			Enabled:       user.Enabled,
+			SystemAccount: user.SystemAccount,
+		})
+	}
+	return users, nil
+}
+
+func (s *Store) Get(username string) (*User, error) {
+	s.mutex.RLock()
+	defer s.mutex.RUnlock()
+
+	db, err := s.loadLocked(false)
+	if err != nil {
+		return nil, err
+	}
+	return findUser(db.Users, username)
+}
+
+func (s *Store) Authenticate(username, password string) (*User, bool, error) {
+	s.mutex.Lock()
+	defer s.mutex.Unlock()
+
+	db, err := s.loadLocked(true)
+	if err != nil {
+		return nil, false, err
+	}
+	user, err := findUser(db.Users, username)
+	if err != nil || !user.Enabled {
+		return nil, false, nil
+	}
+
+	if bcrypt.CompareHashAndPassword([]byte(user.PasswordHash), []byte(password)) == nil {
+		return user, true, nil
+	}
+
+	// Older releases stored a reversibly encrypted password. Upgrade it after
+	// the first successful login so the compatibility path is not permanent.
+	legacyPassword, decodeErr := utils.DecodeDecrypt(user.PasswordHash)
+	if decodeErr != nil || legacyPassword != password {
+		return nil, false, nil
+	}
+
+	hash, hashErr := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
+	if hashErr != nil {
+		return nil, false, hashErr
+	}
+	for index := range db.Users {
+		if db.Users[index].Username == username {
+			db.Users[index].PasswordHash = string(hash)
+			if db.Users[index].TokenVersion == 0 {
+				db.Users[index].TokenVersion = 1
+			}
+			user = cloneUser(&db.Users[index])
+			break
+		}
+	}
+	if err = s.saveLocked(db); err != nil {
+		return nil, false, err
+	}
+	return user, true, nil
+}
+
+func (s *Store) ValidateToken(username string, tokenVersion uint64) (*User, error) {
+	user, err := s.Get(username)
+	if err != nil {
+		return nil, err
+	}
+	if !user.Enabled || user.TokenVersion != tokenVersion {
+		return nil, errors.New("session revoked")
+	}
+	return user, nil
+}
+
+func (s *Store) Create(username, password string, role Role) error {
+	if err := ValidateUsername(username); err != nil {
+		return err
+	}
+	if err := ValidatePassword(password); err != nil {
+		return err
+	}
+	if !IsValidRole(role) {
+		return errors.New("invalid role")
+	}
+
+	hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
+	if err != nil {
+		return err
+	}
+	tokenVersion, err := newTokenVersion()
+	if err != nil {
+		return err
+	}
+
+	s.mutex.Lock()
+	defer s.mutex.Unlock()
+	db, err := s.loadLocked(true)
+	if err != nil {
+		return err
+	}
+	if _, err = findUser(db.Users, username); err == nil {
+		return ErrUserExists
+	}
+	db.Users = append(db.Users, User{
+		Username:     username,
+		PasswordHash: string(hash),
+		Role:         role,
+		Enabled:      true,
+		TokenVersion: tokenVersion,
+	})
+	return s.saveLocked(db)
+}
+
+func (s *Store) Update(actor, username string, patch UserPatch) (*User, error) {
+	s.mutex.Lock()
+	defer s.mutex.Unlock()
+
+	db, err := s.loadLocked(true)
+	if err != nil {
+		return nil, err
+	}
+	index := userIndex(db.Users, username)
+	if index < 0 {
+		return nil, ErrUserNotFound
+	}
+	user := db.Users[index]
+
+	if patch.Role != nil && !IsValidRole(*patch.Role) {
+		return nil, errors.New("invalid role")
+	}
+	if actor == username && user.Role == RoleAdmin &&
+		((patch.Role != nil && *patch.Role != RoleAdmin) || (patch.Enabled != nil && !*patch.Enabled)) {
+		return nil, ErrSelfModification
+	}
+	if user.SystemAccount &&
+		((patch.Role != nil && *patch.Role != RoleAdmin) || (patch.Enabled != nil && !*patch.Enabled)) {
+		return nil, ErrSystemAccount
+	}
+
+	changed := false
+	if patch.Role != nil && user.Role != *patch.Role {
+		user.Role = *patch.Role
+		changed = true
+	}
+	if patch.Enabled != nil && user.Enabled != *patch.Enabled {
+		user.Enabled = *patch.Enabled
+		changed = true
+	}
+	if !changed {
+		return &user, nil
+	}
+
+	db.Users[index] = user
+	if enabledAdminCount(db.Users) == 0 {
+		return nil, ErrLastAdmin
+	}
+	db.Users[index].TokenVersion++
+	if err = s.saveLocked(db); err != nil {
+		return nil, err
+	}
+	return cloneUser(&db.Users[index]), nil
+}
+
+func (s *Store) Delete(actor, username string) error {
+	if actor == username {
+		return ErrSelfDelete
+	}
+
+	s.mutex.Lock()
+	defer s.mutex.Unlock()
+	db, err := s.loadLocked(true)
+	if err != nil {
+		return err
+	}
+	index := userIndex(db.Users, username)
+	if index < 0 {
+		return ErrUserNotFound
+	}
+	if db.Users[index].SystemAccount {
+		return ErrSystemAccount
+	}
+	users := append([]User(nil), db.Users[:index]...)
+	users = append(users, db.Users[index+1:]...)
+	if enabledAdminCount(users) == 0 {
+		return ErrLastAdmin
+	}
+	db.Users = users
+	return s.saveLocked(db)
+}
+
+func (s *Store) SetPassword(username, password string) (*User, error) {
+	return s.SetPasswordAndRun(username, password, nil)
+}
+
+// SetPasswordAndRun commits the web password before running the optional
+// system-side update. If that update fails, the account record is rolled back
+// while the store lock is still held.
+func (s *Store) SetPasswordAndRun(username, password string, afterCommit func() error) (*User, error) {
+	if err := ValidatePassword(password); err != nil {
+		return nil, err
+	}
+	hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
+	if err != nil {
+		return nil, err
+	}
+
+	s.mutex.Lock()
+	defer s.mutex.Unlock()
+	db, err := s.loadLocked(true)
+	if err != nil {
+		return nil, err
+	}
+	index := userIndex(db.Users, username)
+	if index < 0 {
+		return nil, ErrUserNotFound
+	}
+	previous := *db
+	previous.Users = append([]User(nil), db.Users...)
+	db.Users[index].PasswordHash = string(hash)
+	db.Users[index].MustChangePassword = false
+	db.Users[index].TokenVersion++
+	if err = s.saveLocked(db); err != nil {
+		return nil, err
+	}
+	if afterCommit != nil {
+		if err = afterCommit(); err != nil {
+			if rollbackErr := s.saveLocked(&previous); rollbackErr != nil {
+				return nil, fmt.Errorf("system password update failed: %v; account rollback failed: %w", err, rollbackErr)
+			}
+			return nil, err
+		}
+	}
+	return cloneUser(&db.Users[index]), nil
+}
+
+func (s *Store) Revoke(username string) (*User, error) {
+	s.mutex.Lock()
+	defer s.mutex.Unlock()
+	db, err := s.loadLocked(true)
+	if err != nil {
+		return nil, err
+	}
+	index := userIndex(db.Users, username)
+	if index < 0 {
+		return nil, ErrUserNotFound
+	}
+	db.Users[index].TokenVersion++
+	if err = s.saveLocked(db); err != nil {
+		return nil, err
+	}
+	return cloneUser(&db.Users[index]), nil
+}
+
+func (s *Store) loadLocked(migrate bool) (*database, error) {
+	data, err := os.ReadFile(s.path)
+	if errors.Is(err, os.ErrNotExist) {
+		db, defaultErr := defaultDatabase()
+		if defaultErr != nil {
+			return nil, defaultErr
+		}
+		if migrate {
+			if saveErr := s.saveLocked(db); saveErr != nil {
+				return nil, saveErr
+			}
+		}
+		return db, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	var db database
+	if err = json.Unmarshal(data, &db); err == nil && db.Version != 0 {
+		if err = validateDatabase(&db); err != nil {
+			return nil, err
+		}
+		return &db, nil
+	}
+
+	var legacy legacyAccount
+	if err = json.Unmarshal(data, &legacy); err != nil || legacy.Username == "" || legacy.Password == "" {
+		return nil, errors.New("invalid account file")
+	}
+	if err = ValidateUsername(legacy.Username); err != nil {
+		return nil, fmt.Errorf("invalid legacy username: %w", err)
+	}
+	tokenVersion, err := newTokenVersion()
+	if err != nil {
+		return nil, err
+	}
+	db = database{
+		Version: currentFileVersion,
+		Users: []User{{
+			Username:           legacy.Username,
+			PasswordHash:       legacy.Password,
+			Role:               RoleAdmin,
+			Enabled:            true,
+			TokenVersion:       tokenVersion,
+			MustChangePassword: passwordMatches(legacy.Password, defaultPassword),
+			SystemAccount:      true,
+		}},
+	}
+	if migrate {
+		if err = s.saveLocked(&db); err != nil {
+			return nil, err
+		}
+	}
+	return &db, nil
+}
+
+func (s *Store) saveLocked(db *database) error {
+	if err := validateDatabase(db); err != nil {
+		return err
+	}
+	syncLegacyAccount(db)
+	data, err := json.MarshalIndent(db, "", "  ")
+	if err != nil {
+		return err
+	}
+	data = append(data, '\n')
+
+	directory := filepath.Dir(s.path)
+	if err = os.MkdirAll(directory, 0o755); err != nil {
+		return err
+	}
+	temporary, err := os.CreateTemp(directory, ".pwd-*")
+	if err != nil {
+		return err
+	}
+	temporaryPath := temporary.Name()
+	defer func() { _ = os.Remove(temporaryPath) }()
+
+	if err = temporary.Chmod(0o600); err == nil {
+		_, err = temporary.Write(data)
+	}
+	if err == nil {
+		err = temporary.Sync()
+	}
+	closeErr := temporary.Close()
+	if err == nil {
+		err = closeErr
+	}
+	if err != nil {
+		return err
+	}
+	if err = os.Rename(temporaryPath, s.path); err != nil {
+		return err
+	}
+
+	dir, err := os.Open(directory)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = dir.Close() }()
+	return dir.Sync()
+}
+
+func defaultDatabase() (*database, error) {
+	hash, err := bcrypt.GenerateFromPassword([]byte(defaultPassword), bcrypt.DefaultCost)
+	if err != nil {
+		return nil, err
+	}
+	tokenVersion, err := newTokenVersion()
+	if err != nil {
+		return nil, err
+	}
+	return &database{
+		Version: currentFileVersion,
+		Users: []User{{
+			Username:           defaultUsername,
+			PasswordHash:       string(hash),
+			Role:               RoleAdmin,
+			Enabled:            true,
+			TokenVersion:       tokenVersion,
+			MustChangePassword: true,
+			SystemAccount:      true,
+		}},
+	}, nil
+}
+
+func newTokenVersion() (uint64, error) {
+	var data [8]byte
+	for {
+		if _, err := rand.Read(data[:]); err != nil {
+			return 0, err
+		}
+		version := binary.LittleEndian.Uint64(data[:])
+		if version != 0 && version != ^uint64(0) {
+			return version, nil
+		}
+	}
+}
+
+func validateDatabase(db *database) error {
+	if db.Version != currentFileVersion {
+		return fmt.Errorf("unsupported account file version: %d", db.Version)
+	}
+	if len(db.Users) == 0 {
+		return errors.New("account file contains no users")
+	}
+	seen := make(map[string]struct{}, len(db.Users))
+	systemAccounts := 0
+	for index := range db.Users {
+		user := &db.Users[index]
+		if err := ValidateUsername(user.Username); err != nil {
+			return err
+		}
+		if user.PasswordHash == "" || !IsValidRole(user.Role) {
+			return errors.New("account file contains an invalid user")
+		}
+		if _, exists := seen[user.Username]; exists {
+			return errors.New("account file contains duplicate usernames")
+		}
+		seen[user.Username] = struct{}{}
+		if user.TokenVersion == 0 {
+			user.TokenVersion = 1
+		}
+		if user.SystemAccount {
+			systemAccounts++
+			if user.Role != RoleAdmin || !user.Enabled || systemAccounts > 1 {
+				return ErrSystemAccount
+			}
+		}
+	}
+	if enabledAdminCount(db.Users) == 0 {
+		return ErrLastAdmin
+	}
+	return nil
+}
+
+func findUser(users []User, username string) (*User, error) {
+	index := userIndex(users, username)
+	if index < 0 {
+		return nil, ErrUserNotFound
+	}
+	return cloneUser(&users[index]), nil
+}
+
+func userIndex(users []User, username string) int {
+	for index := range users {
+		if users[index].Username == username {
+			return index
+		}
+	}
+	return -1
+}
+
+func enabledAdminCount(users []User) int {
+	count := 0
+	for _, user := range users {
+		if user.Role == RoleAdmin && user.Enabled {
+			count++
+		}
+	}
+	return count
+}
+
+func cloneUser(user *User) *User {
+	if user == nil {
+		return nil
+	}
+	copy := *user
+	return &copy
+}
+
+func passwordMatches(hash, password string) bool {
+	if bcrypt.CompareHashAndPassword([]byte(hash), []byte(password)) == nil {
+		return true
+	}
+	legacyPassword, err := utils.DecodeDecrypt(hash)
+	return err == nil && legacyPassword == password
+}
+
+// Keep a legacy top-level account mirror so downgrading to a single-user
+// server still authenticates the original device owner instead of failing
+// open or forcing an immediate physical reset.
+func syncLegacyAccount(db *database) {
+	db.LegacyUsername = ""
+	db.LegacyPassword = ""
+	var fallback *User
+	for _, user := range db.Users {
+		if user.SystemAccount {
+			db.LegacyUsername = user.Username
+			db.LegacyPassword = user.PasswordHash
+			return
+		}
+		if fallback == nil && user.Role == RoleAdmin && user.Enabled {
+			copy := user
+			fallback = &copy
+		}
+	}
+	if fallback != nil {
+		db.LegacyUsername = fallback.Username
+		db.LegacyPassword = fallback.PasswordHash
+	}
+}

server/authn/store_test.go

@@ -0,0 +1,212 @@
+package authn
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+
+	"golang.org/x/crypto/bcrypt"
+)
+
+func TestLegacyAccountMigratesInPlace(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "pwd")
+	hash, err := bcrypt.GenerateFromPassword([]byte("legacy-password"), bcrypt.MinCost)
+	if err != nil {
+		t.Fatal(err)
+	}
+	legacy, _ := json.Marshal(legacyAccount{Username: "owner", Password: string(hash)})
+	if err = os.WriteFile(path, legacy, 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	store := NewStore(path)
+	user, ok, err := store.Authenticate("owner", "legacy-password")
+	if err != nil || !ok {
+		t.Fatalf("authenticate migrated account: ok=%v err=%v", ok, err)
+	}
+	if user.Role != RoleAdmin || !user.SystemAccount || user.TokenVersion == 0 {
+		t.Fatalf("unexpected migrated user: %+v", user)
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var db database
+	if err = json.Unmarshal(data, &db); err != nil {
+		t.Fatalf("account file was not migrated: %v", err)
+	}
+	if db.Version != currentFileVersion || len(db.Users) != 1 {
+		t.Fatalf("unexpected database: %+v", db)
+	}
+	var downgrade legacyAccount
+	if err = json.Unmarshal(data, &downgrade); err != nil || downgrade.Username != "owner" || downgrade.Password == "" {
+		t.Fatalf("legacy downgrade mirror is invalid: %+v, %v", downgrade, err)
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Mode().Perm() != 0o600 {
+		t.Fatalf("account mode = %o, want 600", info.Mode().Perm())
+	}
+}
+
+func TestCorruptAccountFileFailsClosed(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "pwd")
+	if err := os.WriteFile(path, []byte("not json"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	_, ok, err := NewStore(path).Authenticate("admin", "admin")
+	if err == nil || ok {
+		t.Fatalf("corrupt file must fail closed: ok=%v err=%v", ok, err)
+	}
+}
+
+func TestUserLifecycleAndTokenRevocation(t *testing.T) {
+	store := NewStore(filepath.Join(t.TempDir(), "pwd"))
+	if _, ok, err := store.Authenticate("admin", "admin"); err != nil || !ok {
+		t.Fatalf("default login: ok=%v err=%v", ok, err)
+	}
+	if err := store.Create("alice", "correct-horse", RoleUser); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok, err := store.Authenticate("alice", "wrong-password"); err != nil || ok {
+		t.Fatalf("wrong password login: ok=%v err=%v", ok, err)
+	}
+	alice, err := store.Get("alice")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err = store.ValidateToken("alice", alice.TokenVersion); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = store.SetPassword("alice", "new-password"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = store.ValidateToken("alice", alice.TokenVersion); err == nil {
+		t.Fatal("old token stayed valid after password change")
+	}
+	if _, ok, err := store.Authenticate("alice", "new-password"); err != nil || !ok {
+		t.Fatalf("new password login: ok=%v err=%v", ok, err)
+	}
+
+	disabled := false
+	if _, err = store.Update("admin", "alice", UserPatch{Enabled: &disabled}); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok, err := store.Authenticate("alice", "new-password"); err != nil || ok {
+		t.Fatalf("disabled login: ok=%v err=%v", ok, err)
+	}
+	enabled := true
+	if _, err = store.Update("admin", "alice", UserPatch{Enabled: &enabled}); err != nil {
+		t.Fatal(err)
+	}
+	if err = store.Delete("admin", "alice"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = store.Get("alice"); !errors.Is(err, ErrUserNotFound) {
+		t.Fatalf("deleted user lookup error = %v", err)
+	}
+}
+
+func TestLastAdminAndSelfProtection(t *testing.T) {
+	store := NewStore(filepath.Join(t.TempDir(), "pwd"))
+	if _, ok, err := store.Authenticate("admin", "admin"); err != nil || !ok {
+		t.Fatalf("default login: ok=%v err=%v", ok, err)
+	}
+	userRole := RoleUser
+	if _, err := store.Update("admin", "admin", UserPatch{Role: &userRole}); !errors.Is(err, ErrSelfModification) {
+		t.Fatalf("self demotion error = %v", err)
+	}
+	if err := store.Delete("admin", "admin"); !errors.Is(err, ErrSelfDelete) {
+		t.Fatalf("self delete error = %v", err)
+	}
+	if err := store.Create("second", "second-password", RoleAdmin); err != nil {
+		t.Fatal(err)
+	}
+	disabled := false
+	if _, err := store.Update("second", "admin", UserPatch{Enabled: &disabled}); !errors.Is(err, ErrSystemAccount) {
+		t.Fatalf("disable device owner error = %v", err)
+	}
+	if _, err := store.Update("second", "admin", UserPatch{Role: &userRole}); !errors.Is(err, ErrSystemAccount) {
+		t.Fatalf("demote device owner error = %v", err)
+	}
+	if err := store.Delete("second", "admin"); !errors.Is(err, ErrSystemAccount) {
+		t.Fatalf("delete device owner error = %v", err)
+	}
+	if err := store.Delete("admin", "second"); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRemovedAccountFileAndRecreatedUserInvalidateOldVersions(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "pwd")
+	store := NewStore(path)
+	admin, ok, err := store.Authenticate("admin", "admin")
+	if err != nil || !ok {
+		t.Fatalf("default login: ok=%v err=%v", ok, err)
+	}
+	if err = os.Remove(path); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = store.ValidateToken("admin", admin.TokenVersion); err == nil {
+		t.Fatal("old admin token survived account-file reset")
+	}
+
+	if _, ok, err = store.Authenticate("admin", "admin"); err != nil || !ok {
+		t.Fatalf("login after reset: ok=%v err=%v", ok, err)
+	}
+	if err = store.Create("alice", "alice-password", RoleUser); err != nil {
+		t.Fatal(err)
+	}
+	alice, err := store.Get("alice")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = store.Delete("admin", "alice"); err != nil {
+		t.Fatal(err)
+	}
+	if err = store.Create("alice", "alice-password", RoleUser); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = store.ValidateToken("alice", alice.TokenVersion); err == nil {
+		t.Fatal("old token survived deletion and username reuse")
+	}
+}
+
+func TestConcurrentCreatesDoNotLoseUsers(t *testing.T) {
+	store := NewStore(filepath.Join(t.TempDir(), "pwd"))
+	if _, ok, err := store.Authenticate("admin", "admin"); err != nil || !ok {
+		t.Fatalf("default login: ok=%v err=%v", ok, err)
+	}
+
+	const count = 5
+	var workers sync.WaitGroup
+	errorsCh := make(chan error, count)
+	for index := 0; index < count; index++ {
+		workers.Add(1)
+		go func(index int) {
+			defer workers.Done()
+			errorsCh <- store.Create(fmt.Sprintf("user%d", index), "valid-password", RoleUser)
+		}(index)
+	}
+	workers.Wait()
+	close(errorsCh)
+	for err := range errorsCh {
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	users, err := store.List()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(users) != count+1 {
+		t.Fatalf("got %d users, want %d", len(users), count+1)
+	}
+}

server/common/kvm_vision.go

@@ -18,7 +18,10 @@ var (
 	kvmVisionOnce sync.Once
 )
 
-type KvmVision struct{}
+type KvmVision struct {
+	mutex  sync.RWMutex
+	closed bool
+}
 
 func GetKvmVision() *KvmVision {
 	kvmVisionOnce.Do(func() {
@@ -33,6 +36,12 @@ func GetKvmVision() *KvmVision {
 }
 
 func (k *KvmVision) ReadMjpeg(width uint16, height uint16, quality uint16) (data []byte, result int) {
+	k.mutex.RLock()
+	defer k.mutex.RUnlock()
+	if k.closed {
+		return nil, -1
+	}
+
 	var (
 		kvmData  *C.uint8_t
 		dataSize C.uint32_t
@@ -57,6 +66,12 @@ func (k *KvmVision) ReadMjpeg(width uint16, height uint16, quality uint16) (data
 }
 
 func (k *KvmVision) ReadH264(width uint16, height uint16, bitRate uint16) (data []byte, result int) {
+	k.mutex.RLock()
+	defer k.mutex.RUnlock()
+	if k.closed {
+		return nil, -1
+	}
+
 	var (
 		kvmData  *C.uint8_t
 		dataSize C.uint32_t
@@ -81,6 +96,12 @@ func (k *KvmVision) ReadH264(width uint16, height uint16, bitRate uint16) (data
 }
 
 func (k *KvmVision) SetHDMI(enable bool) int {
+	k.mutex.RLock()
+	defer k.mutex.RUnlock()
+	if k.closed {
+		return -1
+	}
+
 	hdmiEnable := C.uint8_t(0)
 	if enable {
 		hdmiEnable = C.uint8_t(1)
@@ -95,17 +116,46 @@ func (k *KvmVision) SetHDMI(enable bool) int {
 	return result
 }
 
+func (k *KvmVision) HasHDMISignal() bool {
+	k.mutex.RLock()
+	defer k.mutex.RUnlock()
+	if k.closed {
+		return false
+	}
+
+	return C.kvmv_hdmi_signal_active() != 0
+}
+
 func (k *KvmVision) SetGop(gop uint8) {
+	k.mutex.RLock()
+	defer k.mutex.RUnlock()
+	if k.closed {
+		return
+	}
+
 	_gop := C.uint8_t(gop)
 	C.set_h264_gop(_gop)
 }
 
 func (k *KvmVision) SetFrameDetect(frame uint8) {
+	k.mutex.RLock()
+	defer k.mutex.RUnlock()
+	if k.closed {
+		return
+	}
+
 	_frame := C.uint8_t(frame)
 	C.set_frame_detact(_frame)
 }
 
 func (k *KvmVision) Close() {
+	k.mutex.Lock()
+	defer k.mutex.Unlock()
+	if k.closed {
+		return
+	}
+
+	k.closed = true
 	C.kvmv_deinit()
 	log.Debugf("stop kvm vision...")
 }

server/config/default.go

@@ -2,6 +2,7 @@ package config
 
 var defaultConfig = &Config{
 	Proto: "http",
+	Host:  "",
 	Port: Port{
 		Http:  80,
 		Https: 443,
@@ -26,6 +27,10 @@ var defaultConfig = &Config{
 		TurnCred: "",
 	},
 	Authentication: "enable",
+	Security: Security{
+		LoginLockoutDuration: 0,
+		LoginMaxFailures:     5,
+	},
 }
 
 func checkDefaultValue() {

server/config/jwt.go

@@ -7,13 +7,6 @@ import (
 	"time"
 )
 
-// RegenerateSecretKey regenerate secret key when logout
-func RegenerateSecretKey() {
-	if instance.JWT.RevokeTokensOnLogout {
-		instance.JWT.SecretKey = generateRandomSecretKey()
-	}
-}
-
 // Generate random string for secret key.
 func generateRandomSecretKey() string {
 	b := make([]byte, 64)

server/config/picoclaw_internal.go

@@ -0,0 +1,61 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+)
+
+const (
+	PicoclawInternalTokenHeader = "X-NanoKVM-Internal-Token"
+	picoclawInternalTokenFile   = "/etc/kvm/.picoclaw_internal_token"
+)
+
+var picoclawInternalToken struct {
+	mu    sync.Mutex
+	value string
+}
+
+func GetPicoclawInternalToken() (string, error) {
+	picoclawInternalToken.mu.Lock()
+	defer picoclawInternalToken.mu.Unlock()
+
+	if picoclawInternalToken.value != "" {
+		return picoclawInternalToken.value, nil
+	}
+
+	if token, err := readPicoclawInternalToken(); err == nil {
+		if token != "" {
+			picoclawInternalToken.value = token
+			return token, nil
+		}
+	} else if !os.IsNotExist(err) {
+		return "", err
+	}
+
+	token := generateRandomSecretKey()
+	if err := os.MkdirAll(filepath.Dir(picoclawInternalTokenFile), 0o755); err != nil {
+		return "", err
+	}
+	if err := os.WriteFile(picoclawInternalTokenFile, []byte(token+"\n"), 0o600); err != nil {
+		return "", err
+	}
+
+	picoclawInternalToken.value = token
+	return token, nil
+}
+
+func EnsurePicoclawInternalToken() error {
+	_, err := GetPicoclawInternalToken()
+	return err
+}
+
+func readPicoclawInternalToken() (string, error) {
+	data, err := os.ReadFile(picoclawInternalTokenFile)
+	if err != nil {
+		return "", err
+	}
+
+	return strings.TrimSpace(string(data)), nil
+}

server/config/types.go

@@ -1,14 +1,16 @@
 package config
 
 type Config struct {
-	Proto          string `yaml:"proto"`
-	Port           Port   `yaml:"port"`
-	Cert           Cert   `yaml:"cert"`
-	Logger         Logger `yaml:"logger"`
-	Authentication string `yaml:"authentication"`
-	JWT            JWT    `yaml:"jwt"`
-	Stun           string `yaml:"stun"`
-	Turn           Turn   `yaml:"turn"`
+	Proto          string   `yaml:"proto"`
+	Host           string   `yaml:"host"`
+	Port           Port     `yaml:"port"`
+	Cert           Cert     `yaml:"cert"`
+	Logger         Logger   `yaml:"logger"`
+	Authentication string   `yaml:"authentication"`
+	JWT            JWT      `yaml:"jwt"`
+	Stun           string   `yaml:"stun"`
+	Turn           Turn     `yaml:"turn"`
+	Security       Security `yaml:"security"`
 
 	Hardware Hardware `yaml:"-"`
 }
@@ -40,6 +42,11 @@ type Turn struct {
 	TurnCred string `yaml:"turnCred"`
 }
 
+type Security struct {
+	LoginLockoutDuration int `yaml:"loginLockoutDuration"`
+	LoginMaxFailures     int `yaml:"loginMaxFailures"`
+}
+
 type Hardware struct {
 	Version      HWVersion `yaml:"-"`
 	GPIOReset    string    `yaml:"-"`

server/go.mod

@@ -1,16 +1,20 @@
 module NanoKVM-Server
 
-go 1.24.0
+go 1.25.0
 
 require (
 	github.com/creack/pty v1.1.24
 	github.com/gin-gonic/contrib v0.0.0-20240508051311-c1c6bf0061b0
 	github.com/gin-gonic/gin v1.10.0
 	github.com/go-playground/validator/v10 v10.20.0
-	github.com/golang-jwt/jwt/v5 v5.2.2
+	github.com/golang-jwt/jwt/v5 v5.3.1
+	github.com/google/jsonschema-go v0.4.3
+	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/mervick/aes-everywhere/go/aes256 v0.0.0-20240803013625-6759956693c0
-	github.com/pion/dtls/v3 v3.0.3
+	github.com/modelcontextprotocol/go-sdk v1.6.1
+	github.com/pion/dtls/v3 v3.1.2
+	github.com/pion/interceptor v0.1.39
 	github.com/pion/rtp v1.8.18
 	github.com/pion/webrtc/v4 v4.0.1
 	github.com/rs/cors/wrapper/gin v0.0.0-20240830163046-1084d89a1692
@@ -18,6 +22,7 @@ require (
 	github.com/spf13/viper v1.19.0
 	github.com/unrolled/secure v1.15.0
 	golang.org/x/crypto v0.45.0
+	golang.org/x/sys v0.41.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -32,7 +37,6 @@ require (
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/goccy/go-json v0.10.2 // indirect
-	github.com/google/uuid v1.6.0 // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.7 // indirect
@@ -45,8 +49,7 @@ require (
 	github.com/pelletier/go-toml/v2 v2.2.2 // indirect
 	github.com/pion/datachannel v1.5.9 // indirect
 	github.com/pion/ice/v4 v4.0.2 // indirect
-	github.com/pion/interceptor v0.1.39 // indirect
-	github.com/pion/logging v0.2.3 // indirect
+	github.com/pion/logging v0.2.4 // indirect
 	github.com/pion/mdns/v2 v2.0.7 // indirect
 	github.com/pion/randutil v0.1.0 // indirect
 	github.com/pion/rtcp v1.2.15 // indirect
@@ -55,10 +58,13 @@ require (
 	github.com/pion/srtp/v3 v3.0.4 // indirect
 	github.com/pion/stun/v3 v3.0.0 // indirect
 	github.com/pion/transport/v3 v3.0.7 // indirect
+	github.com/pion/transport/v4 v4.0.1 // indirect
 	github.com/pion/turn/v4 v4.0.0 // indirect
 	github.com/rs/cors v1.11.0 // indirect
 	github.com/sagikazarmark/locafero v0.4.0 // indirect
 	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
+	github.com/segmentio/asm v1.1.3 // indirect
+	github.com/segmentio/encoding v0.5.4 // indirect
 	github.com/sourcegraph/conc v0.3.0 // indirect
 	github.com/spf13/afero v1.11.0 // indirect
 	github.com/spf13/cast v1.6.0 // indirect
@@ -66,13 +72,14 @@ require (
 	github.com/subosito/gotenv v1.6.0 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.12 // indirect
-	github.com/wlynxg/anet v0.0.3 // indirect
+	github.com/wlynxg/anet v0.0.5 // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	go.uber.org/atomic v1.9.0 // indirect
 	go.uber.org/multierr v1.9.0 // indirect
 	golang.org/x/arch v0.8.0 // indirect
 	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
 	golang.org/x/net v0.47.0 // indirect
-	golang.org/x/sys v0.38.0 // indirect
+	golang.org/x/oauth2 v0.35.0 // indirect
 	golang.org/x/text v0.31.0 // indirect
 	google.golang.org/protobuf v1.34.1 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect

server/go.sum

@@ -34,11 +34,13 @@ github.com/go-playground/validator/v10 v10.20.0 h1:K9ISHbSaI0lyB2eWMPJo+kOS/FBEx
 github.com/go-playground/validator/v10 v10.20.0/go.mod h1:dbuPbCMFw/DrkbEynArYaCwl3amGuJotoKCe95atGMM=
 github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
 github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
-github.com/golang-jwt/jwt/v5 v5.2.2 h1:Rl4B7itRWVtYIHFrSNd7vhTiz9UpLdi6gZhZ3wEeDy8=
-github.com/golang-jwt/jwt/v5 v5.2.2/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
-github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
-github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+DQPd0=
+github.com/google/jsonschema-go v0.4.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
@@ -65,6 +67,8 @@ github.com/mervick/aes-everywhere/go/aes256 v0.0.0-20240803013625-6759956693c0 h
 github.com/mervick/aes-everywhere/go/aes256 v0.0.0-20240803013625-6759956693c0/go.mod h1:Eb5RMoo9kOQra/2uRiUTGP+LfNuM13Vqm7y7P34+KKo=
 github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
 github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/modelcontextprotocol/go-sdk v1.6.1 h1:0zOSupjKUxPKSocPT1Wtago+mUHU2/uZ4xSOY0FGReU=
+github.com/modelcontextprotocol/go-sdk v1.6.1/go.mod h1:kzm3kzFL1/+AziGOE0nUs3gvPoNxMCvkxokMkuFapXQ=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
@@ -74,14 +78,14 @@ github.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6
 github.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=
 github.com/pion/datachannel v1.5.9 h1:LpIWAOYPyDrXtU+BW7X0Yt/vGtYxtXQ8ql7dFfYUVZA=
 github.com/pion/datachannel v1.5.9/go.mod h1:kDUuk4CU4Uxp82NH4LQZbISULkX/HtzKa4P7ldf9izE=
-github.com/pion/dtls/v3 v3.0.3 h1:j5ajZbQwff7Z8k3pE3S+rQ4STvKvXUdKsi/07ka+OWM=
-github.com/pion/dtls/v3 v3.0.3/go.mod h1:weOTUyIV4z0bQaVzKe8kpaP17+us3yAuiQsEAG1STMU=
+github.com/pion/dtls/v3 v3.1.2 h1:gqEdOUXLtCGW+afsBLO0LtDD8GnuBBjEy6HRtyofZTc=
+github.com/pion/dtls/v3 v3.1.2/go.mod h1:Hw/igcX4pdY69z1Hgv5x7wJFrUkdgHwAn/Q/uo7YHRo=
 github.com/pion/ice/v4 v4.0.2 h1:1JhBRX8iQLi0+TfcavTjPjI6GO41MFn4CeTBX+Y9h5s=
 github.com/pion/ice/v4 v4.0.2/go.mod h1:DCdqyzgtsDNYN6/3U8044j3U7qsJ9KFJC92VnOWHvXg=
 github.com/pion/interceptor v0.1.39 h1:Y6k0bN9Y3Lg/Wb21JBWp480tohtns8ybJ037AGr9UuA=
 github.com/pion/interceptor v0.1.39/go.mod h1:Z6kqH7M/FYirg3frjGJ21VLSRJGBXB/KqaTIrdqnOic=
-github.com/pion/logging v0.2.3 h1:gHuf0zpoh1GW67Nr6Gj4cv5Z9ZscU7g/EaoC/Ke/igI=
-github.com/pion/logging v0.2.3/go.mod h1:z8YfknkquMe1csOrxK5kc+5/ZPAzMxbKLX5aXpbpC90=
+github.com/pion/logging v0.2.4 h1:tTew+7cmQ+Mc1pTBLKH2puKsOvhm32dROumOZ655zB8=
+github.com/pion/logging v0.2.4/go.mod h1:DffhXTKYdNZU+KtJ5pyQDjvOAh/GsNSyv1lbkFbe3so=
 github.com/pion/mdns/v2 v2.0.7 h1:c9kM8ewCgjslaAmicYMFQIde2H9/lrZpjBkN8VwoVtM=
 github.com/pion/mdns/v2 v2.0.7/go.mod h1:vAdSYNAT0Jy3Ru0zl2YiW3Rm/fJCwIeM0nToenfOJKA=
 github.com/pion/randutil v0.1.0 h1:CFG1UdESneORglEsnimhUjf33Rwjubwj6xfiOXBa3mA=
@@ -100,6 +104,8 @@ github.com/pion/stun/v3 v3.0.0 h1:4h1gwhWLWuZWOJIJR9s2ferRO+W3zA/b6ijOI6mKzUw=
 github.com/pion/stun/v3 v3.0.0/go.mod h1:HvCN8txt8mwi4FBvS3EmDghW6aQJ24T+y+1TKjB5jyU=
 github.com/pion/transport/v3 v3.0.7 h1:iRbMH05BzSNwhILHoBoAPxoB9xQgOaJk+591KC9P1o0=
 github.com/pion/transport/v3 v3.0.7/go.mod h1:YleKiTZ4vqNxVwh77Z0zytYi7rXHl7j6uPLGhhz9rwo=
+github.com/pion/transport/v4 v4.0.1 h1:sdROELU6BZ63Ab7FrOLn13M6YdJLY20wldXW2Cu2k8o=
+github.com/pion/transport/v4 v4.0.1/go.mod h1:nEuEA4AD5lPdcIegQDpVLgNoDGreqM/YqmEx3ovP4jM=
 github.com/pion/turn/v4 v4.0.0 h1:qxplo3Rxa9Yg1xXDxxH8xaqcyGUtbHYw4QSCvmFWvhM=
 github.com/pion/turn/v4 v4.0.0/go.mod h1:MuPDkm15nYSklKpN8vWJ9W2M0PlyQZqYt1McGuxG7mA=
 github.com/pion/webrtc/v4 v4.0.1 h1:6Unwc6JzoTsjxetcAIoWH81RUM4K5dBc1BbJGcF9WVE=
@@ -117,6 +123,10 @@ github.com/sagikazarmark/locafero v0.4.0 h1:HApY1R9zGo4DBgr7dqsTH/JJxLTTsOt7u6ke
 github.com/sagikazarmark/locafero v0.4.0/go.mod h1:Pe1W6UlPYUk/+wc/6KFhbORCfqzgYEpgQ3O5fPuL3H4=
 github.com/sagikazarmark/slog-shim v0.1.0 h1:diDBnUNK9N/354PgrxMywXnAwEr1QZcOr6gto+ugjYE=
 github.com/sagikazarmark/slog-shim v0.1.0/go.mod h1:SrcSrq8aKtyuqEI1uvTDTK1arOWRIczQRv+GVI1AkeQ=
+github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
+github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
+github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
+github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
 github.com/sourcegraph/conc v0.3.0 h1:OQTbbt6P72L20UqAkXXuLOj79LfEanQ+YQFNpLA9ySo=
@@ -140,8 +150,8 @@ github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO
 github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
-github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
-github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
@@ -150,8 +160,10 @@ github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65E
 github.com/ugorji/go/codec v1.2.12/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
 github.com/unrolled/secure v1.15.0 h1:q7x+pdp8jAHnbzxu6UheP8fRlG/rwYTb8TPuQ3rn9Og=
 github.com/unrolled/secure v1.15.0/go.mod h1:BmF5hyM6tXczk3MpQkFf1hpKSRqCyhqcbiQtiAF7+40=
-github.com/wlynxg/anet v0.0.3 h1:PvR53psxFXstc12jelG6f1Lv4MWqE0tI76/hHGjh9rg=
-github.com/wlynxg/anet v0.0.3/go.mod h1:eay5PRQr7fIVAMbTbchTnO9gG65Hg/uYGdc7mguHxoA=
+github.com/wlynxg/anet v0.0.5 h1:J3VJGi1gvo0JwZ/P1/Yc/8p63SoW98B5dHkYDmpgvvU=
+github.com/wlynxg/anet v0.0.5/go.mod h1:eay5PRQr7fIVAMbTbchTnO9gG65Hg/uYGdc7mguHxoA=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 go.uber.org/atomic v1.9.0 h1:ECmE8Bn/WFTYwEW/bpKD3M8VtR/zQVbavAoalC1PYyE=
 go.uber.org/atomic v1.9.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc=
 go.uber.org/multierr v1.9.0 h1:7fIwc/ZtS0q++VgcfqFDxSBZVv/Xo49/SYnDFupUwlI=
@@ -165,13 +177,17 @@ golang.org/x/exp v0.0.0-20230905200255-921286631fa9 h1:GoHiUyI/Tp2nVkLI2mCxVkOjs
 golang.org/x/exp v0.0.0-20230905200255-921286631fa9/go.mod h1:S2oDrQGGwySpoQPVqRShND87VCbxmc6bL1Yd2oYrm6k=
 golang.org/x/net v0.47.0 h1:Mx+4dIFzqraBXUugkia1OOvlD6LemFo1ALMHjrXDOhY=
 golang.org/x/net v0.47.0/go.mod h1:/jNxtkgq5yWUGYkaZGqo27cfGZ1c5Nen03aYrrKpVRU=
+golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
+golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
 golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
-golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
 golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
+golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
+golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
 google.golang.org/protobuf v1.34.1 h1:9ddQBjfCyZPOHPUiPxpYESBLc+T8P3E+Vo4IbKZgFWg=
 google.golang.org/protobuf v1.34.1/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

server/include/kvm_vision.h

@@ -66,6 +66,7 @@ void set_h264_gop(uint8_t _gop);
 void set_frame_detact(uint8_t _frame_detact);
 void kvmv_deinit();
 uint8_t kvmv_hdmi_control(uint8_t _en);
+uint8_t kvmv_hdmi_signal_active(void);
 
 #ifdef __cplusplus
 }

server/main.go

@@ -1,12 +1,10 @@
 package main
 
 import (
-	"fmt"
 	"log"
-	"net/http"
 	"os"
 	"os/signal"
-	"strings"
+	"strconv"
 	"syscall"
 	"time"
 
@@ -15,6 +13,7 @@ import (
 	"NanoKVM-Server/logger"
 	"NanoKVM-Server/middleware"
 	"NanoKVM-Server/router"
+	"NanoKVM-Server/service/vm"
 	"NanoKVM-Server/service/vm/jiggler"
 	"NanoKVM-Server/utils"
 
@@ -30,18 +29,22 @@ func main() {
 }
 
 func initialize() {
+	if err := config.EnsurePicoclawInternalToken(); err != nil {
+		log.Fatalf("failed to initialize picoclaw internal token: %v", err)
+	}
+
 	logger.Init()
 
 	// init screen parameters
 	_ = common.GetScreen()
 
 	// init HDMI
-	vision := common.GetKvmVision()
-	vision.SetHDMI(false)
+	vm.DisableHdmiCapture()
 	time.Sleep(10 * time.Millisecond)
 	if !utils.IsHdmiDisabled() {
-		vision.SetHDMI(true)
+		vm.EnableHdmiCapture()
 	}
+	vm.SetHdmiViewerCount(0)
 
 	// run mouse jiggler
 	jiggler.GetJiggler().Run()
@@ -69,46 +72,56 @@ func run() {
 
 	router.Init(r)
 
-	httpAddr := fmt.Sprintf(":%d", conf.Port.Http)
-	httpsAddr := fmt.Sprintf(":%d", conf.Port.Https)
+	httpAddr := utils.ListenAddr(conf.Host, strconv.Itoa(conf.Port.Http))
+	loopbackHTTPAddr := utils.ListenAddr("127.0.0.1", strconv.Itoa(conf.Port.Http))
+	needsLoopbackHTTP := utils.NeedsDedicatedLoopbackListener(conf.Host)
 
 	if conf.Proto == "https" {
+		httpsPortStr := strconv.Itoa(conf.Port.Https)
+
 		go func() {
-			r.Use(middleware.Tls())
-			err := r.RunTLS(httpsAddr, conf.Cert.Crt, conf.Cert.Key)
+			err := r.RunTLS(utils.ListenAddr(conf.Host, httpsPortStr), conf.Cert.Crt, conf.Cert.Key)
 			if err != nil {
 				panic("start https server failed")
 			}
 		}()
 
-		runRedirect(httpAddr, httpsAddr)
+		if needsLoopbackHTTP {
+			go func() {
+				if err := middleware.ListenAndServeLoopbackHTTPRedirect(
+					loopbackHTTPAddr,
+					httpsPortStr,
+					r,
+					router.LoopbackHTTPAllowedPaths()...,
+				); err != nil {
+					panic("start loopback http server failed")
+				}
+			}()
+		}
+
+		if err := middleware.ListenAndServeLoopbackHTTPRedirect(
+			httpAddr,
+			httpsPortStr,
+			r,
+			router.LoopbackHTTPAllowedPaths()...,
+		); err != nil {
+			panic("start http server failed")
+		}
 	} else {
+		if needsLoopbackHTTP {
+			go func() {
+				if err := r.Run(loopbackHTTPAddr); err != nil {
+					panic("start loopback http server failed")
+				}
+			}()
+		}
+
 		if err := r.Run(httpAddr); err != nil {
 			panic("start http server failed")
 		}
 	}
 }
 
-func runRedirect(httpPort string, httpsPort string) {
-	err := http.ListenAndServe(httpPort, http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
-		host := req.Host
-		if strings.Contains(host, httpPort) {
-			host = strings.Split(host, httpPort)[0]
-		}
-
-		targetURL := "https://" + host + req.URL.String()
-		if httpsPort != ":443" {
-			targetURL = "https://" + host + httpsPort + req.URL.String()
-		}
-
-		http.Redirect(w, req, targetURL, http.StatusTemporaryRedirect)
-	}))
-
-	if err != nil {
-		panic("start http server failed")
-	}
-}
-
 func dispose() {
 	common.GetKvmVision().Close()
 }

server/middleware/jwt.go

@@ -1,75 +1,205 @@
 package middleware
 
 import (
+	"context"
+	"errors"
 	"net/http"
 	"time"
 
+	"NanoKVM-Server/authn"
+	"NanoKVM-Server/config"
+
 	"github.com/gin-gonic/gin"
 	"github.com/golang-jwt/jwt/v5"
 	log "github.com/sirupsen/logrus"
-
-	"NanoKVM-Server/config"
 )
 
+const (
+	principalContextKey = "principal"
+	tokenContextKey     = "token"
+	CookieName          = "nano-kvm-token"
+	sessionRecheckDelay = 5 * time.Second
+)
+
+type Principal struct {
+	Username string
+	Role     authn.Role
+}
+
 type Token struct {
-	Username string `json:"username"`
+	Username     string `json:"username"`
+	TokenVersion uint64 `json:"tokenVersion"`
 	jwt.RegisteredClaims
 }
 
 func CheckToken() gin.HandlerFunc {
 	return func(c *gin.Context) {
-		conf := config.GetInstance()
+		principal, token, ok := authenticate(c)
+		if !ok {
+			abortUnauthorized(c)
+			return
+		}
 
-		if conf.Authentication == "disable" {
+		c.Set(principalContextKey, principal)
+		c.Set(tokenContextKey, token)
+		if token == nil || token.ExpiresAt == nil {
 			c.Next()
 			return
 		}
 
-		cookie, err := c.Cookie("nano-kvm-token")
-		if err == nil {
-			_, err = ParseJWT(cookie)
-			if err == nil {
-				c.Next()
-				return
-			}
-		}
+		requestContext, cancel := context.WithCancel(c.Request.Context())
+		c.Request = c.Request.WithContext(requestContext)
+		unregister := activeSessions.register(principal.Username, cancel)
+		timer := time.AfterFunc(time.Until(token.ExpiresAt.Time), cancel)
+		go watchSessionState(requestContext, cancel, principal.Username, token.TokenVersion, sessionRecheckDelay)
+		defer func() {
+			timer.Stop()
+			unregister()
+			cancel()
+		}()
 
-		c.JSON(http.StatusUnauthorized, "unauthorized")
-		c.Abort()
+		c.Next()
 	}
 }
 
-func GenerateJWT(username string) (string, error) {
+func watchSessionState(ctx context.Context, cancel context.CancelFunc, username string, tokenVersion uint64, interval time.Duration) {
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			if _, err := authn.DefaultStore.ValidateToken(username, tokenVersion); err != nil {
+				cancel()
+				return
+			}
+		}
+	}
+}
+
+func RequireRole(roles ...authn.Role) gin.HandlerFunc {
+	allowed := make(map[authn.Role]struct{}, len(roles))
+	for _, role := range roles {
+		allowed[role] = struct{}{}
+	}
+	return func(c *gin.Context) {
+		principal, ok := CurrentPrincipal(c)
+		if !ok {
+			abortUnauthorized(c)
+			return
+		}
+		if _, ok = allowed[principal.Role]; !ok {
+			c.JSON(http.StatusForbidden, "forbidden")
+			c.Abort()
+			return
+		}
+		c.Next()
+	}
+}
+
+func CurrentPrincipal(c *gin.Context) (Principal, bool) {
+	value, exists := c.Get(principalContextKey)
+	if !exists {
+		return Principal{}, false
+	}
+	principal, ok := value.(Principal)
+	return principal, ok
+}
+
+func CheckLoopbackInternalToken() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if allowByLoopbackInternalToken(c.Request) {
+			c.Next()
+			return
+		}
+		abortUnauthorized(c)
+	}
+}
+
+func CheckTokenOrLoopbackInternalToken() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if allowByLoopbackInternalToken(c.Request) {
+			c.Next()
+			return
+		}
+
+		principal, token, ok := authenticate(c)
+		if !ok {
+			abortUnauthorized(c)
+			return
+		}
+		c.Set(principalContextKey, principal)
+		c.Set(tokenContextKey, token)
+		c.Next()
+	}
+}
+
+func authenticate(c *gin.Context) (Principal, *Token, bool) {
 	conf := config.GetInstance()
-
-	expireDuration := time.Duration(conf.JWT.RefreshTokenDuration) * time.Second
-
-	claims := Token{
-		Username: username,
-		RegisteredClaims: jwt.RegisteredClaims{
-			ExpiresAt: jwt.NewNumericDate(time.Now().Add(expireDuration)),
-		},
+	if conf.Authentication == "disable" {
+		return Principal{Username: "admin", Role: authn.RoleAdmin}, nil, true
 	}
 
-	t := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+	cookie, err := c.Cookie(CookieName)
+	if err != nil {
+		return Principal{}, nil, false
+	}
+	token, err := ParseJWT(cookie)
+	if err != nil {
+		return Principal{}, nil, false
+	}
+	user, err := authn.DefaultStore.ValidateToken(token.Username, token.TokenVersion)
+	if err != nil {
+		log.Debugf("validate session for %q: %s", token.Username, err)
+		return Principal{}, nil, false
+	}
+	return Principal{Username: user.Username, Role: user.Role}, token, true
+}
 
-	return t.SignedString([]byte(conf.JWT.SecretKey))
+func abortUnauthorized(c *gin.Context) {
+	c.JSON(http.StatusUnauthorized, "unauthorized")
+	c.Abort()
+}
+
+func GenerateJWT(username string, tokenVersion uint64) (string, error) {
+	conf := config.GetInstance()
+	now := time.Now()
+	expireDuration := time.Duration(conf.JWT.RefreshTokenDuration) * time.Second
+	claims := Token{
+		Username:     username,
+		TokenVersion: tokenVersion,
+		RegisteredClaims: jwt.RegisteredClaims{
+			Subject:   username,
+			IssuedAt:  jwt.NewNumericDate(now),
+			ExpiresAt: jwt.NewNumericDate(now.Add(expireDuration)),
+		},
+	}
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+	return token.SignedString([]byte(conf.JWT.SecretKey))
 }
 
 func ParseJWT(jwtToken string) (*Token, error) {
 	conf := config.GetInstance()
-
-	t, err := jwt.ParseWithClaims(jwtToken, &Token{}, func(token *jwt.Token) (interface{}, error) {
-		return []byte(conf.JWT.SecretKey), nil
-	})
+	parsed, err := jwt.ParseWithClaims(
+		jwtToken,
+		&Token{},
+		func(token *jwt.Token) (interface{}, error) {
+			if token.Method != jwt.SigningMethodHS256 {
+				return nil, errors.New("unexpected signing method")
+			}
+			return []byte(conf.JWT.SecretKey), nil
+		},
+		jwt.WithValidMethods([]string{jwt.SigningMethodHS256.Alg()}),
+		jwt.WithExpirationRequired(),
+	)
 	if err != nil {
 		log.Debugf("parse jwt error: %s", err)
 		return nil, err
 	}
-
-	if claims, ok := t.Claims.(*Token); ok && t.Valid {
-		return claims, nil
-	} else {
-		return nil, err
+	claims, ok := parsed.Claims.(*Token)
+	if !ok || !parsed.Valid || claims.Username == "" || claims.Subject != claims.Username || claims.TokenVersion == 0 {
+		return nil, errors.New("invalid token claims")
 	}
+	return claims, nil
 }

server/middleware/jwt_test.go

@@ -0,0 +1,230 @@
+package middleware
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"NanoKVM-Server/authn"
+	"NanoKVM-Server/config"
+
+	"github.com/gin-gonic/gin"
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/gorilla/websocket"
+)
+
+func TestCheckTokenUsesLiveRoleAndVersion(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	store := authn.NewStore(filepath.Join(t.TempDir(), "pwd"))
+	admin, ok, err := store.Authenticate("admin", "admin")
+	if err != nil || !ok {
+		t.Fatalf("default login: ok=%v err=%v", ok, err)
+	}
+	if err = store.Create("alice", "valid-password", authn.RoleUser); err != nil {
+		t.Fatal(err)
+	}
+	alice, err := store.Get("alice")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	restore := useTestAuthStore(t, store)
+	defer restore()
+	adminToken, err := GenerateJWT(admin.Username, admin.TokenVersion)
+	if err != nil {
+		t.Fatal(err)
+	}
+	userToken, err := GenerateJWT(alice.Username, alice.TokenVersion)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	router := gin.New()
+	router.GET("/admin", CheckToken(), RequireRole(authn.RoleAdmin), func(c *gin.Context) {
+		c.Status(http.StatusNoContent)
+	})
+	if status := requestWithToken(router, "/admin", ""); status != http.StatusUnauthorized {
+		t.Fatalf("missing token status = %d", status)
+	}
+	if status := requestWithToken(router, "/admin", adminToken); status != http.StatusNoContent {
+		t.Fatalf("admin status = %d", status)
+	}
+	if status := requestWithToken(router, "/admin", userToken); status != http.StatusForbidden {
+		t.Fatalf("user status = %d", status)
+	}
+	if _, err = store.Revoke("admin"); err != nil {
+		t.Fatal(err)
+	}
+	if status := requestWithToken(router, "/admin", adminToken); status != http.StatusUnauthorized {
+		t.Fatalf("revoked status = %d", status)
+	}
+}
+
+func TestParseJWTRejectsOtherHMACMethods(t *testing.T) {
+	conf := config.GetInstance()
+	originalSecret := conf.JWT.SecretKey
+	conf.JWT.SecretKey = "test-secret"
+	defer func() { conf.JWT.SecretKey = originalSecret }()
+
+	now := time.Now()
+	claims := Token{
+		Username:     "admin",
+		TokenVersion: 1,
+		RegisteredClaims: jwt.RegisteredClaims{
+			Subject:   "admin",
+			ExpiresAt: jwt.NewNumericDate(now.Add(time.Hour)),
+		},
+	}
+	token, err := jwt.NewWithClaims(jwt.SigningMethodHS384, claims).SignedString([]byte(conf.JWT.SecretKey))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err = ParseJWT(token); err == nil {
+		t.Fatal("HS384 token was accepted")
+	}
+}
+
+func TestParseJWTRejectsExpiredToken(t *testing.T) {
+	conf := config.GetInstance()
+	originalSecret := conf.JWT.SecretKey
+	conf.JWT.SecretKey = "test-secret"
+	defer func() { conf.JWT.SecretKey = originalSecret }()
+
+	claims := Token{
+		Username:     "admin",
+		TokenVersion: 1,
+		RegisteredClaims: jwt.RegisteredClaims{
+			Subject:   "admin",
+			ExpiresAt: jwt.NewNumericDate(time.Now().Add(-time.Minute)),
+		},
+	}
+	token, err := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(conf.JWT.SecretKey))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err = ParseJWT(token); err == nil {
+		t.Fatal("expired token was accepted")
+	}
+}
+
+func TestRevokeUserSessionsCancelsActiveRequests(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	unregister := activeSessions.register("alice", cancel)
+	defer unregister()
+
+	RevokeUserSessions("alice")
+	select {
+	case <-ctx.Done():
+	case <-time.After(time.Second):
+		t.Fatal("active session was not cancelled")
+	}
+}
+
+func TestAccountFileResetCancelsActiveSession(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "pwd")
+	store := authn.NewStore(path)
+	user, ok, err := store.Authenticate("admin", "admin")
+	if err != nil || !ok {
+		t.Fatalf("default login: ok=%v err=%v", ok, err)
+	}
+	restore := useTestAuthStore(t, store)
+	defer restore()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go watchSessionState(ctx, cancel, user.Username, user.TokenVersion, 10*time.Millisecond)
+	if err = os.Remove(path); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case <-ctx.Done():
+	case <-time.After(2 * time.Second):
+		t.Fatal("active session survived account-file reset")
+	}
+}
+
+func TestWatchWebSocketClosesRevokedConnection(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	upgrader := websocket.Upgrader{CheckOrigin: func(*http.Request) bool { return true }}
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		connection, err := upgrader.Upgrade(writer, request, nil)
+		if err != nil {
+			return
+		}
+		defer connection.Close()
+		stop := WatchWebSocket(ctx, connection)
+		defer stop()
+		_, _, _ = connection.ReadMessage()
+	}))
+	defer server.Close()
+
+	wsURL := "ws" + server.URL[len("http"):]
+	connection, _, err := websocket.DefaultDialer.Dial(wsURL, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer connection.Close()
+	cancel()
+	_ = connection.SetReadDeadline(time.Now().Add(2 * time.Second))
+	_, _, err = connection.ReadMessage()
+	if !websocket.IsCloseError(err, SessionRevokedCloseCode) {
+		t.Fatalf("close error = %v, want code %d", err, SessionRevokedCloseCode)
+	}
+}
+
+func TestCheckWebSocketOrigin(t *testing.T) {
+	tests := []struct {
+		origin string
+		host   string
+		want   bool
+	}{
+		{"", "kvm.local", true},
+		{"http://kvm.local", "kvm.local", true},
+		{"http://KVM.local", "kvm.local", true},
+		{"http://kvm.local:8080", "kvm.local:8080", true},
+		{"http://kvm.local:8081", "kvm.local:8080", false},
+		{"http://evil.example", "kvm.local", false},
+	}
+	for _, test := range tests {
+		request := httptest.NewRequest(http.MethodGet, "http://"+test.host+"/api/ws", nil)
+		request.Host = test.host
+		if test.origin != "" {
+			request.Header.Set("Origin", test.origin)
+		}
+		if got := CheckWebSocketOrigin(request); got != test.want {
+			t.Fatalf("origin %q host %q = %v, want %v", test.origin, test.host, got, test.want)
+		}
+	}
+}
+
+func requestWithToken(handler http.Handler, path, token string) int {
+	recorder := httptest.NewRecorder()
+	request := httptest.NewRequest(http.MethodGet, path, nil)
+	request.AddCookie(&http.Cookie{Name: CookieName, Value: token})
+	handler.ServeHTTP(recorder, request)
+	return recorder.Code
+}
+
+func useTestAuthStore(t *testing.T, store *authn.Store) func() {
+	t.Helper()
+	originalStore := authn.DefaultStore
+	conf := config.GetInstance()
+	originalAuthentication := conf.Authentication
+	originalSecret := conf.JWT.SecretKey
+	originalDuration := conf.JWT.RefreshTokenDuration
+	authn.DefaultStore = store
+	conf.Authentication = "enable"
+	conf.JWT.SecretKey = "test-secret"
+	conf.JWT.RefreshTokenDuration = 3600
+	return func() {
+		authn.DefaultStore = originalStore
+		conf.Authentication = originalAuthentication
+		conf.JWT.SecretKey = originalSecret
+		conf.JWT.RefreshTokenDuration = originalDuration
+	}
+}

server/middleware/loopback_http.go

@@ -0,0 +1,94 @@
+package middleware
+
+import (
+	"crypto/subtle"
+	"net"
+	"net/http"
+	"strings"
+
+	"NanoKVM-Server/config"
+)
+
+func ListenAndServeLoopbackHTTPRedirect(
+	httpAddr string,
+	httpsPort string,
+	handler http.Handler,
+	allowedPaths ...string,
+) error {
+	allowlist := make(map[string]struct{}, len(allowedPaths))
+	for _, path := range allowedPaths {
+		if strings.TrimSpace(path) == "" {
+			continue
+		}
+		allowlist[path] = struct{}{}
+	}
+
+	return http.ListenAndServe(httpAddr, http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		if isLoopbackAllowedPath(req, allowlist) {
+			if hasValidLoopbackHTTPToken(req) {
+				handler.ServeHTTP(w, req)
+				return
+			}
+
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+
+		http.Redirect(w, req, "https://"+redirectHost(req.Host, httpsPort)+req.URL.RequestURI(), http.StatusTemporaryRedirect)
+	}))
+}
+
+func redirectHost(requestHost string, httpsPort string) string {
+	host := requestHost
+	if h, _, err := net.SplitHostPort(requestHost); err == nil {
+		host = h
+	} else if strings.HasPrefix(host, "[") && strings.HasSuffix(host, "]") {
+		host = strings.TrimPrefix(strings.TrimSuffix(host, "]"), "[")
+	}
+
+	if httpsPort != "443" {
+		return net.JoinHostPort(host, httpsPort)
+	}
+
+	if strings.Contains(host, ":") && !strings.HasPrefix(host, "[") && !strings.HasSuffix(host, "]") {
+		return "[" + host + "]"
+	}
+
+	return host
+}
+
+func allowByLoopbackInternalToken(req *http.Request) bool {
+	return req != nil && isLoopbackRemote(req.RemoteAddr) && hasValidLoopbackHTTPToken(req)
+}
+
+func isLoopbackAllowedPath(req *http.Request, allowedPaths map[string]struct{}) bool {
+	if !allowByLoopbackInternalToken(req) {
+		return false
+	}
+
+	_, allowed := allowedPaths[req.URL.Path]
+	return allowed
+}
+
+func hasValidLoopbackHTTPToken(req *http.Request) bool {
+	if req == nil {
+		return false
+	}
+	token, err := config.GetPicoclawInternalToken()
+	if err != nil || token == "" {
+		return false
+	}
+
+	provided := req.Header.Get(config.PicoclawInternalTokenHeader)
+	return subtle.ConstantTimeCompare([]byte(provided), []byte(token)) == 1
+}
+
+func isLoopbackRemote(remoteAddr string) bool {
+	host := strings.TrimSpace(remoteAddr)
+	if parsedHost, _, err := net.SplitHostPort(remoteAddr); err == nil {
+		host = parsedHost
+	}
+
+	ip := net.ParseIP(strings.Trim(host, "[]"))
+	return ip != nil && ip.IsLoopback()
+}

server/middleware/session.go

@@ -0,0 +1,123 @@
+package middleware
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+const SessionRevokedCloseCode = 4401
+
+type sessionRegistry struct {
+	mutex    sync.Mutex
+	nextID   atomic.Uint64
+	byUserID map[string]map[uint64]context.CancelFunc
+}
+
+var activeSessions = &sessionRegistry{byUserID: make(map[string]map[uint64]context.CancelFunc)}
+
+func (r *sessionRegistry) register(username string, cancel context.CancelFunc) func() {
+	id := r.nextID.Add(1)
+	r.mutex.Lock()
+	if r.byUserID[username] == nil {
+		r.byUserID[username] = make(map[uint64]context.CancelFunc)
+	}
+	r.byUserID[username][id] = cancel
+	r.mutex.Unlock()
+
+	return func() {
+		r.mutex.Lock()
+		delete(r.byUserID[username], id)
+		if len(r.byUserID[username]) == 0 {
+			delete(r.byUserID, username)
+		}
+		r.mutex.Unlock()
+	}
+}
+
+func RevokeUserSessions(username string) {
+	activeSessions.mutex.Lock()
+	sessions := activeSessions.byUserID[username]
+	delete(activeSessions.byUserID, username)
+	activeSessions.mutex.Unlock()
+
+	for _, cancel := range sessions {
+		cancel()
+	}
+}
+
+func WatchWebSocket(ctx context.Context, connection *websocket.Conn) func() {
+	stopped := make(chan struct{})
+	var stopOnce sync.Once
+	go func() {
+		select {
+		case <-ctx.Done():
+			_ = connection.WriteControl(
+				websocket.CloseMessage,
+				websocket.FormatCloseMessage(SessionRevokedCloseCode, "session expired or revoked"),
+				time.Now().Add(2*time.Second),
+			)
+			_ = connection.Close()
+		case <-stopped:
+		}
+	}()
+	return func() { stopOnce.Do(func() { close(stopped) }) }
+}
+
+func CheckWebSocketOrigin(request *http.Request) bool {
+	origin := strings.TrimSpace(request.Header.Get("Origin"))
+	if origin == "" {
+		return true
+	}
+	parsed, err := url.Parse(origin)
+	if err != nil || parsed.Host == "" {
+		return false
+	}
+	requestScheme := "http"
+	if request.TLS != nil {
+		requestScheme = "https"
+	}
+	if forwarded := strings.TrimSpace(strings.Split(request.Header.Get("X-Forwarded-Proto"), ",")[0]); forwarded != "" {
+		requestScheme = strings.ToLower(forwarded)
+	}
+	return equalOrigin(parsed, request.Host, requestScheme)
+}
+
+func equalOrigin(origin *url.URL, requestHost, requestScheme string) bool {
+	originHost, originPort := splitHostPort(origin.Host)
+	host, port := splitHostPort(requestHost)
+	if !strings.EqualFold(originHost, host) {
+		return false
+	}
+	if originPort == "" {
+		originPort = defaultPort(origin.Scheme)
+	}
+	if port == "" {
+		port = defaultPort(requestScheme)
+	}
+	return originPort == port
+}
+
+func splitHostPort(value string) (string, string) {
+	host, port, err := net.SplitHostPort(value)
+	if err == nil {
+		return host, port
+	}
+	return strings.Trim(value, "[]"), ""
+}
+
+func defaultPort(scheme string) string {
+	switch strings.ToLower(scheme) {
+	case "https", "wss":
+		return "443"
+	default:
+		return "80"
+	}
+}

server/proto/application.go

@@ -12,3 +12,13 @@ type GetPreviewRsp struct {
 type SetPreviewReq struct {
 	Enable bool `validate:"omitempty"`
 }
+
+type GetUpdateServerRsp struct {
+	Enabled bool   `json:"enabled"`
+	URL     string `json:"url"`
+}
+
+type SetUpdateServerReq struct {
+	Enabled *bool  `json:"enabled" form:"enabled" validate:"required"`
+	URL     string `json:"url" form:"url"`
+}

server/proto/auth.go

@@ -5,19 +5,38 @@ type LoginReq struct {
 	Password string `validate:"required"`
 }
 
-type LoginRsp struct {
-	Token string `json:"token"`
-}
-
 type GetAccountRsp struct {
 	Username string `json:"username"`
+	Role     string `json:"role"`
 }
 
 type ChangePasswordReq struct {
-	Username string `json:"username" validate:"required"`
-	Password string `json:"password" validate:"required"`
+	CurrentPassword string `json:"currentPassword"`
+	Password        string `json:"password" validate:"required"`
 }
 
 type IsPasswordUpdatedRsp struct {
 	IsUpdated bool `json:"isUpdated"`
 }
+
+type UserInfo struct {
+	Username      string `json:"username"`
+	Role          string `json:"role"`
+	Enabled       bool   `json:"enabled"`
+	SystemAccount bool   `json:"systemAccount,omitempty"`
+}
+
+type ListUsersRsp struct {
+	Users []UserInfo `json:"users"`
+}
+
+type CreateUserReq struct {
+	Username string `json:"username" validate:"required"`
+	Password string `json:"password" validate:"required"`
+	Role     string `json:"role" validate:"required"`
+}
+
+type UpdateUserReq struct {
+	Role    *string `json:"role"`
+	Enabled *bool   `json:"enabled"`
+}

server/proto/download.go

@@ -1,5 +1,10 @@
 package proto
 
+type DownloadImageReq struct {
+	File      string `json:"file" validate:"required"`
+	SHA256Sum string `json:"sha256sum"`
+}
+
 type ImageEnabledRsp struct {
 	Enabled bool `json:"enabled"`
 }

server/proto/hid.go

@@ -4,6 +4,14 @@ type GetHidModeRsp struct {
 	Mode string `json:"mode"` // normal or hid-only
 }
 
+type GetKeyboardLedStatusRsp struct {
+	NumLock    bool   `json:"numLock"`
+	CapsLock   bool   `json:"capsLock"`
+	ScrollLock bool   `json:"scrollLock"`
+	Known      bool   `json:"known"`
+	UpdatedAt  string `json:"updatedAt"`
+}
+
 type SetHidModeReq struct {
 	Mode string `validate:"required"` // normal or hid-only
 }
@@ -29,3 +37,11 @@ type AddShortcutReq struct {
 type DeleteShortcutReq struct {
 	ID string `validate:"required"`
 }
+
+type SetLeaderKeyReq struct {
+	Key string `validate:"omitempty"`
+}
+
+type GetLeaderKeyRsp struct {
+	Key string `json:"key"`
+}

server/proto/mcp.go

@@ -0,0 +1,12 @@
+package proto
+
+type GetMCPConfigRsp struct {
+	Enabled       bool   `json:"enabled"`
+	APIKey        string `json:"apiKey"`
+	ControlMode   string `json:"controlMode"`
+	Transitioning bool   `json:"transitioning"`
+}
+
+type SetMCPConfigReq struct {
+	Enabled *bool `json:"enabled" form:"enabled" validate:"required"`
+}

server/proto/network.go

@@ -26,5 +26,27 @@ type GetWifiRsp struct {
 
 type ConnectWifiReq struct {
 	Ssid     string `validate:"required"`
-	Password string `valid:"required"`
+	Password string `validate:"required"`
+}
+
+type GetDNSRsp struct {
+	Mode      string   `json:"mode"`
+	Servers   []string `json:"servers"`
+	Effective []string `json:"effective"`
+	DHCP      []string `json:"dhcp"`
+	Info      DNSInfo  `json:"info"`
+}
+
+type SetDNSReq struct {
+	Mode    string   `json:"mode" validate:"required,oneof=manual dhcp"`
+	Servers []string `json:"servers"`
+}
+
+type DNSInfo struct {
+	Interface     string   `json:"interface"`
+	Type          string   `json:"type"`
+	Address       string   `json:"address"`
+	SubnetMask    string   `json:"subnetMask"`
+	Gateway       string   `json:"gateway"`
+	SearchDomains []string `json:"searchDomains"`
 }

server/proto/request.go

@@ -20,7 +20,7 @@ func ValidateRequest(req interface{}) error {
 	}
 
 	if env == "" || env == "debug" {
-		log.Debugf("request: %+v\n", req)
+		log.Debugf("request validated: %T", req)
 	}
 
 	return nil

server/proto/vm.go

@@ -98,7 +98,13 @@ type GetOLEDRsp struct {
 }
 
 type GetGetHdmiStateRsp struct {
-	Enabled bool `json:"enabled"`
+	Enabled     bool `json:"enabled"`
+	Signal      bool `json:"signal"`
+	IdleTimeout int  `json:"idleTimeout"`
+}
+
+type SetHdmiIdleTimeoutReq struct {
+	Minutes int `validate:"gte=0,lte=10080"`
 }
 
 type GetSSHStateRsp struct {
@@ -146,3 +152,54 @@ type GetWebTitleRsp struct {
 type SetTlsReq struct {
 	Enabled bool `validate:"omitempty"`
 }
+
+type InputRegion struct {
+	Mode               string               `json:"mode"`
+	FrameWidth         int                  `json:"frameWidth"`
+	FrameHeight        int                  `json:"frameHeight"`
+	Left               int                  `json:"left"`
+	Top                int                  `json:"top"`
+	Width              int                  `json:"width"`
+	Height             int                  `json:"height"`
+	Resolutions        []OriginalResolution `json:"resolutions,omitempty"`
+	SelectedResolution string               `json:"selectedResolution"`
+	Regions            []ManualRegion       `json:"regions,omitempty"`
+	SelectedRegion     string               `json:"selectedRegion"`
+}
+
+type ManualRegion struct {
+	FrameWidth  int `json:"frameWidth"`
+	FrameHeight int `json:"frameHeight"`
+	Left        int `json:"left"`
+	Top         int `json:"top"`
+	Width       int `json:"width"`
+	Height      int `json:"height"`
+}
+
+type OriginalResolution struct {
+	Width  int `json:"width"`
+	Height int `json:"height"`
+}
+
+type SetInputRegionReq struct {
+	Mode               string                `json:"mode"`
+	FrameWidth         *int                  `json:"frameWidth,omitempty"`
+	FrameHeight        *int                  `json:"frameHeight,omitempty"`
+	Left               *int                  `json:"left,omitempty"`
+	Top                *int                  `json:"top,omitempty"`
+	Width              *int                  `json:"width,omitempty"`
+	Height             *int                  `json:"height,omitempty"`
+	Resolutions        *[]OriginalResolution `json:"resolutions,omitempty"`
+	SelectedResolution *string               `json:"selectedResolution,omitempty"`
+	Regions            *[]ManualRegion       `json:"regions,omitempty"`
+	SelectedRegion     *string               `json:"selectedRegion,omitempty"`
+}
+
+type GetInputRegionRsp struct {
+	InputRegion
+}
+
+type GetInputResolutionRsp struct {
+	Width  int `json:"width"`
+	Height int `json:"height"`
+}

server/router/application.go

@@ -1,6 +1,7 @@
 package router
 
 import (
+	"NanoKVM-Server/authn"
 	"NanoKVM-Server/middleware"
 	"NanoKVM-Server/service/application"
 
@@ -9,7 +10,7 @@ import (
 
 func applicationRouter(r *gin.Engine) {
 	service := application.NewService()
-	api := r.Group("/api").Use(middleware.CheckToken())
+	api := r.Group("/api").Use(middleware.CheckToken(), middleware.RequireRole(authn.RoleAdmin))
 
 	api.GET("/application/version", service.GetVersion)            // get application version
 	api.POST("/application/update", service.Update)                // update application
@@ -17,4 +18,7 @@ func applicationRouter(r *gin.Engine) {
 
 	api.GET("/application/preview", service.GetPreview)  // get preview updates state
 	api.POST("/application/preview", service.SetPreview) // set preview updates state
+
+	api.GET("/application/update-server", service.GetUpdateServer)  // get custom update server
+	api.POST("/application/update-server", service.SetUpdateServer) // set custom update server
 }

server/router/auth.go

@@ -3,6 +3,7 @@ package router
 import (
 	"github.com/gin-gonic/gin"
 
+	"NanoKVM-Server/authn"
 	"NanoKVM-Server/middleware"
 	"NanoKVM-Server/service/auth"
 )
@@ -18,4 +19,14 @@ func authRouter(r *gin.Engine) {
 	api.GET("/auth/account", service.GetAccount)         // get account
 	api.POST("/auth/password", service.ChangePassword)   // change password
 	api.POST("/auth/logout", service.Logout)             // logout
+
+	admin := r.Group("/api").Use(
+		middleware.CheckToken(),
+		middleware.RequireRole(authn.RoleAdmin),
+	)
+	admin.GET("/auth/users", service.ListUsers)
+	admin.POST("/auth/users", service.CreateUser)
+	admin.PUT("/auth/users/:username", service.UpdateUser)
+	admin.DELETE("/auth/users/:username", service.DeleteUser)
+	admin.POST("/auth/users/:username/password", service.ChangeUserPassword)
 }

server/router/control.go

@@ -0,0 +1,163 @@
+package router
+
+import (
+	"net/http"
+	"time"
+
+	"NanoKVM-Server/authn"
+	"NanoKVM-Server/middleware"
+	"NanoKVM-Server/service/controlmode"
+	"NanoKVM-Server/service/hid"
+	"NanoKVM-Server/service/inputcontrol"
+	"NanoKVM-Server/service/picoclaw"
+
+	"github.com/gin-gonic/gin"
+	log "github.com/sirupsen/logrus"
+)
+
+type setAIControlModeRequest struct {
+	Mode controlmode.Mode `json:"mode"`
+}
+
+func controlRouter(r *gin.Engine, control *controlmode.Manager, picoclawService *picoclaw.Service) {
+	group := r.Group("/api/ai/control").Use(
+		middleware.CheckToken(),
+		middleware.RequireRole(authn.RoleAdmin),
+	)
+	group.GET("/status", func(c *gin.Context) {
+		status, err := control.Status()
+		if err != nil {
+			c.JSON(http.StatusOK, gin.H{"code": -1, "message": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"code": 0, "msg": "success", "data": status})
+	})
+
+	group.PUT("/mode", func(c *gin.Context) {
+		startedAt := time.Now()
+		var req setAIControlModeRequest
+		if err := c.ShouldBindJSON(&req); err != nil {
+			c.JSON(http.StatusOK, gin.H{"code": -1, "message": "invalid arguments"})
+			return
+		}
+		if !validAIControlMode(req.Mode) {
+			c.JSON(http.StatusOK, gin.H{"code": -1, "message": "invalid control mode"})
+			return
+		}
+
+		previousStatus, previousErr := control.Status()
+		if previousErr != nil {
+			log.WithFields(log.Fields{
+				"request_mode": string(req.Mode),
+				"elapsed_ms":   time.Since(startedAt).Milliseconds(),
+			}).WithError(previousErr).Warn("AI control mode request failed before switch")
+			c.JSON(http.StatusOK, gin.H{"code": -2, "message": previousErr.Error()})
+			return
+		}
+
+		preempt := func() error {
+			inputcontrol.GetCoordinator().CancelMCP()
+			if req.Mode == controlmode.ModeMCP {
+				return picoclawService.PreemptControlLeasesForMCP()
+			}
+			picoclawService.CancelActiveControlOperations()
+			return nil
+		}
+		cleanup := func() error {
+			return hid.ReleaseAllHIDStateBestEffort()
+		}
+		if req.Mode == controlmode.ModeMCP {
+			cleanup = func() error {
+				if err := picoclawService.StopRuntimeForMCP(); err != nil {
+					return err
+				}
+				return hid.ReleaseAllHIDStateBestEffort()
+			}
+		}
+		if err := control.SwitchWithCleanup(req.Mode, preempt, cleanup); err != nil {
+			if req.Mode == controlmode.ModeOff {
+				if status, statusErr := control.Status(); statusErr == nil && status.Mode == controlmode.ModeOff {
+					picoclawService.CancelActiveControlOperations()
+					picoclawService.PreserveRuntimeForChatOnly("control_release_chat_only")
+					closedSessions := 0
+					picoclawService.PublishControlModeChangedFrom(status, "ai_control_mode")
+					log.WithFields(log.Fields{
+						"request_mode":    string(req.Mode),
+						"previous_mode":   string(previousStatus.Mode),
+						"final_mode":      string(status.Mode),
+						"transitioning":   status.Transitioning,
+						"closed_sessions": closedSessions,
+						"elapsed_ms":      time.Since(startedAt).Milliseconds(),
+					}).WithError(err).Warn("AI control mode request completed with cleanup warning")
+					c.JSON(http.StatusOK, gin.H{
+						"code": 0,
+						"msg":  "success",
+						"data": gin.H{
+							"control":         status,
+							"runtime":         picoclawService.RuntimeStatus(),
+							"released":        true,
+							"closed_sessions": closedSessions,
+							"cleanup_warning": err.Error(),
+						},
+					})
+					return
+				}
+			}
+			log.WithFields(log.Fields{
+				"request_mode":  string(req.Mode),
+				"previous_mode": string(previousStatus.Mode),
+				"elapsed_ms":    time.Since(startedAt).Milliseconds(),
+			}).WithError(err).Warn("AI control mode request failed")
+			c.JSON(http.StatusOK, gin.H{"code": -2, "message": err.Error()})
+			return
+		}
+
+		status, err := control.Status()
+		if err != nil {
+			log.WithFields(log.Fields{
+				"request_mode":  string(req.Mode),
+				"previous_mode": string(previousStatus.Mode),
+				"elapsed_ms":    time.Since(startedAt).Milliseconds(),
+			}).WithError(err).Warn("AI control mode request failed after switch")
+			c.JSON(http.StatusOK, gin.H{"code": -2, "message": err.Error()})
+			return
+		}
+		closedSessions := 0
+		if req.Mode == controlmode.ModeOff {
+			picoclawService.CancelActiveControlOperations()
+			picoclawService.PreserveRuntimeForChatOnly("control_release_chat_only")
+		}
+		picoclawService.PublishControlModeChangedFrom(status, "ai_control_mode")
+		log.WithFields(log.Fields{
+			"request_mode":  string(req.Mode),
+			"previous_mode": string(previousStatus.Mode),
+			"final_mode":    string(status.Mode),
+			"transitioning": status.Transitioning,
+			"elapsed_ms":    time.Since(startedAt).Milliseconds(),
+		}).Info("AI control mode request completed")
+		if req.Mode == controlmode.ModeOff {
+			c.JSON(http.StatusOK, gin.H{
+				"code": 0,
+				"msg":  "success",
+				"data": gin.H{
+					"control":         status,
+					"runtime":         picoclawService.RuntimeStatus(),
+					"released":        true,
+					"closed_sessions": closedSessions,
+					"cleanup_warning": "",
+				},
+			})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"code": 0, "msg": "success", "data": status})
+	})
+}
+
+func validAIControlMode(mode controlmode.Mode) bool {
+	switch mode {
+	case controlmode.ModeOff, controlmode.ModeMCP, controlmode.ModePicoclaw:
+		return true
+	default:
+		return false
+	}
+}

server/router/download.go

@@ -1,6 +1,7 @@
 package router
 
 import (
+	"NanoKVM-Server/authn"
 	"NanoKVM-Server/service/download"
 	"github.com/gin-gonic/gin"
 
@@ -9,10 +10,11 @@ import (
 
 func downloadRouter(r *gin.Engine) {
 	service := download.NewService()
-	api := r.Group("/api").Use(middleware.CheckToken())
+	api := r.Group("/api").Use(middleware.CheckToken(), middleware.RequireRole(authn.RoleAdmin))
 
-	api.POST("/download/image", service.DownloadImage)       // download image
-	api.GET("/download/image/status", service.StatusImage)   // download image
-	api.GET("/download/image/enabled", service.ImageEnabled) // download image
-	api.POST("/download/file", service.DownloadImageFile)       // download image
+	api.POST("/download/image", service.DownloadImage)              // download image
+	api.POST("/download/image/cancel", service.CancelDownloadImage) // cancel image download
+	api.GET("/download/image/status", service.StatusImage)          // download image
+	api.GET("/download/image/enabled", service.ImageEnabled)        // download image
+	api.POST("/download/file", service.DownloadImageFile)           // download image
 }

server/router/extensions.go

@@ -1,6 +1,7 @@
 package router
 
 import (
+	"NanoKVM-Server/authn"
 	"NanoKVM-Server/middleware"
 	"NanoKVM-Server/service/extensions/tailscale"
 
@@ -8,7 +9,10 @@ import (
 )
 
 func extensionsRouter(r *gin.Engine) {
-	api := r.Group("/api/extensions").Use(middleware.CheckToken())
+	api := r.Group("/api/extensions").Use(
+		middleware.CheckToken(),
+		middleware.RequireRole(authn.RoleAdmin),
+	)
 
 	ts := tailscale.NewService()
 

server/router/hid.go

@@ -3,21 +3,39 @@ package router
 import (
 	"github.com/gin-gonic/gin"
 
+	"NanoKVM-Server/authn"
 	"NanoKVM-Server/middleware"
 	"NanoKVM-Server/service/hid"
 )
 
+const internalUSBRecoverPath = "/api/internal/usb/recover"
+
+func HIDLoopbackHTTPAllowedPaths() []string {
+	return []string{internalUSBRecoverPath}
+}
+
 func hidRouter(r *gin.Engine) {
 	service := hid.NewService()
 	api := r.Group("/api").Use(middleware.CheckToken())
+	localAPI := r.Group("/api/internal").Use(middleware.CheckLoopbackInternalToken())
 
 	api.POST("/hid/paste", service.Paste) // paste
 
-	api.GET("/hid/shortcuts", service.GetShortcuts)     // get shortcuts
-	api.POST("/hid/shortcut", service.AddShortcut)      // add shortcut
-	api.DELETE("/hid/shortcut", service.DeleteShortcut) // delete shortcut
+	api.GET("/hid/shortcuts", service.GetShortcuts)           // get shortcuts
+	api.GET("/hid/shortcut/leader-key", service.GetLeaderKey) // get shortcut leader key
 
-	api.GET("/hid/mode", service.GetHidMode)  // get hid mode
-	api.POST("/hid/mode", service.SetHidMode) // set hid mode
-	api.POST("/hid/reset", service.ResetHid)  // reset hid
+	api.GET("/hid/mode", service.GetHidMode) // get hid mode
+	api.GET("/hid/leds", service.GetKeyboardLedStatus)
+
+	admin := r.Group("/api").Use(
+		middleware.CheckToken(),
+		middleware.RequireRole(authn.RoleAdmin),
+	)
+	admin.POST("/hid/mode", service.SetHidMode) // set hid mode
+	admin.POST("/hid/reset", service.ResetHid)  // reset hid
+	admin.POST("/hid/shortcut", service.AddShortcut)
+	admin.DELETE("/hid/shortcut", service.DeleteShortcut)
+	admin.POST("/hid/shortcut/leader-key", service.SetLeaderKey)
+
+	localAPI.POST("/usb/recover", service.RecoverUSB)
 }

server/router/mcp.go

@@ -0,0 +1,38 @@
+package router
+
+import (
+	"net/http"
+
+	"NanoKVM-Server/authn"
+	"NanoKVM-Server/middleware"
+	"NanoKVM-Server/service/controlmode"
+	"NanoKVM-Server/service/hid"
+	mcpservice "NanoKVM-Server/service/mcp"
+	"NanoKVM-Server/service/mcp/capture/kvm"
+	"NanoKVM-Server/service/picoclaw"
+
+	"github.com/gin-gonic/gin"
+)
+
+func mcpRouter(r *gin.Engine, control *controlmode.Manager, picoclawService *picoclaw.Service) {
+	service := mcpservice.NewServiceWithPreempt(
+		control,
+		picoclawService.PreemptControlLeasesForMCP,
+		picoclawService.StopRuntimeForMCP,
+		hid.ReleaseAllHIDStateBestEffort,
+		func(status controlmode.Status) {
+			picoclawService.PublishControlModeChangedFrom(status, "mcp_config")
+		},
+	)
+	management := r.Group("/api/mcp").Use(
+		middleware.CheckToken(),
+		middleware.RequireRole(authn.RoleAdmin),
+	)
+	management.GET("/config", service.GetConfig)
+	management.POST("/config", service.SetConfig)
+	management.POST("/key/regenerate", service.RegenerateAPIKey)
+
+	handler := mcpservice.NewMCPHandler(control, kvmcapture.New())
+	handler = http.NewCrossOriginProtection().Handler(handler)
+	r.Any("/api/mcp", mcpservice.APIKeyMiddleware(control), gin.WrapH(handler))
+}

server/router/network.go

@@ -3,6 +3,7 @@ package router
 import (
 	"github.com/gin-gonic/gin"
 
+	"NanoKVM-Server/authn"
 	"NanoKVM-Server/middleware"
 	"NanoKVM-Server/service/network"
 )
@@ -10,16 +11,24 @@ import (
 func networkRouter(r *gin.Engine) {
 	service := network.NewService()
 
-	r.POST("/api/network/wifi", service.ConnectWifiNoAuth) // connect Wi-Fi without auth (only available in ap mode)
+	r.POST("/api/network/wifi", service.ConnectWifiNoAuth)    // connect Wi-Fi without auth (only available in ap mode)
+	r.POST("/api/network/wifi/verify", service.VerifyApLogin) // verify ap login
 
 	api := r.Group("/api").Use(middleware.CheckToken())
 
-	api.POST("/network/wol", service.WakeOnLAN)           // wake on lan
-	api.GET("/network/wol/mac", service.GetMac)           // get mac list
-	api.DELETE("/network/wol/mac", service.DeleteMac)     // delete mac
-	api.POST("/network/wol/mac/name", service.SetMacName) // set mac name
+	api.POST("/network/wol", service.WakeOnLAN) // wake on lan
+	api.GET("/network/wol/mac", service.GetMac) // get mac list
 
-	api.GET("/network/wifi", service.GetWifi)                    // get Wi-Fi information
-	api.POST("/network/wifi/connect", service.ConnectWifi)       // connect Wi-Fi
-	api.POST("/network/wifi/disconnect", service.DisconnectWifi) // disconnect Wi-Fi
+	admin := r.Group("/api").Use(
+		middleware.CheckToken(),
+		middleware.RequireRole(authn.RoleAdmin),
+	)
+	admin.DELETE("/network/wol/mac", service.DeleteMac)     // delete mac
+	admin.POST("/network/wol/mac/name", service.SetMacName) // set mac name
+
+	admin.GET("/network/wifi", service.GetWifi)                    // get Wi-Fi information
+	admin.POST("/network/wifi/connect", service.ConnectWifi)       // connect Wi-Fi
+	admin.POST("/network/wifi/disconnect", service.DisconnectWifi) // disconnect Wi-Fi
+	admin.GET("/network/dns", service.GetDNS)                      // get DNS configuration
+	admin.POST("/network/dns", service.SetDNS)                     // set DNS configuration
 }

server/router/picoclaw.go

@@ -0,0 +1,67 @@
+package router
+
+import (
+	"github.com/gin-gonic/gin"
+
+	"NanoKVM-Server/authn"
+	"NanoKVM-Server/middleware"
+	"NanoKVM-Server/service/picoclaw"
+)
+
+const (
+	picoclawBasePath             = "/api/picoclaw"
+	picoclawModelConfigPath      = "/model/config"
+	picoclawAgentProfilePath     = "/agent/profile"
+	picoclawSessionsPath         = "/sessions"
+	picoclawSessionByIDPath      = "/sessions/:id"
+	picoclawRuntimeStatusPath    = "/runtime/status"
+	picoclawRuntimeSessionPath   = "/runtime/session"
+	picoclawRuntimeInstallPath   = "/runtime/install"
+	picoclawRuntimeUninstallPath = "/runtime/uninstall"
+	picoclawRuntimeStartPath     = "/runtime/start"
+	picoclawRuntimeStopPath      = "/runtime/stop"
+	picoclawGatewayWSPath        = "/gateway/ws"
+	picoclawScreenshotPath       = "/screenshot"
+	picoclawActionsPath          = "/actions"
+	picoclawMCPPath              = "/mcp"
+	picoclawLoadImagePath        = "/load-image"
+)
+
+var picoclawLoopbackHTTPAllowedPaths = []string{
+	picoclawBasePath + picoclawMCPPath,
+	picoclawBasePath + picoclawRuntimeSessionPath,
+	picoclawBasePath + picoclawScreenshotPath,
+	picoclawBasePath + picoclawActionsPath,
+	picoclawBasePath + picoclawLoadImagePath,
+}
+
+func PicoclawLoopbackHTTPAllowedPaths() []string {
+	return append([]string(nil), picoclawLoopbackHTTPAllowedPaths...)
+}
+
+func picoclawRouter(r *gin.Engine, service *picoclaw.Service) {
+	frontendAPI := r.Group(picoclawBasePath).Use(
+		middleware.CheckToken(),
+		middleware.RequireRole(authn.RoleAdmin),
+	)
+	localAPI := r.Group(picoclawBasePath).Use(middleware.CheckLoopbackInternalToken())
+
+	localAPI.GET(picoclawScreenshotPath, service.Screenshot)
+	localAPI.POST(picoclawActionsPath, service.Actions)
+	localAPI.POST(picoclawMCPPath, service.MCPHandler)
+	localAPI.POST(picoclawLoadImagePath, service.LoadImage)
+	localAPI.GET(picoclawRuntimeSessionPath, service.GetRuntimeSession)
+
+	frontendAPI.POST(picoclawModelConfigPath, service.UpdateModelConfig)
+	frontendAPI.POST(picoclawAgentProfilePath, service.UpdateAgentProfile)
+	frontendAPI.GET(picoclawSessionsPath, service.ListSessions)
+	frontendAPI.GET(picoclawSessionByIDPath, service.GetSession)
+	frontendAPI.DELETE(picoclawSessionByIDPath, service.DeleteSession)
+	frontendAPI.GET(picoclawRuntimeStatusPath, service.GetRuntimeStatus)
+	frontendAPI.DELETE(picoclawRuntimeSessionPath, service.ReleaseRuntimeSession)
+	frontendAPI.POST(picoclawRuntimeInstallPath, service.InstallRuntime)
+	frontendAPI.POST(picoclawRuntimeUninstallPath, service.UninstallRuntime)
+	frontendAPI.POST(picoclawRuntimeStartPath, service.StartRuntime)
+	frontendAPI.POST(picoclawRuntimeStopPath, service.StopRuntime)
+	frontendAPI.GET(picoclawGatewayWSPath, service.ConnectGateway)
+}

server/router/router.go

@@ -5,6 +5,9 @@ import (
 	"os"
 	"path/filepath"
 
+	"NanoKVM-Server/service/controlmode"
+	"NanoKVM-Server/service/picoclaw"
+
 	"github.com/gin-gonic/contrib/static"
 	"github.com/gin-gonic/gin"
 	log "github.com/sirupsen/logrus"
@@ -29,6 +32,9 @@ func web(r *gin.Engine) {
 }
 
 func server(r *gin.Engine) {
+	control := controlmode.GetManager()
+	picoclawService := picoclaw.NewService(control)
+
 	authRouter(r)
 	applicationRouter(r)
 	vmRouter(r)
@@ -36,7 +42,16 @@ func server(r *gin.Engine) {
 	storageRouter(r)
 	networkRouter(r)
 	hidRouter(r)
+	controlRouter(r, control, picoclawService)
+	mcpRouter(r, control, picoclawService)
+	picoclawRouter(r, picoclawService)
 	wsRouter(r)
 	downloadRouter(r)
 	extensionsRouter(r)
 }
+
+func LoopbackHTTPAllowedPaths() []string {
+	paths := PicoclawLoopbackHTTPAllowedPaths()
+	paths = append(paths, HIDLoopbackHTTPAllowedPaths()...)
+	return paths
+}

server/router/storage.go

@@ -3,13 +3,14 @@ package router
 import (
 	"github.com/gin-gonic/gin"
 
+	"NanoKVM-Server/authn"
 	"NanoKVM-Server/middleware"
 	"NanoKVM-Server/service/storage"
 )
 
 func storageRouter(r *gin.Engine) {
 	service := storage.NewService()
-	api := r.Group("/api").Use(middleware.CheckToken())
+	api := r.Group("/api").Use(middleware.CheckToken(), middleware.RequireRole(authn.RoleAdmin))
 
 	api.GET("/storage/image", service.GetImages)               // get image list
 	api.GET("/storage/image/mounted", service.GetMountedImage) // get mounted image

server/router/vm.go

@@ -3,6 +3,7 @@ package router
 import (
 	"github.com/gin-gonic/gin"
 
+	"NanoKVM-Server/authn"
 	"NanoKVM-Server/middleware"
 	"NanoKVM-Server/service/vm"
 )
@@ -11,6 +12,10 @@ func vmRouter(r *gin.Engine) {
 	service := vm.NewService()
 
 	api := r.Group("/api").Use(middleware.CheckToken())
+	admin := r.Group("/api").Use(
+		middleware.CheckToken(),
+		middleware.RequireRole(authn.RoleAdmin),
+	)
 
 	api.GET("/vm/info", service.GetInfo)         // get device information
 	api.GET("/vm/hardware", service.GetHardware) // get hardware version
@@ -19,54 +24,59 @@ func vmRouter(r *gin.Engine) {
 	api.GET("/vm/gpio", service.GetGpio)      // get gpio
 	api.POST("/vm/screen", service.SetScreen) // update screen
 
-	api.GET("/vm/terminal", service.Terminal) // web terminal
+	api.GET("/vm/input-region", service.GetInputRegion)
+	api.POST("/vm/input-region", service.SetInputRegion)
+	api.GET("/vm/input-resolution", service.GetInputResolution)
 
-	api.GET("/vm/script", service.GetScripts)           // get script
-	api.POST("/vm/script/upload", service.UploadScript) // upload script
-	api.POST("/vm/script/run", service.RunScript)       // run script
-	api.DELETE("/vm/script", service.DeleteScript)      // delete script
+	admin.GET("/vm/terminal", service.Terminal) // web terminal
 
-	api.GET("/vm/device/virtual", service.GetVirtualDevice)     // get virtual device
-	api.POST("/vm/device/virtual", service.UpdateVirtualDevice) // update virtual device
+	admin.GET("/vm/script", service.GetScripts)           // get script
+	admin.POST("/vm/script/upload", service.UploadScript) // upload script
+	admin.POST("/vm/script/run", service.RunScript)       // run script
+	admin.DELETE("/vm/script", service.DeleteScript)      // delete script
 
-	api.GET("/vm/memory/limit", service.GetMemoryLimit)  // get memory limit
-	api.POST("/vm/memory/limit", service.SetMemoryLimit) // set memory limit
+	admin.GET("/vm/device/virtual", service.GetVirtualDevice)     // get virtual device
+	admin.POST("/vm/device/virtual", service.UpdateVirtualDevice) // update virtual device
 
-	api.GET("/vm/oled", service.GetOLED)  // get OLED configuration
-	api.POST("/vm/oled", service.SetOLED) // set OLED configuration
+	admin.GET("/vm/memory/limit", service.GetMemoryLimit)  // get memory limit
+	admin.POST("/vm/memory/limit", service.SetMemoryLimit) // set memory limit
+
+	admin.GET("/vm/oled", service.GetOLED)  // get OLED configuration
+	admin.POST("/vm/oled", service.SetOLED) // set OLED configuration
 
 	// Only supported by PCIe version
-	api.GET("/vm/hdmi", service.GetHdmiState)         // get HDMI state
-	api.POST("/vm/hdmi/reset", service.ResetHdmi)     // reset hdmi
-	api.POST("/vm/hdmi/enable", service.EnableHdmi)   // enable hdmi
-	api.POST("/vm/hdmi/disable", service.DisableHdmi) // disable hdmi
+	api.GET("/vm/hdmi", service.GetHdmiState)           // get HDMI state
+	api.POST("/vm/hdmi/reset", service.ResetHdmi)       // reset hdmi
+	admin.POST("/vm/hdmi/enable", service.EnableHdmi)   // enable hdmi
+	admin.POST("/vm/hdmi/disable", service.DisableHdmi) // disable hdmi
+	admin.POST("/vm/hdmi/timeout", service.SetHdmiIdleTimeout)
 
-	api.GET("/vm/ssh", service.GetSSHState)         // get SSH state
-	api.POST("/vm/ssh/enable", service.EnableSSH)   // enable SSH
-	api.POST("/vm/ssh/disable", service.DisableSSH) // disable SSH
+	admin.GET("/vm/ssh", service.GetSSHState)         // get SSH state
+	admin.POST("/vm/ssh/enable", service.EnableSSH)   // enable SSH
+	admin.POST("/vm/ssh/disable", service.DisableSSH) // disable SSH
 
-	api.GET("/vm/swap", service.GetSwap)  // get swap file size
-	api.POST("/vm/swap", service.SetSwap) // set swap file size
+	admin.GET("/vm/swap", service.GetSwap)  // get swap file size
+	admin.POST("/vm/swap", service.SetSwap) // set swap file size
 
-	api.GET("/vm/mouse-jiggler", service.GetMouseJiggler)   // get mouse jiggler
-	api.POST("/vm/mouse-jiggler/", service.SetMouseJiggler) // set mouse jiggler
+	admin.GET("/vm/mouse-jiggler", service.GetMouseJiggler)   // get mouse jiggler
+	admin.POST("/vm/mouse-jiggler/", service.SetMouseJiggler) // set mouse jiggler
 
-	api.GET("/vm/hostname", service.GetHostname)  // Get Hostname
-	api.POST("/vm/hostname", service.SetHostname) // Set Hostname
+	api.GET("/vm/hostname", service.GetHostname)    // Get Hostname
+	admin.POST("/vm/hostname", service.SetHostname) // Set Hostname
 
-	api.GET("/vm/web-title", service.GetWebTitle)  // Get web title
-	api.POST("/vm/web-title", service.SetWebTitle) // Set web title
+	api.GET("/vm/web-title", service.GetWebTitle)    // Get web title
+	admin.POST("/vm/web-title", service.SetWebTitle) // Set web title
 
-	api.GET("/vm/mdns", service.GetMdnsState)         // get mDNS state
-	api.POST("/vm/mdns/enable", service.EnableMdns)   // enable mDNS
-	api.POST("/vm/mdns/disable", service.DisableMdns) // disable mDNS
+	admin.GET("/vm/mdns", service.GetMdnsState)         // get mDNS state
+	admin.POST("/vm/mdns/enable", service.EnableMdns)   // enable mDNS
+	admin.POST("/vm/mdns/disable", service.DisableMdns) // disable mDNS
 
-	api.POST("/vm/tls", service.SetTls) // enable/disable TLS
+	admin.POST("/vm/tls", service.SetTls) // enable/disable TLS
 
-	api.GET("/vm/autostart", service.GetAutostart)              // get autostart list
-	api.GET("/vm/autostart/:name", service.GetAutostartContent) // get autostart content
-	api.DELETE("/vm/autostart/:name", service.DeleteAutostart)  // delete autostart script
-	api.POST("/vm/autostart/:name", service.UploadAutostart)    // upload autostart script
+	admin.GET("/vm/autostart", service.GetAutostart)              // get autostart list
+	admin.GET("/vm/autostart/:name", service.GetAutostartContent) // get autostart content
+	admin.DELETE("/vm/autostart/:name", service.DeleteAutostart)  // delete autostart script
+	admin.POST("/vm/autostart/:name", service.UploadAutostart)    // upload autostart script
 
-	api.POST("/vm/system/reboot", service.Reboot) // reboot system
+	admin.POST("/vm/system/reboot", service.Reboot) // reboot system
 }

server/service/application/archive.go

@@ -0,0 +1,203 @@
+package application
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"errors"
+	"fmt"
+	"io"
+	"math"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+)
+
+type updateArchiveInfo struct {
+	root          string
+	expandedBytes uint64
+	entries       int
+}
+
+func inspectUpdateArchive(archivePath, expectedRoot string) (updateArchiveInfo, error) {
+	file, err := os.Open(archivePath)
+	if err != nil {
+		return updateArchiveInfo{}, err
+	}
+	defer file.Close()
+	reader, err := gzip.NewReader(file)
+	if err != nil {
+		return updateArchiveInfo{}, fmt.Errorf("open gzip archive: %w", err)
+	}
+	defer reader.Close()
+
+	info := updateArchiveInfo{root: expectedRoot}
+	seen := make(map[string]struct{})
+	hasRoot, hasVersion := false, false
+	tarReader := tar.NewReader(reader)
+	for {
+		header, err := tarReader.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return updateArchiveInfo{}, fmt.Errorf("read tar archive: %w", err)
+		}
+		name, err := validateArchiveHeader(header, expectedRoot)
+		if err != nil {
+			return updateArchiveInfo{}, err
+		}
+		if _, ok := seen[name]; ok {
+			return updateArchiveInfo{}, fmt.Errorf("duplicate archive entry %q", name)
+		}
+		seen[name] = struct{}{}
+		info.entries++
+		if info.entries > maxArchiveEntries {
+			return updateArchiveInfo{}, fmt.Errorf("update archive has more than %d entries", maxArchiveEntries)
+		}
+		if name == expectedRoot && header.Typeflag == tar.TypeDir {
+			hasRoot = true
+		}
+		if name == expectedRoot+"/version" && isRegularType(header.Typeflag) {
+			hasVersion = true
+		}
+		if isRegularType(header.Typeflag) {
+			if header.Size < 0 {
+				return updateArchiveInfo{}, fmt.Errorf("negative archive file size")
+			}
+			size := uint64(header.Size)
+			if size > maxExpandedSize-info.expandedBytes {
+				return updateArchiveInfo{}, fmt.Errorf("update archive expanded size exceeds %d bytes", maxExpandedSize)
+			}
+			if info.expandedBytes > math.MaxUint64-size {
+				return updateArchiveInfo{}, fmt.Errorf("update archive expanded size overflow")
+			}
+			info.expandedBytes += size
+		}
+	}
+	if !hasRoot {
+		return updateArchiveInfo{}, fmt.Errorf("invalid update package layout: missing top-level directory")
+	}
+	if !hasVersion {
+		return updateArchiveInfo{}, fmt.Errorf("invalid update package layout: missing version file")
+	}
+	return info, nil
+}
+
+func extractUpdateArchive(archivePath, destDir, expectedRoot string) (string, error) {
+	file, err := os.Open(archivePath)
+	if err != nil {
+		return "", err
+	}
+	defer file.Close()
+	reader, err := gzip.NewReader(file)
+	if err != nil {
+		return "", fmt.Errorf("open gzip archive: %w", err)
+	}
+	defer reader.Close()
+
+	seen := make(map[string]struct{})
+	entries := 0
+	expanded := uint64(0)
+	tarReader := tar.NewReader(reader)
+	for {
+		header, err := tarReader.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return "", fmt.Errorf("read tar archive: %w", err)
+		}
+		name, err := validateArchiveHeader(header, expectedRoot)
+		if err != nil {
+			return "", err
+		}
+		if _, ok := seen[name]; ok {
+			return "", fmt.Errorf("duplicate archive entry %q", name)
+		}
+		seen[name] = struct{}{}
+		entries++
+		if entries > maxArchiveEntries {
+			return "", fmt.Errorf("update archive has more than %d entries", maxArchiveEntries)
+		}
+
+		filename := filepath.Join(destDir, filepath.FromSlash(name))
+		switch header.Typeflag {
+		case tar.TypeDir:
+			if err := os.MkdirAll(filename, 0o755); err != nil {
+				return "", fmt.Errorf("create archive directory: %w", err)
+			}
+		case tar.TypeReg, tar.TypeRegA:
+			if header.Size < 0 {
+				return "", fmt.Errorf("negative archive file size")
+			}
+			size := uint64(header.Size)
+			if size > maxExpandedSize-expanded {
+				return "", fmt.Errorf("update archive expanded size exceeds %d bytes", maxExpandedSize)
+			}
+			expanded += size
+			if err := os.MkdirAll(filepath.Dir(filename), 0o755); err != nil {
+				return "", fmt.Errorf("create archive parent directory: %w", err)
+			}
+			out, err := os.OpenFile(filename, os.O_WRONLY|os.O_CREATE|os.O_EXCL, os.FileMode(header.Mode)&0o777)
+			if err != nil {
+				return "", fmt.Errorf("create archive file: %w", err)
+			}
+			written, copyErr := io.CopyN(out, tarReader, header.Size)
+			closeErr := out.Close()
+			if copyErr != nil {
+				return "", fmt.Errorf("write archive file: %w", copyErr)
+			}
+			if written != header.Size {
+				return "", fmt.Errorf("truncated archive file %q", name)
+			}
+			if closeErr != nil {
+				return "", fmt.Errorf("close archive file: %w", closeErr)
+			}
+		}
+	}
+	return filepath.Join(destDir, expectedRoot), nil
+}
+
+func validateArchiveHeader(header *tar.Header, expectedRoot string) (string, error) {
+	if header.Name == "" || path.IsAbs(header.Name) {
+		return "", fmt.Errorf("invalid archive path %q", header.Name)
+	}
+	name := path.Clean(header.Name)
+	if name == "." || name == ".." || strings.HasPrefix(name, "../") {
+		return "", fmt.Errorf("invalid archive path %q", header.Name)
+	}
+	if name != expectedRoot && !strings.HasPrefix(name, expectedRoot+"/") {
+		return "", fmt.Errorf("invalid update package layout: entry %q is outside %s", header.Name, expectedRoot)
+	}
+	if !isRegularType(header.Typeflag) && header.Typeflag != tar.TypeDir {
+		return "", fmt.Errorf("unsupported archive entry type for %q", header.Name)
+	}
+	return name, nil
+}
+
+func isRegularType(typeFlag byte) bool {
+	return typeFlag == tar.TypeReg || typeFlag == tar.TypeRegA
+}
+
+func validateExtractedPackage(rootDir, expectedVersion string) error {
+	version, err := os.ReadFile(filepath.Join(rootDir, "version"))
+	if err != nil {
+		return fmt.Errorf("invalid update package layout: read version: %w", err)
+	}
+	if strings.TrimSpace(string(version)) != expectedVersion {
+		return fmt.Errorf("invalid update package layout: version mismatch")
+	}
+	for _, required := range []string{
+		"version",
+		"server/NanoKVM-Server",
+		"kvm_system/kvm_system",
+		"system/init.d/S95nanokvm",
+	} {
+		info, err := os.Stat(filepath.Join(rootDir, filepath.FromSlash(required)))
+		if err != nil || !info.Mode().IsRegular() {
+			return fmt.Errorf("invalid update package layout: missing required file %s", required)
+		}
+	}
+	return nil
+}

server/service/application/archive_test.go

@@ -0,0 +1,90 @@
+package application
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+type archiveEntry struct {
+	name     string
+	typeFlag byte
+	data     string
+}
+
+func writeTestArchive(t *testing.T, entries []archiveEntry) string {
+	t.Helper()
+	file := filepath.Join(t.TempDir(), "update.tar.gz")
+	out, err := os.Create(file)
+	if err != nil {
+		t.Fatal(err)
+	}
+	gzipWriter := gzip.NewWriter(out)
+	tarWriter := tar.NewWriter(gzipWriter)
+	for _, entry := range entries {
+		header := &tar.Header{Name: entry.name, Typeflag: entry.typeFlag, Mode: 0o755}
+		if entry.typeFlag == tar.TypeReg || entry.typeFlag == tar.TypeRegA {
+			header.Size = int64(len(entry.data))
+		}
+		if err := tarWriter.WriteHeader(header); err != nil {
+			t.Fatal(err)
+		}
+		if entry.data != "" {
+			if _, err := tarWriter.Write([]byte(entry.data)); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+	if err := tarWriter.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := gzipWriter.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := out.Close(); err != nil {
+		t.Fatal(err)
+	}
+	return file
+}
+
+func TestInspectArchiveRejectsUnsafeEntries(t *testing.T) {
+	root := "nanokvm_1.2.3"
+	for _, entry := range []archiveEntry{
+		{name: "../escape", typeFlag: tar.TypeReg, data: "x"},
+		{name: "/escape", typeFlag: tar.TypeReg, data: "x"},
+		{name: root + "/link", typeFlag: tar.TypeSymlink},
+	} {
+		archive := writeTestArchive(t, []archiveEntry{{name: root, typeFlag: tar.TypeDir}, entry})
+		if _, err := inspectUpdateArchive(archive, root); err == nil {
+			t.Fatalf("unsafe entry %+v was accepted", entry)
+		}
+	}
+}
+
+func TestInspectAndExtractArchive(t *testing.T) {
+	root := "nanokvm_1.2.3"
+	archive := writeTestArchive(t, []archiveEntry{
+		{name: root, typeFlag: tar.TypeDir},
+		{name: root + "/version", typeFlag: tar.TypeReg, data: "1.2.3\n"},
+		{name: root + "/server/NanoKVM-Server", typeFlag: tar.TypeReg, data: "server"},
+		{name: root + "/kvm_system/kvm_system", typeFlag: tar.TypeReg, data: "system"},
+		{name: root + "/system/init.d/S95nanokvm", typeFlag: tar.TypeReg, data: "init"},
+	})
+	info, err := inspectUpdateArchive(archive, root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.expandedBytes != 22 { // data totals: 6 + 6 + 6 + 4
+		t.Fatalf("unexpected expanded size %d", info.expandedBytes)
+	}
+	destination := t.TempDir()
+	extracted, err := extractUpdateArchive(archive, destination, root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := validateExtractedPackage(extracted, "1.2.3"); err != nil {
+		t.Fatal(err)
+	}
+}

server/service/application/install.go

@@ -31,17 +31,12 @@ func releaseUpdateLock() {
 	isUpdating = false
 }
 
-func installPackage(source string) error {
-	dir, err := utils.UnTarGz(source, CacheDir)
-	if err != nil {
-		return fmt.Errorf("failed to decompress app: %w", err)
-	}
-
+func installPreparedPackage(sourceDir string) error {
 	if err := backupCurrentApp(); err != nil {
 		return err
 	}
 
-	if err := applyUpdate(dir); err != nil {
+	if err := applyUpdate(sourceDir); err != nil {
 		return err
 	}
 

server/service/application/progress_writer.go

@@ -7,11 +7,13 @@ import (
 	"strings"
 	"time"
 
+	"NanoKVM-Server/utils"
+
 	log "github.com/sirupsen/logrus"
 )
 
 const (
-	sentinelPath       = "/tmp/.download_in_progress"
+	sentinelPath       = utils.TransferSentinelPath
 	tickerInterval     = 2500 * time.Millisecond
 	sentinelPermission = 0644
 )

server/service/application/service.go

@@ -7,6 +7,14 @@ const (
 	AppDir    = "/kvmapp"
 	BackupDir = "/root/old"
 	CacheDir  = "/root/.kvmcache"
+
+	updateWorkspacePrefix = "nanokvm-update-"
+	cacheDirMode          = 0o700
+	maxPackageSize        = uint64(1 << 30)
+	maxExpandedSize       = uint64(2 << 30)
+	maxArchiveEntries     = 100_000
+	minFreeReserve        = uint64(128 << 20)
+	freeReservePercent    = uint64(5)
 )
 
 type Service struct{}

server/service/application/storage.go

@@ -0,0 +1,103 @@
+package application
+
+import (
+	"errors"
+	"fmt"
+	"math"
+	"os"
+	"path/filepath"
+
+	"golang.org/x/sys/unix"
+)
+
+var ErrInsufficientStorage = errors.New("insufficient storage")
+
+type filesystemSpace struct {
+	total     uint64
+	available uint64
+}
+
+func getFilesystemSpace(path string) (filesystemSpace, error) {
+	var stat unix.Statfs_t
+	if err := unix.Statfs(path, &stat); err != nil {
+		return filesystemSpace{}, fmt.Errorf("stat filesystem %s: %w", path, err)
+	}
+	return filesystemSpaceFromStats(uint64(stat.Blocks), uint64(stat.Bavail), uint64(stat.Bsize))
+}
+
+func filesystemSpaceFromStats(blocks, availableBlocks, blockSize uint64) (filesystemSpace, error) {
+	if blockSize != 0 && (blocks > math.MaxUint64/blockSize || availableBlocks > math.MaxUint64/blockSize) {
+		return filesystemSpace{}, fmt.Errorf("filesystem size overflow")
+	}
+	return filesystemSpace{total: blocks * blockSize, available: availableBlocks * blockSize}, nil
+}
+
+func reserveBytes(total uint64) uint64 {
+	percent := total / 100 * freeReservePercent
+	percent += total % 100 * freeReservePercent / 100
+	if percent > minFreeReserve {
+		return percent
+	}
+	return minFreeReserve
+}
+
+func hasFreeSpace(space filesystemSpace, payload uint64) (bool, uint64, error) {
+	reserve := reserveBytes(space.total)
+	if payload > math.MaxUint64-reserve {
+		return false, 0, fmt.Errorf("storage requirement overflow")
+	}
+	required := payload + reserve
+	return space.available >= required, required, nil
+}
+
+func ensureFreeSpace(path string, payloadBytes uint64) error {
+	space, err := getFilesystemSpace(path)
+	if err != nil {
+		return err
+	}
+	ok, required, err := hasFreeSpace(space, payloadBytes)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return fmt.Errorf("%w: need %d MiB including reserve, %d MiB available on %s", ErrInsufficientStorage, required>>20, space.available>>20, path)
+	}
+	return nil
+}
+
+func ensureExpandedSpace(path string, expandedBytes uint64) error {
+	// Keep the last known-good backup until the new package is fully prepared.
+	// Reclaiming it here can leave the device without rollback material even
+	// when extraction later fails or the reclaimed space is still insufficient.
+	return ensureFreeSpace(path, expandedBytes)
+}
+
+func ensureInstallFilesystem(workspaceDir, appDir, backupDir string) error {
+	backupPath := backupDir
+	if _, err := os.Stat(backupPath); err != nil {
+		if !os.IsNotExist(err) {
+			return fmt.Errorf("stat backup path %s: %w", backupPath, err)
+		}
+		backupPath = filepath.Dir(backupPath)
+	}
+
+	// AppDir already exists (prepareCacheForUpdate verifies it), so stat the
+	// directory itself. Its parent can be on another filesystem when AppDir is
+	// a mount point.
+	paths := []string{workspaceDir, appDir, backupPath}
+	var device uint64
+	for i, path := range paths {
+		var stat unix.Stat_t
+		if err := unix.Stat(path, &stat); err != nil {
+			return fmt.Errorf("stat install filesystem %s: %w", path, err)
+		}
+		if i == 0 {
+			device = uint64(stat.Dev)
+			continue
+		}
+		if uint64(stat.Dev) != device {
+			return fmt.Errorf("update workspace, application and backup must be on the same filesystem")
+		}
+	}
+	return nil
+}

server/service/application/storage_test.go

@@ -0,0 +1,46 @@
+package application
+
+import (
+	"math"
+	"path/filepath"
+	"testing"
+)
+
+func TestReserveBytesAndSpaceBoundary(t *testing.T) {
+	if got := reserveBytes(1 << 30); got != minFreeReserve {
+		t.Fatalf("reserve for 1 GiB = %d, want %d", got, minFreeReserve)
+	}
+	if got := reserveBytes(4 << 30); got != 214748364 {
+		t.Fatalf("reserve for 4 GiB = %d, want 214748364", got)
+	}
+	space := filesystemSpace{total: 1 << 30, available: (1 << 20) + minFreeReserve}
+	ok, required, err := hasFreeSpace(space, 1<<20)
+	if err != nil || !ok || required != space.available {
+		t.Fatalf("boundary should fit: ok=%v required=%d err=%v", ok, required, err)
+	}
+	space.available--
+	ok, _, err = hasFreeSpace(space, 1<<20)
+	if err != nil || ok {
+		t.Fatalf("one byte short should fail: ok=%v err=%v", ok, err)
+	}
+}
+
+func TestStorageOverflowIsRejected(t *testing.T) {
+	if _, err := filesystemSpaceFromStats(math.MaxUint64, 1, 2); err == nil {
+		t.Fatal("expected filesystem overflow")
+	}
+	if _, _, err := hasFreeSpace(filesystemSpace{total: 1}, math.MaxUint64); err == nil {
+		t.Fatal("expected requirement overflow")
+	}
+}
+
+func TestInstallFilesystemChecksAppMountPoint(t *testing.T) {
+	workspace := t.TempDir()
+	backup := filepath.Join(t.TempDir(), "backup")
+
+	// /proc is a mount point whose parent is /. Checking filepath.Dir(appDir)
+	// would therefore miss the cross-filesystem layout on a normal Linux host.
+	if err := ensureInstallFilesystem(workspace, "/proc", backup); err == nil {
+		t.Fatal("separate application mount point was accepted")
+	}
+}

server/service/application/update.go

@@ -8,6 +8,8 @@ import (
 	"net/http"
 	"os"
 	"os/exec"
+	"path/filepath"
+	"strings"
 	"time"
 
 	"github.com/gin-gonic/gin"
@@ -28,9 +30,9 @@ func (s *Service) Update(c *gin.Context) {
 		rsp.ErrRsp(c, -1, "update already in progress")
 		return
 	}
-	defer releaseUpdateLock()
 
 	if err := update(); err != nil {
+		releaseUpdateLock()
 		rsp.ErrRsp(c, -1, fmt.Sprintf("update failed: %s", err))
 		return
 	}
@@ -38,40 +40,75 @@ func (s *Service) Update(c *gin.Context) {
 	rsp.OkRsp(c)
 	log.Debugf("update application success")
 
-	// Sleep for a second before restarting the device
+	go restartServices()
+}
+
+func restartServices() {
+	// Let the HTTP response reach the client before stopping the server.
 	time.Sleep(1 * time.Second)
 
-	_ = exec.Command("sh", "-c", "/etc/init.d/S95nanokvm restart").Run()
+	if err := exec.Command("/kvmapp/system/init.d/S95nanokvm", "restart").Run(); err != nil {
+		log.Errorf("failed to restart services after update: %v", err)
+	}
 }
 
 func update() error {
-	_ = os.RemoveAll(CacheDir)
-	_ = os.MkdirAll(CacheDir, 0o755)
-	defer func() {
-		_ = os.RemoveAll(CacheDir)
-	}()
-
-	// get latest information
 	latest, err := getLatest()
 	if err != nil {
 		return err
 	}
-
-	// download
-	target := fmt.Sprintf("%s/%s", CacheDir, latest.Name)
-	if err := download(latest.Url, target); err != nil {
-		log.Errorf("download app failed: %s", err)
+	if err := prepareCacheForUpdate(); err != nil {
+		return err
+	}
+	workspace, err := newUpdateWorkspace(CacheDir)
+	if err != nil {
+		return err
+	}
+	defer func() {
+		if err := workspace.Close(); err != nil {
+			log.Warnf("failed to clean update workspace %s: %v", workspace.dir, err)
+		}
+	}()
+	if err := ensureInstallFilesystem(workspace.dir, AppDir, BackupDir); err != nil {
+		return err
+	}
+	if err := preflightManifestSpace(workspace.dir, latest); err != nil {
+		return err
+	}
+
+	target := filepath.Join(workspace.dir, latest.Name)
+	downloadInfo, err := download(latest, target)
+	if err != nil {
+		log.Errorf("download app failed: %s", err)
+		return err
+	}
+	if err := validateDownloadedSize(latest, uint64(downloadInfo.Written)); err != nil {
 		return err
 	}
 
-	// check sha512
 	if err := checksum(target, latest.Sha512); err != nil {
 		log.Errorf("check sha512 failed: %s", err)
 		return err
 	}
-
-	// install
-	if err := installPackage(target); err != nil {
+	expectedRoot := strings.TrimSuffix(latest.Name, ".tar.gz")
+	info, err := inspectUpdateArchive(target, expectedRoot)
+	if err != nil {
+		return fmt.Errorf("inspect update package: %w", err)
+	}
+	if err := validateExpandedSize(latest, info.expandedBytes); err != nil {
+		return err
+	}
+	if err := ensureExpandedSpace(workspace.dir, info.expandedBytes); err != nil {
+		return err
+	}
+	sourceDir, err := extractUpdateArchive(target, workspace.dir, expectedRoot)
+	if err != nil {
+		return fmt.Errorf("extract update package: %w", err)
+	}
+	if err := validateExtractedPackage(sourceDir, latest.Version); err != nil {
+		return err
+	}
+	if err := installPreparedPackage(sourceDir); err != nil {
 		log.Errorf("failed to install package: %v", err)
 		return err
 	}
@@ -79,7 +116,7 @@ func update() error {
 	return nil
 }
 
-func download(url string, target string) (err error) {
+func download(latest *Latest, target string) (info utils.DownloadInfo, err error) {
 	for i := range maxTries {
 		log.Debugf("attempt #%d/%d", i+1, maxTries)
 		if i > 0 {
@@ -87,21 +124,26 @@ func download(url string, target string) (err error) {
 		}
 
 		var req *http.Request
-		req, err = http.NewRequest("GET", url, nil)
+		req, err = utils.NewAuthenticatedRequest("GET", latest.Url, nil)
 		if err != nil {
 			log.Errorf("new request err: %s", err)
 			continue
 		}
 
 		log.Debugf("update will be saved to: %s", target)
-		err = utils.Download(req, target)
+		info, err = utils.Download(req, target, int64(maxPackageSize), func(contentLength int64) error {
+			if latest.ManifestVersion == 2 && uint64(contentLength) != latest.SizeBytes {
+				return fmt.Errorf("update package size mismatch: manifest has %d bytes, response has %d", latest.SizeBytes, contentLength)
+			}
+			return ensureFreeSpace(filepath.Dir(target), uint64(contentLength))
+		})
 		if err != nil {
 			log.Errorf("downloading latest application failed, try again...")
 			continue
 		}
-		return nil
+		return info, nil
 	}
-	return err
+	return utils.DownloadInfo{}, err
 }
 
 func checksum(filePath string, expectedHash string) error {

server/service/application/update_offline.go

@@ -1,15 +1,17 @@
 package application
 
 import (
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/hex"
 	"fmt"
 	"io"
 	"mime/multipart"
+	"net/http"
 	"os"
-	"os/exec"
 	"path/filepath"
 	"regexp"
 	"strings"
-	"time"
 
 	"NanoKVM-Server/proto"
 	"github.com/gin-gonic/gin"
@@ -25,9 +27,9 @@ func (s *Service) OfflineUpdate(c *gin.Context) {
 		rsp.ErrRsp(c, -1, "update already in progress")
 		return
 	}
-	defer releaseUpdateLock()
 
 	if err := offlineUpdate(c); err != nil {
+		releaseUpdateLock()
 		rsp.ErrRsp(c, -1, fmt.Sprintf("update failed: %s", err))
 		return
 	}
@@ -35,21 +37,43 @@ func (s *Service) OfflineUpdate(c *gin.Context) {
 	rsp.OkRsp(c)
 	log.Debugf("offline update application success")
 
-	time.Sleep(1 * time.Second)
-	_ = exec.Command("sh", "-c", "/etc/init.d/S95nanokvm restart").Run()
+	go restartServices()
 }
 
 func offlineUpdate(c *gin.Context) error {
-	_ = os.RemoveAll(CacheDir)
-	_ = os.MkdirAll(CacheDir, 0o755)
-	defer func() {
-		_ = os.RemoveAll(CacheDir)
-	}()
-
-	if err := checkDownloadInProgress(); err != nil {
+	expectedSHA256, err := parseSHA256Checksum(c.GetHeader("X-SHA256-Checksum"))
+	if err != nil {
 		return err
 	}
 
+	if err := prepareCacheForUpdate(); err != nil {
+		return err
+	}
+	workspace, err := newUpdateWorkspace(CacheDir)
+	if err != nil {
+		return err
+	}
+	defer func() {
+		if err := workspace.Close(); err != nil {
+			log.Warnf("failed to clean update workspace %s: %v", workspace.dir, err)
+		}
+	}()
+	if err := ensureInstallFilesystem(workspace.dir, AppDir, BackupDir); err != nil {
+		return err
+	}
+
+	maxRequestBytes := int64(maxPackageSize) + (1 << 20)
+	contentLength := c.Request.ContentLength
+	if contentLength > maxRequestBytes {
+		return fmt.Errorf("offline update request exceeds %d bytes", maxRequestBytes)
+	}
+	if contentLength > 0 {
+		if err := ensureFreeSpace(workspace.dir, uint64(contentLength)); err != nil {
+			return err
+		}
+	}
+	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxRequestBytes)
+
 	if err := createSentinelFile(); err != nil {
 		return err
 	}
@@ -61,13 +85,35 @@ func offlineUpdate(c *gin.Context) error {
 		return fmt.Errorf("invalid multipart data: %w", err)
 	}
 
-	target, err := processUpload(reader, c.Request.ContentLength)
+	target, err := processUpload(reader, contentLength, workspace.dir)
 	if err != nil {
 		log.Errorf("failed to upload install package: %v", err)
 		return err
 	}
 
-	if err := installPackage(target); err != nil {
+	if err := verifySHA256Checksum(target, expectedSHA256); err != nil {
+		log.Errorf("failed to verify install package: %v", err)
+		return err
+	}
+
+	archiveName := filepath.Base(target)
+	expectedRoot := strings.TrimSuffix(archiveName, ".tar.gz")
+	expectedVersion := strings.TrimPrefix(expectedRoot, "nanokvm_")
+	info, err := inspectUpdateArchive(target, expectedRoot)
+	if err != nil {
+		return fmt.Errorf("inspect update package: %w", err)
+	}
+	if err := ensureExpandedSpace(workspace.dir, info.expandedBytes); err != nil {
+		return err
+	}
+	sourceDir, err := extractUpdateArchive(target, workspace.dir, expectedRoot)
+	if err != nil {
+		return fmt.Errorf("extract update package: %w", err)
+	}
+	if err := validateExtractedPackage(sourceDir, expectedVersion); err != nil {
+		return err
+	}
+	if err := installPreparedPackage(sourceDir); err != nil {
 		log.Errorf("failed to install package: %v", err)
 		return err
 	}
@@ -75,23 +121,71 @@ func offlineUpdate(c *gin.Context) error {
 	return nil
 }
 
-func checkDownloadInProgress() error {
-	if _, err := os.Stat(sentinelPath); err == nil {
-		log.Debug("Download in progress")
-		return fmt.Errorf("download already in progress")
+func parseSHA256Checksum(value string) ([]byte, error) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return nil, nil
 	}
+
+	checksum, err := hex.DecodeString(value)
+	if err != nil || len(checksum) != sha256.Size {
+		return nil, fmt.Errorf("invalid sha256 checksum")
+	}
+
+	return checksum, nil
+}
+
+func verifySHA256Checksum(filePath string, expected []byte) error {
+	if len(expected) == 0 {
+		return nil
+	}
+
+	file, err := os.Open(filePath)
+	if err != nil {
+		return fmt.Errorf("failed to open uploaded file: %w", err)
+	}
+	defer file.Close()
+
+	hasher := sha256.New()
+	if _, err := io.Copy(hasher, file); err != nil {
+		return fmt.Errorf("failed to calculate sha256 checksum: %w", err)
+	}
+
+	if subtle.ConstantTimeCompare(hasher.Sum(nil), expected) != 1 {
+		return fmt.Errorf("sha256 checksum mismatch")
+	}
+
 	return nil
 }
 
 func createSentinelFile() error {
-	if err := os.WriteFile(sentinelPath, []byte("downloading"), sentinelPermission); err != nil {
+	file, err := os.OpenFile(
+		sentinelPath,
+		os.O_WRONLY|os.O_CREATE|os.O_EXCL,
+		sentinelPermission,
+	)
+	if err != nil {
+		if os.IsExist(err) {
+			return fmt.Errorf("download already in progress")
+		}
 		log.Errorf("Failed to create sentinel file: %v", err)
 		return fmt.Errorf("failed to create sentinel file: %w", err)
 	}
+
+	if _, err := file.WriteString("downloading"); err != nil {
+		_ = file.Close()
+		_ = os.Remove(sentinelPath)
+		return fmt.Errorf("failed to initialize sentinel file: %w", err)
+	}
+	if err := file.Close(); err != nil {
+		_ = os.Remove(sentinelPath)
+		return fmt.Errorf("failed to close sentinel file: %w", err)
+	}
+
 	return nil
 }
 
-func processUpload(reader *multipart.Reader, contentLength int64) (string, error) {
+func processUpload(reader *multipart.Reader, contentLength int64, workspaceDir string) (string, error) {
 	var outPath string
 
 	for {
@@ -106,8 +200,11 @@ func processUpload(reader *multipart.Reader, contentLength int64) (string, error
 		if part.FormName() != "file" {
 			continue
 		}
+		if outPath != "" {
+			return "", fmt.Errorf("multiple files uploaded")
+		}
 
-		outPath, err = saveUploadedFile(part, contentLength)
+		outPath, err = saveUploadedFile(part, contentLength, workspaceDir)
 		if err != nil {
 			return "", err
 		}
@@ -120,7 +217,7 @@ func processUpload(reader *multipart.Reader, contentLength int64) (string, error
 	return outPath, nil
 }
 
-func saveUploadedFile(part *multipart.Part, contentLength int64) (string, error) {
+func saveUploadedFile(part *multipart.Part, contentLength int64, workspaceDir string) (string, error) {
 	filename := part.FileName()
 	if filename == "" {
 		return "", fmt.Errorf("no filename provided")
@@ -130,19 +227,36 @@ func saveUploadedFile(part *multipart.Part, contentLength int64) (string, error)
 		return "", err
 	}
 
-	outPath := filepath.Join(CacheDir, filename)
-	out, err := os.Create(outPath)
+	outPath := filepath.Join(workspaceDir, filename)
+	out, err := os.OpenFile(outPath, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
 	if err != nil {
 		return "", fmt.Errorf("failed to create output file: %w", err)
 	}
-	defer out.Close()
+	success := false
+	defer func() {
+		_ = out.Close()
+		if !success {
+			_ = os.Remove(outPath)
+		}
+	}()
 
+	if contentLength < 0 {
+		contentLength = 0
+	}
 	pw := newProgressWriter(out, contentLength)
 	defer pw.Stop()
 
-	if _, err := io.Copy(pw, part); err != nil {
+	written, err := io.Copy(pw, io.LimitReader(part, int64(maxPackageSize)+1))
+	if err != nil {
 		return "", fmt.Errorf("failed to write file: %w", err)
 	}
+	if written > int64(maxPackageSize) {
+		return "", fmt.Errorf("uploaded package exceeds %d bytes", maxPackageSize)
+	}
+	if err := out.Close(); err != nil {
+		return "", fmt.Errorf("failed to close output file: %w", err)
+	}
+	success = true
 
 	return outPath, nil
 }
@@ -167,6 +281,9 @@ func validateFilename(filename string) error {
 		log.Warnf("Invalid filename characters: %s", filename)
 		return fmt.Errorf("invalid filename: contains invalid characters")
 	}
+	if !packageNamePattern.MatchString(filename) {
+		return fmt.Errorf("invalid update package name")
+	}
 
 	return nil
 }

server/service/application/update_server.go

@@ -0,0 +1,212 @@
+package application
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+
+	"NanoKVM-Server/proto"
+
+	"github.com/gin-gonic/gin"
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	UpdateServerConfigFile = "/etc/kvm/application-update.json"
+	maxUpdateServerURLSize = 2048
+)
+
+var (
+	updateServerConfigMu   sync.Mutex
+	updateServerConfigPath = UpdateServerConfigFile
+)
+
+type UpdateServerConfig struct {
+	Enabled bool   `json:"enabled"`
+	URL     string `json:"url"`
+}
+
+func defaultUpdateServerConfig() UpdateServerConfig {
+	return UpdateServerConfig{URL: StableURL}
+}
+
+func (s *Service) GetUpdateServer(c *gin.Context) {
+	var rsp proto.Response
+
+	cfg, err := loadUpdateServerConfig()
+	if err != nil {
+		log.Errorf("failed to load update server config: %s", err)
+		rsp.ErrRsp(c, -1, "failed to load update server config")
+		return
+	}
+
+	rsp.OkRspWithData(c, &proto.GetUpdateServerRsp{
+		Enabled: cfg.Enabled,
+		URL:     cfg.URL,
+	})
+}
+
+func (s *Service) SetUpdateServer(c *gin.Context) {
+	var req proto.SetUpdateServerReq
+	var rsp proto.Response
+
+	// Avoid the shared request logger because the URL may contain credentials.
+	if err := c.ShouldBind(&req); err != nil || req.Enabled == nil {
+		rsp.ErrRsp(c, -1, "invalid arguments")
+		return
+	}
+
+	normalizedURL, err := normalizeUpdateServerURL(req.URL)
+	if err != nil {
+		rsp.ErrRsp(c, -2, err.Error())
+		return
+	}
+	if *req.Enabled && normalizedURL == "" {
+		rsp.ErrRsp(c, -2, "update server URL is required")
+		return
+	}
+	if normalizedURL == "" {
+		normalizedURL = StableURL
+	}
+
+	cfg := UpdateServerConfig{Enabled: *req.Enabled, URL: normalizedURL}
+	if err := saveUpdateServerConfig(cfg); err != nil {
+		log.Errorf("failed to save update server config: %s", err)
+		rsp.ErrRsp(c, -3, "failed to save update server config")
+		return
+	}
+
+	rsp.OkRspWithData(c, &proto.GetUpdateServerRsp{
+		Enabled: cfg.Enabled,
+		URL:     cfg.URL,
+	})
+}
+
+func resolveUpdateBaseURL() (string, error) {
+	cfg, err := loadUpdateServerConfig()
+	if err != nil {
+		return "", err
+	}
+	if cfg.Enabled {
+		return cfg.URL, nil
+	}
+	if isPreviewEnabled() {
+		return PreviewURL, nil
+	}
+	return StableURL, nil
+}
+
+func normalizeUpdateServerURL(raw string) (string, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return "", nil
+	}
+	if len(raw) > maxUpdateServerURLSize {
+		return "", errors.New("update server URL is too long")
+	}
+
+	parsed, err := url.Parse(raw)
+	if err != nil || parsed.Host == "" || (parsed.Scheme != "http" && parsed.Scheme != "https") {
+		return "", errors.New("invalid update server URL")
+	}
+	if parsed.RawQuery != "" || parsed.Fragment != "" {
+		return "", errors.New("update server URL must not contain a query or fragment")
+	}
+	if strings.HasSuffix(strings.TrimRight(parsed.Path, "/"), "/latest.json") {
+		return "", errors.New("enter the update server directory, not latest.json")
+	}
+
+	parsed.Path = strings.TrimRight(parsed.Path, "/")
+	return parsed.String(), nil
+}
+
+func loadUpdateServerConfig() (UpdateServerConfig, error) {
+	updateServerConfigMu.Lock()
+	defer updateServerConfigMu.Unlock()
+
+	return loadUpdateServerConfigFromPath(updateServerConfigPath)
+}
+
+func loadUpdateServerConfigFromPath(path string) (UpdateServerConfig, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return defaultUpdateServerConfig(), nil
+		}
+		return UpdateServerConfig{}, err
+	}
+
+	var cfg UpdateServerConfig
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return UpdateServerConfig{}, fmt.Errorf("decode update server config: %w", err)
+	}
+
+	normalizedURL, err := normalizeUpdateServerURL(cfg.URL)
+	if err != nil {
+		return UpdateServerConfig{}, err
+	}
+	if normalizedURL == "" {
+		normalizedURL = StableURL
+	}
+	cfg.URL = normalizedURL
+	return cfg, nil
+}
+
+func saveUpdateServerConfig(cfg UpdateServerConfig) error {
+	updateServerConfigMu.Lock()
+	defer updateServerConfigMu.Unlock()
+
+	return saveUpdateServerConfigToPath(updateServerConfigPath, cfg)
+}
+
+func saveUpdateServerConfigToPath(path string, cfg UpdateServerConfig) error {
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return fmt.Errorf("create update server config directory: %w", err)
+	}
+
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		return fmt.Errorf("encode update server config: %w", err)
+	}
+	data = append(data, '\n')
+
+	tmp, err := os.CreateTemp(dir, ".application-update.json.*")
+	if err != nil {
+		return fmt.Errorf("create temporary update server config: %w", err)
+	}
+	tmpPath := tmp.Name()
+	defer func() { _ = os.Remove(tmpPath) }()
+
+	if err := tmp.Chmod(0o600); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("set update server config permissions: %w", err)
+	}
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("write update server config: %w", err)
+	}
+	if err := tmp.Sync(); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("sync update server config: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("close update server config: %w", err)
+	}
+	if err := os.Rename(tmpPath, path); err != nil {
+		return fmt.Errorf("replace update server config: %w", err)
+	}
+
+	directory, err := os.Open(dir)
+	if err == nil {
+		_ = directory.Sync()
+		_ = directory.Close()
+	}
+
+	return nil
+}

server/service/application/version.go

@@ -1,28 +1,46 @@
 package application
 
 import (
+	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"os"
+	"regexp"
 	"strings"
 	"time"
 
 	"NanoKVM-Server/proto"
+	"NanoKVM-Server/utils"
 
 	"github.com/gin-gonic/gin"
 	log "github.com/sirupsen/logrus"
 )
 
 type Latest struct {
-	Version string `json:"version"`
-	Name    string `json:"name"`
-	Sha512  string `json:"sha512"`
-	Size    uint   `json:"size"`
-	Url     string `json:"url"`
+	ManifestVersion   int    `json:"manifest_version,omitempty"`
+	Version           string `json:"version"`
+	Name              string `json:"name"`
+	Sha512            string `json:"sha512"`
+	LegacySize        uint64 `json:"size"`
+	SizeBytes         uint64 `json:"size_bytes,omitempty"`
+	UnpackedSizeBytes uint64 `json:"unpacked_size_bytes,omitempty"`
+	Url               string `json:"-"`
 }
 
+const (
+	maxLatestJSONSize = 64 * 1024
+)
+
+var (
+	latestClient       = utils.NewUpdateHTTPClient(15 * time.Second)
+	packageNamePattern = regexp.MustCompile(`^nanokvm_[0-9]+\.[0-9]+\.[0-9]+\.tar\.gz$`)
+	versionPattern     = regexp.MustCompile(`^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$`)
+)
+
 func (s *Service) GetVersion(c *gin.Context) {
 	var rsp proto.Response
 
@@ -39,9 +57,12 @@ func (s *Service) GetVersion(c *gin.Context) {
 	// latest version
 	latestVersion := ""
 	latest, err := getLatest()
-	if err == nil && latest != nil {
-		latestVersion = latest.Version
+	if err != nil {
+		log.Errorf("failed to get latest version: %s", err)
+		rsp.ErrRsp(c, -1, "failed to query latest version")
+		return
 	}
+	latestVersion = latest.Version
 
 	rsp.OkRspWithData(c, &proto.GetVersionRsp{
 		Current: currentVersion,
@@ -50,23 +71,37 @@ func (s *Service) GetVersion(c *gin.Context) {
 }
 
 func getLatest() (*Latest, error) {
-	baseURL := StableURL
-	if isPreviewEnabled() {
-		baseURL = PreviewURL
+	baseURL, err := resolveUpdateBaseURL()
+	if err != nil {
+		return nil, err
 	}
 
-	url := fmt.Sprintf("%s/latest.json?now=%d", baseURL, time.Now().Unix())
-
-	resp, err := http.Get(url)
+	manifestURL, err := joinUpdateURL(baseURL, "latest.json")
 	if err != nil {
-		log.Debugf("failed to request version: %v", err)
 		return nil, err
 	}
+	parsedManifestURL, err := url.Parse(manifestURL)
+	if err != nil {
+		return nil, err
+	}
+	query := parsedManifestURL.Query()
+	query.Set("now", fmt.Sprintf("%d", time.Now().Unix()))
+	parsedManifestURL.RawQuery = query.Encode()
+
+	request, err := utils.NewAuthenticatedRequest("GET", parsedManifestURL.String(), nil)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := latestClient.Do(request)
+	if err != nil {
+		log.Debugf("failed to request version from %s", parsedManifestURL.Redacted())
+		return nil, errors.New("update server is inaccessible")
+	}
 	defer func() {
 		_ = resp.Body.Close()
 	}()
 
-	body, err := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(io.LimitReader(resp.Body, maxLatestJSONSize+1))
 	if err != nil {
 		log.Errorf("failed to read response: %v", err)
 		return nil, err
@@ -76,15 +111,86 @@ func getLatest() (*Latest, error) {
 		log.Errorf("server responded with status code: %d", resp.StatusCode)
 		return nil, fmt.Errorf("status code %d", resp.StatusCode)
 	}
+	if len(body) > maxLatestJSONSize {
+		return nil, fmt.Errorf("latest manifest exceeds %d bytes", maxLatestJSONSize)
+	}
 
 	var latest Latest
 	if err := json.Unmarshal(body, &latest); err != nil {
 		log.Errorf("failed to unmarshal response: %s", err)
 		return nil, err
 	}
+	if err := validateLatest(&latest); err != nil {
+		return nil, err
+	}
 
-	latest.Url = fmt.Sprintf("%s/%s", baseURL, latest.Name)
+	latest.Url, err = joinUpdateURL(baseURL, latest.Name)
+	if err != nil {
+		return nil, err
+	}
 
 	log.Debugf("get application latest version: %s", latest.Version)
 	return &latest, nil
 }
+
+func joinUpdateURL(baseURL string, element string) (string, error) {
+	joined, err := url.JoinPath(baseURL, element)
+	if err != nil {
+		return "", fmt.Errorf("join update URL: %w", err)
+	}
+	return joined, nil
+}
+
+func validateLatest(latest *Latest) error {
+	if !versionPattern.MatchString(latest.Version) {
+		return errors.New("invalid latest version")
+	}
+	if !packageNamePattern.MatchString(latest.Name) {
+		return errors.New("invalid update package name")
+	}
+	digest, err := base64.StdEncoding.DecodeString(latest.Sha512)
+	if err != nil || len(digest) != 64 {
+		return errors.New("invalid update package sha512")
+	}
+	if latest.LegacySize == 0 {
+		return errors.New("invalid update package size")
+	}
+	switch latest.ManifestVersion {
+	case 0, 1:
+		return nil
+	case 2:
+		if latest.SizeBytes == 0 || latest.SizeBytes > maxPackageSize {
+			return errors.New("invalid update package size_bytes")
+		}
+		if latest.UnpackedSizeBytes == 0 || latest.UnpackedSizeBytes > maxExpandedSize {
+			return errors.New("invalid update package unpacked_size_bytes")
+		}
+		return nil
+	default:
+		return errors.New("unsupported update manifest version")
+	}
+}
+
+func preflightManifestSpace(path string, latest *Latest) error {
+	if latest.ManifestVersion != 2 {
+		return nil
+	}
+	return ensureFreeSpace(path, latest.SizeBytes)
+}
+
+func validateDownloadedSize(latest *Latest, written uint64) error {
+	if written > maxPackageSize {
+		return fmt.Errorf("update package exceeds %d bytes", maxPackageSize)
+	}
+	if latest.ManifestVersion == 2 && written != latest.SizeBytes {
+		return fmt.Errorf("update package size mismatch: expected %d bytes, got %d", latest.SizeBytes, written)
+	}
+	return nil
+}
+
+func validateExpandedSize(latest *Latest, expanded uint64) error {
+	if latest.ManifestVersion == 2 && expanded != latest.UnpackedSizeBytes {
+		return fmt.Errorf("update package expanded size mismatch: expected %d bytes, got %d", latest.UnpackedSizeBytes, expanded)
+	}
+	return nil
+}

server/service/application/version_test.go

@@ -0,0 +1,46 @@
+package application
+
+import (
+	"crypto/sha512"
+	"encoding/base64"
+	"testing"
+)
+
+func validLatest() Latest {
+	digest := sha512.Sum512([]byte("package"))
+	return Latest{
+		Version: "1.2.3", Name: "nanokvm_1.2.3.tar.gz",
+		Sha512: base64.StdEncoding.EncodeToString(digest[:]), LegacySize: 1,
+	}
+}
+
+func TestValidateLatestV1DoesNotInterpretLegacySizeAsBytes(t *testing.T) {
+	latest := validLatest()
+	latest.LegacySize = 15048 // historic stable manifests used a non-byte value
+	if err := validateLatest(&latest); err != nil {
+		t.Fatal(err)
+	}
+	if err := validateDownloadedSize(&latest, 15406125); err != nil {
+		t.Fatalf("v1 must not require equality with legacy size: %v", err)
+	}
+}
+
+func TestValidateLatestV2RequiresExactByteFields(t *testing.T) {
+	latest := validLatest()
+	latest.ManifestVersion = 2
+	latest.SizeBytes = 100
+	latest.UnpackedSizeBytes = 200
+	if err := validateLatest(&latest); err != nil {
+		t.Fatal(err)
+	}
+	if err := validateDownloadedSize(&latest, 99); err == nil {
+		t.Fatal("v2 size mismatch was accepted")
+	}
+	if err := validateExpandedSize(&latest, 199); err == nil {
+		t.Fatal("v2 expanded size mismatch was accepted")
+	}
+	latest.ManifestVersion = 3
+	if err := validateLatest(&latest); err == nil {
+		t.Fatal("unknown manifest version was accepted")
+	}
+}

server/service/application/workspace.go

@@ -0,0 +1,69 @@
+package application
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+type updateWorkspace struct {
+	dir string
+}
+
+func newUpdateWorkspace(baseDir string) (*updateWorkspace, error) {
+	if err := os.MkdirAll(baseDir, cacheDirMode); err != nil {
+		return nil, fmt.Errorf("create update cache: %w", err)
+	}
+	if err := os.Chmod(baseDir, cacheDirMode); err != nil {
+		return nil, fmt.Errorf("chmod update cache: %w", err)
+	}
+	dir, err := os.MkdirTemp(baseDir, updateWorkspacePrefix)
+	if err != nil {
+		return nil, fmt.Errorf("create update workspace: %w", err)
+	}
+	return &updateWorkspace{dir: dir}, nil
+}
+
+func (w *updateWorkspace) Close() error {
+	return os.RemoveAll(w.dir)
+}
+
+func cleanupStaleWorkspaces(baseDir string) error {
+	entries, err := os.ReadDir(baseDir)
+	if os.IsNotExist(err) {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	for _, entry := range entries {
+		if !strings.HasPrefix(entry.Name(), updateWorkspacePrefix) {
+			continue
+		}
+		if err := os.RemoveAll(filepath.Join(baseDir, entry.Name())); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func prepareCacheForUpdate() error {
+	info, err := os.Stat(AppDir)
+	if err != nil {
+		return fmt.Errorf("stat current application: %w", err)
+	}
+	if !info.IsDir() {
+		return fmt.Errorf("current application is not a directory")
+	}
+	if err := os.MkdirAll(CacheDir, cacheDirMode); err != nil {
+		return fmt.Errorf("create update cache: %w", err)
+	}
+	if err := os.Chmod(CacheDir, cacheDirMode); err != nil {
+		return fmt.Errorf("chmod update cache: %w", err)
+	}
+	if err := cleanupStaleWorkspaces(CacheDir); err != nil {
+		return fmt.Errorf("clean stale update workspace: %w", err)
+	}
+	return nil
+}

server/service/application/workspace_test.go

@@ -0,0 +1,49 @@
+package application
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestWorkspaceCleanupIsScopedToUpdaterDirectories(t *testing.T) {
+	base := t.TempDir()
+	for _, name := range []string{"nanokvm-update-old", "update-other", "firmware.tar.xz", "nanokvm-go_1.0.0"} {
+		if err := os.Mkdir(filepath.Join(base, name), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := cleanupStaleWorkspaces(base); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(filepath.Join(base, "nanokvm-update-old")); !os.IsNotExist(err) {
+		t.Fatalf("stale workspace still exists: %v", err)
+	}
+	for _, name := range []string{"update-other", "firmware.tar.xz", "nanokvm-go_1.0.0"} {
+		if _, err := os.Stat(filepath.Join(base, name)); err != nil {
+			t.Fatalf("unrelated cache entry %s was removed: %v", name, err)
+		}
+	}
+}
+
+func TestNewWorkspaceIsPrivateAndCloseOnlyRemovesItself(t *testing.T) {
+	base := t.TempDir()
+	keep := filepath.Join(base, "keep")
+	if err := os.WriteFile(keep, []byte("keep"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	workspace, err := newUpdateWorkspace(base)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if filepath.Dir(workspace.dir) != base || !strings.HasPrefix(filepath.Base(workspace.dir), updateWorkspacePrefix) {
+		t.Fatalf("unexpected workspace path %q", workspace.dir)
+	}
+	if err := workspace.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(keep); err != nil {
+		t.Fatalf("unrelated cache entry was removed: %v", err)
+	}
+}

server/service/auth/account.go

@@ -1,113 +0,0 @@
-package auth
-
-import (
-	"NanoKVM-Server/utils"
-	"encoding/json"
-	"errors"
-	"os"
-	"path/filepath"
-
-	log "github.com/sirupsen/logrus"
-	"golang.org/x/crypto/bcrypt"
-)
-
-const AccountFile = "/etc/kvm/pwd"
-
-type Account struct {
-	Username string `json:"username"`
-	Password string `json:"password"`	// should be named HashedPassword for clarity
-}
-
-func GetAccount() (*Account, error) {
-	if _, err := os.Stat(AccountFile); err != nil {
-		if errors.Is(err, os.ErrNotExist) {
-			return getDefaultAccount(), nil
-		}
-		return nil, err
-	}
-
-	content, err := os.ReadFile(AccountFile)
-	if err != nil {
-		return nil, err
-	}
-
-	var account Account
-	if err = json.Unmarshal(content, &account); err != nil {
-		log.Errorf("unmarshal account failed: %s", err)
-		return nil, err
-	}
-
-	return &account, nil
-}
-
-func SetAccount(username string, hashedPassword string) error {
-	account, err := json.Marshal(&Account{
-		Username: username,
-		Password: hashedPassword,
-	})
-	if err != nil {
-		log.Errorf("failed to marshal account information to json: %s", err)
-		return err
-	}
-
-	err = os.MkdirAll(filepath.Dir(AccountFile), 0o644)
-	if err != nil {
-		log.Errorf("create directory %s failed: %s", AccountFile, err)
-		return err
-	}
-
-	err = os.WriteFile(AccountFile, account, 0o644)
-	if err != nil {
-		log.Errorf("write password failed: %s", err)
-		return err
-	}
-
-	return nil
-}
-
-func CompareAccount(username string, plainPassword string) bool {
-	account, err := GetAccount()
-	if err != nil {
-		return false
-	}
-
-	if username != account.Username {
-		return false
-	}
-
-	hashedPassword, err := utils.DecodeDecrypt(plainPassword)
-	if err != nil || hashedPassword == "" {
-		return false
-	}
-
-	err = bcrypt.CompareHashAndPassword([]byte(account.Password), []byte(hashedPassword))
-	if err != nil {
-		// Compatible with old versions
-		accountHashedPassword, _ := utils.DecodeDecrypt(account.Password)
-		if accountHashedPassword == hashedPassword {
-			return true
-		}
-
-		return false
-	}
-
-	return true
-}
-
-func DelAccount() error {
-	if err := os.Remove(AccountFile); err != nil {
-		log.Errorf("failed to delete password: %s", err)
-		return err
-	}
-
-	return nil
-}
-
-func getDefaultAccount() *Account {
-	hashedPassword, _ := bcrypt.GenerateFromPassword([]byte("admin"), bcrypt.DefaultCost)
-
-	return &Account{
-		Username: "admin",
-		Password: string(hashedPassword),
-	}
-}

server/service/auth/brute_force.go

@@ -0,0 +1,147 @@
+package auth
+
+import (
+	"sync"
+	"time"
+
+	"NanoKVM-Server/config"
+
+	"github.com/gin-gonic/gin"
+	log "github.com/sirupsen/logrus"
+)
+
+type loginAttempt struct {
+	failures   int
+	lastFailed time.Time
+	lockoutEnd time.Time
+}
+
+const (
+	maxLoginAttemptsRecords = 3000
+	cleanupInterval         = 6 * time.Hour
+)
+
+var (
+	loginAttempts = make(map[string]*loginAttempt)
+	loginMutex    sync.Mutex
+	cleanupOnce   sync.Once
+)
+
+// startCleanupRoutine starts a background routine to clean up memory
+func startCleanupRoutine() {
+	conf := config.GetInstance()
+	if conf.Security.LoginLockoutDuration <= 0 {
+		return
+	}
+
+	go func() {
+		ticker := time.NewTicker(cleanupInterval)
+		for range ticker.C {
+			loginMutex.Lock()
+			now := time.Now()
+			for ip, attempt := range loginAttempts {
+				// Cleanup rules: if it has been locked and the lockout time has passed,
+				// or (although not locked) it has been 30 minutes since the last failure,
+				// remove this record
+				if (!attempt.lockoutEnd.IsZero() && now.After(attempt.lockoutEnd)) ||
+					(attempt.lockoutEnd.IsZero() && now.Sub(attempt.lastFailed) > 30*time.Minute) {
+					delete(loginAttempts, ip)
+				}
+			}
+			loginMutex.Unlock()
+		}
+	}()
+}
+
+// GetClientIP gets a reliable real IP
+func GetClientIP(c *gin.Context) string {
+	ip := c.RemoteIP()
+	if ip == "" {
+		ip = c.ClientIP()
+	}
+	return ip
+}
+
+// CheckLoginAttempt checks if a login attempt is allowed based on brute-force protection rules.
+// Returning true means the IP/System is locked out, and an error string and error code are returned.
+func CheckLoginAttempt(clientIP string) (bool, int, string) {
+	conf := config.GetInstance()
+	if conf.Security.LoginLockoutDuration <= 0 {
+		return false, 0, ""
+	}
+
+	cleanupOnce.Do(startCleanupRoutine)
+
+	loginMutex.Lock()
+	defer loginMutex.Unlock()
+
+	if attempt, exists := loginAttempts[clientIP]; exists {
+		if time.Now().Before(attempt.lockoutEnd) {
+			log.Debugf("login blocked for IP %s: account locked due to too many failed attempts (until %s)", clientIP, attempt.lockoutEnd)
+			return true, -5, "Account locked due to too many failed attempts, please try again later"
+		}
+
+		// If lockout has elapsed, then we reset the failures and lockoutEnd.
+		if !attempt.lockoutEnd.IsZero() {
+			attempt.failures = 0
+			attempt.lockoutEnd = time.Time{}
+		}
+	}
+
+	return false, 0, ""
+}
+
+// RecordLoginFailure records a failed login attempt for the given IP address.
+func RecordLoginFailure(clientIP string) (bool, int, string) {
+	conf := config.GetInstance()
+	if conf.Security.LoginLockoutDuration <= 0 {
+		return false, 0, ""
+	}
+
+	cleanupOnce.Do(startCleanupRoutine)
+
+	loginMutex.Lock()
+	defer loginMutex.Unlock()
+
+	attempt, exists := loginAttempts[clientIP]
+	if !exists {
+		// When the record pool is full, clear the records instead of global lockout to prevent DDoS
+		if len(loginAttempts) >= maxLoginAttemptsRecords {
+			log.Warn("Login attempt records reached maximum limit, clearing records to prevent memory overflow")
+			loginAttempts = make(map[string]*loginAttempt)
+		}
+		attempt = &loginAttempt{}
+		loginAttempts[clientIP] = attempt
+	}
+
+	now := time.Now()
+	// Failure time window: if it has been a long time since the last failure
+	// (e.g., beyond the lockoutDuration window), reset the failure count
+	if !attempt.lastFailed.IsZero() && now.Sub(attempt.lastFailed) > time.Duration(conf.Security.LoginLockoutDuration)*time.Second {
+		attempt.failures = 0
+	}
+
+	attempt.failures++
+	attempt.lastFailed = now
+
+	// Reach the failure limit, lock out
+	if attempt.failures >= conf.Security.LoginMaxFailures {
+		attempt.lockoutEnd = now.Add(time.Duration(conf.Security.LoginLockoutDuration) * time.Second)
+		log.Debugf("login failures reached threshold for IP %s, locking out until %s", clientIP, attempt.lockoutEnd)
+	}
+
+	return false, 0, ""
+}
+
+// ClearLoginAttempt clears the failed login attempt record for an IP upon successful login.
+func ClearLoginAttempt(clientIP string) {
+	conf := config.GetInstance()
+	if conf.Security.LoginLockoutDuration <= 0 {
+		return
+	}
+
+	loginMutex.Lock()
+	defer loginMutex.Unlock()
+
+	delete(loginAttempts, clientIP)
+}

server/service/auth/login.go

@@ -1,10 +1,15 @@
 package auth
 
 import (
+	"net/http"
+	"strings"
+	"time"
+
+	"NanoKVM-Server/authn"
 	"NanoKVM-Server/config"
 	"NanoKVM-Server/middleware"
 	"NanoKVM-Server/proto"
-	"time"
+	"NanoKVM-Server/utils"
 
 	"github.com/gin-gonic/gin"
 	log "github.com/sirupsen/logrus"
@@ -14,63 +19,110 @@ func (s *Service) Login(c *gin.Context) {
 	var req proto.LoginReq
 	var rsp proto.Response
 
-	// authentication disabled
 	conf := config.GetInstance()
 	if conf.Authentication == "disable" {
-		rsp.OkRspWithData(c, &proto.LoginRsp{
-			Token: "disabled",
-		})
+		rsp.OkRsp(c)
 		return
 	}
 
+	clientIP := GetClientIP(c)
+	if locked, code, msg := CheckLoginAttempt(clientIP); locked {
+		time.Sleep(3 * time.Second)
+		rsp.ErrRsp(c, code, msg)
+		return
+	}
 	if err := proto.ParseFormRequest(c, &req); err != nil {
 		time.Sleep(3 * time.Second)
 		rsp.ErrRsp(c, -1, "invalid parameters")
 		return
 	}
-
-	if ok := CompareAccount(req.Username, req.Password); !ok {
+	password, err := utils.DecodeDecrypt(req.Password)
+	if err != nil || password == "" {
+		s.loginFailed(c, clientIP, &rsp)
+		return
+	}
+	user, ok, err := authn.DefaultStore.Authenticate(req.Username, password)
+	if err != nil {
+		log.Errorf("load account during login: %s", err)
 		time.Sleep(2 * time.Second)
-		rsp.ErrRsp(c, -2, "invalid username or password")
+		rsp.ErrRsp(c, -3, "authentication unavailable")
+		return
+	}
+	if !ok {
+		s.loginFailed(c, clientIP, &rsp)
 		return
 	}
 
-	token, err := middleware.GenerateJWT(req.Username)
+	ClearLoginAttempt(clientIP)
+	token, err := middleware.GenerateJWT(user.Username, user.TokenVersion)
 	if err != nil {
-		time.Sleep(1 * time.Second)
+		time.Sleep(time.Second)
 		rsp.ErrRsp(c, -3, "generate token failed")
 		return
 	}
+	setSessionCookie(c, token)
+	rsp.OkRsp(c)
+	log.Infof("user logged in: %s", user.Username)
+}
 
-	rsp.OkRspWithData(c, &proto.LoginRsp{
-		Token: token,
-	})
-
-	log.Debugf("login success, username: %s", req.Username)
+func (s *Service) loginFailed(c *gin.Context, clientIP string, rsp *proto.Response) {
+	time.Sleep(2 * time.Second)
+	if locked, code, msg := RecordLoginFailure(clientIP); locked {
+		rsp.ErrRsp(c, code, msg)
+		return
+	}
+	rsp.ErrRsp(c, -2, "invalid username or password")
 }
 
 func (s *Service) Logout(c *gin.Context) {
-	conf := config.GetInstance()
-
-	if conf.JWT.RevokeTokensOnLogout {
-		config.RegenerateSecretKey()
-	}
-
 	var rsp proto.Response
+	principal, ok := middleware.CurrentPrincipal(c)
+	conf := config.GetInstance()
+	if ok && conf.Authentication != "disable" && conf.JWT.RevokeTokensOnLogout {
+		if _, err := authn.DefaultStore.Revoke(principal.Username); err != nil {
+			rsp.ErrRsp(c, -1, "failed to revoke session")
+			return
+		}
+		middleware.RevokeUserSessions(principal.Username)
+		log.Infof("user logged out: %s", principal.Username)
+	}
+	clearSessionCookie(c)
 	rsp.OkRsp(c)
 }
 
 func (s *Service) GetAccount(c *gin.Context) {
 	var rsp proto.Response
-
-	account, err := GetAccount()
-	if err != nil {
+	principal, ok := middleware.CurrentPrincipal(c)
+	if !ok {
 		rsp.ErrRsp(c, -1, "get account failed")
 		return
 	}
-
 	rsp.OkRspWithData(c, &proto.GetAccountRsp{
-		Username: account.Username,
+		Username: principal.Username,
+		Role:     string(principal.Role),
 	})
-	log.Debugf("get account successful")
+}
+
+func setSessionCookie(c *gin.Context, token string) {
+	conf := config.GetInstance()
+	secure := conf.Proto == "https" || c.Request.TLS != nil ||
+		strings.EqualFold(c.GetHeader("X-Forwarded-Proto"), "https")
+	c.SetSameSite(http.SameSiteStrictMode)
+	c.SetCookie(
+		middleware.CookieName,
+		token,
+		int(conf.JWT.RefreshTokenDuration),
+		"/",
+		"",
+		secure,
+		true,
+	)
+}
+
+func clearSessionCookie(c *gin.Context) {
+	conf := config.GetInstance()
+	secure := conf.Proto == "https" || c.Request.TLS != nil ||
+		strings.EqualFold(c.GetHeader("X-Forwarded-Proto"), "https")
+	c.SetSameSite(http.SameSiteStrictMode)
+	c.SetCookie(middleware.CookieName, "", -1, "/", "", secure, true)
 }

server/service/auth/password.go

@@ -1,124 +1,126 @@
 package auth
 
 import (
-	"NanoKVM-Server/proto"
-	"NanoKVM-Server/utils"
-	"errors"
 	"io"
 	"os"
 	"os/exec"
 	"time"
 
+	"NanoKVM-Server/authn"
+	"NanoKVM-Server/config"
+	"NanoKVM-Server/middleware"
+	"NanoKVM-Server/proto"
+	"NanoKVM-Server/utils"
+
 	"github.com/gin-gonic/gin"
 	log "github.com/sirupsen/logrus"
-	"golang.org/x/crypto/bcrypt"
 )
 
+var systemPasswordUpdater = changeRootPassword
+
 func (s *Service) ChangePassword(c *gin.Context) {
 	var req proto.ChangePasswordReq
 	var rsp proto.Response
-
 	if err := proto.ParseFormRequest(c, &req); err != nil {
 		rsp.ErrRsp(c, -1, "invalid parameters")
 		return
 	}
-
-	password, err := utils.DecodeDecrypt(req.Password)
-	if err != nil || password == "" {
-		rsp.ErrRsp(c, -2, "invalid password")
-		return
-	}
-
-	hashedPassword, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
-	if err != nil {
-		rsp.ErrRsp(c, -3, "failed to hash password")
-		return
-	}
-
-	if err = SetAccount(req.Username, string(hashedPassword)); err != nil {
-		rsp.ErrRsp(c, -4, "failed to save password")
-		return
-	}
-
-	// change root password
-	err = changeRootPassword(password)
-	if err != nil {
-		_ = DelAccount()
-		rsp.ErrRsp(c, -5, "failed to change password")
+	principal, ok := middleware.CurrentPrincipal(c)
+	if !ok {
+		rsp.ErrRsp(c, -2, "invalid session")
+		return
+	}
+	currentPassword, err := utils.DecodeDecrypt(req.CurrentPassword)
+	if err != nil || currentPassword == "" {
+		rsp.ErrRsp(c, -3, "current password is required")
+		return
+	}
+	if _, authenticated, authErr := authn.DefaultStore.Authenticate(principal.Username, currentPassword); authErr != nil {
+		rsp.ErrRsp(c, -4, "authentication unavailable")
+		return
+	} else if !authenticated {
+		rsp.ErrRsp(c, -3, "current password is incorrect")
+		return
+	}
+	if err := changeUserPassword(principal.Username, req.Password); err != nil {
+		rsp.ErrRsp(c, -5, err.Error())
 		return
 	}
 
+	middleware.RevokeUserSessions(principal.Username)
+	clearSessionCookie(c)
 	rsp.OkRsp(c)
-	log.Debugf("change password success, username: %s", req.Username)
+	log.Infof("password changed for user: %s", principal.Username)
 }
 
 func (s *Service) IsPasswordUpdated(c *gin.Context) {
 	var rsp proto.Response
+	if config.GetInstance().Authentication == "disable" {
+		rsp.OkRspWithData(c, &proto.IsPasswordUpdatedRsp{IsUpdated: true})
+		return
+	}
+	principal, ok := middleware.CurrentPrincipal(c)
+	if !ok {
+		rsp.ErrRsp(c, -1, "invalid session")
+		return
+	}
+	user, err := authn.DefaultStore.Get(principal.Username)
+	if err != nil {
+		rsp.ErrRsp(c, -2, "failed to get password state")
+		return
+	}
+	rsp.OkRspWithData(c, &proto.IsPasswordUpdatedRsp{IsUpdated: !user.MustChangePassword})
+}
 
-	if _, err := os.Stat(AccountFile); err != nil {
-		rsp.OkRspWithData(c, &proto.IsPasswordUpdatedRsp{
-			IsUpdated: false,
+func changeUserPassword(username, encryptedPassword string) error {
+	password, err := utils.DecodeDecrypt(encryptedPassword)
+	if err != nil || password == "" {
+		return errInvalidPassword
+	}
+	if err = authn.ValidatePassword(password); err != nil {
+		return err
+	}
+	user, err := authn.DefaultStore.Get(username)
+	if err != nil {
+		return err
+	}
+	if user.SystemAccount && user.Role == authn.RoleAdmin && user.Enabled {
+		_, err = authn.DefaultStore.SetPasswordAndRun(username, password, func() error {
+			return systemPasswordUpdater(password)
 		})
-		return
+		return err
 	}
-
-	account, err := GetAccount()
-	if err != nil || account == nil {
-		rsp.ErrRsp(c, -1, "failed to get password")
-		return
-	}
-
-	err = bcrypt.CompareHashAndPassword([]byte(account.Password), []byte("admin"))
-
-	rsp.OkRspWithData(c, &proto.IsPasswordUpdatedRsp{
-		// If the hash is not valid, still assume it's not updated
-		// The error we want to see is password and hash not matching
-		IsUpdated: errors.Is(err, bcrypt.ErrMismatchedHashAndPassword),
-	})
+	_, err = authn.DefaultStore.SetPassword(username, password)
+	return err
 }
 
 func changeRootPassword(password string) error {
-	err := passwd(password)
-	if err != nil {
+	if err := passwd(password); err != nil {
 		log.Errorf("failed to change root password: %s", err)
 		return err
 	}
-
-	log.Debugf("change root password successful.")
+	log.Debug("change root password successful")
 	return nil
 }
 
 func passwd(password string) error {
 	cmd := exec.Command("passwd", "root")
-
 	stdin, err := cmd.StdinPipe()
 	if err != nil {
 		return err
 	}
-	defer func() {
-		_ = stdin.Close()
-	}()
-
+	defer func() { _ = stdin.Close() }()
 	cmd.Stdout = os.Stdout
 	cmd.Stderr = os.Stderr
-
 	if err = cmd.Start(); err != nil {
 		return err
 	}
-
 	if _, err = io.WriteString(stdin, password+"\n"); err != nil {
 		return err
 	}
-
 	time.Sleep(100 * time.Millisecond)
-
 	if _, err = io.WriteString(stdin, password+"\n"); err != nil {
 		return err
 	}
-
-	if err = cmd.Wait(); err != nil {
-		return err
-	}
-
-	return nil
+	return cmd.Wait()
 }

server/service/auth/service_test.go

@@ -0,0 +1,307 @@
+package auth
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"path/filepath"
+	"testing"
+
+	"NanoKVM-Server/authn"
+	"NanoKVM-Server/config"
+	"NanoKVM-Server/middleware"
+	"NanoKVM-Server/proto"
+	"NanoKVM-Server/utils"
+
+	"github.com/gin-gonic/gin"
+	"github.com/mervick/aes-everywhere/go/aes256"
+)
+
+func TestLoginCookieAndUserAuthorizationLifecycle(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	store := authn.NewStore(filepath.Join(t.TempDir(), "pwd"))
+	restore := useTestStore(store)
+	defer restore()
+
+	service := NewService()
+	router := gin.New()
+	router.POST("/login", service.Login)
+	authenticated := router.Group("/").Use(middleware.CheckToken())
+	authenticated.GET("/account", service.GetAccount)
+	authenticated.POST("/logout", service.Logout)
+	admin := router.Group("/").Use(middleware.CheckToken(), middleware.RequireRole(authn.RoleAdmin))
+	admin.GET("/users", service.ListUsers)
+	admin.POST("/users", service.CreateUser)
+	admin.PUT("/users/:username", service.UpdateUser)
+
+	adminCookie := loginCookie(t, router, "admin", "admin")
+	if !adminCookie.HttpOnly || adminCookie.SameSite != http.SameSiteStrictMode || adminCookie.Path != "/" {
+		t.Fatalf("unsafe session cookie: %+v", adminCookie)
+	}
+
+	createBody := map[string]any{
+		"username": "alice",
+		"password": encryptForRequest("valid-password"),
+		"role":     "user",
+	}
+	if code := requestJSON(router, http.MethodPost, "/users", createBody, adminCookie); code != http.StatusOK {
+		t.Fatalf("create status = %d", code)
+	}
+	userCookie := loginCookie(t, router, "alice", "valid-password")
+	if code := requestJSON(router, http.MethodGet, "/users", nil, userCookie); code != http.StatusForbidden {
+		t.Fatalf("user management status = %d, want 403", code)
+	}
+
+	disabled := false
+	if code := requestJSON(router, http.MethodPut, "/users/alice", map[string]any{"enabled": disabled}, adminCookie); code != http.StatusOK {
+		t.Fatalf("disable status = %d", code)
+	}
+	if code := requestJSON(router, http.MethodGet, "/account", nil, userCookie); code != http.StatusUnauthorized {
+		t.Fatalf("disabled session status = %d, want 401", code)
+	}
+}
+
+func TestLogoutDoesNotInvalidateAnotherUser(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	store := authn.NewStore(filepath.Join(t.TempDir(), "pwd"))
+	restore := useTestStore(store)
+	defer restore()
+	if _, ok, err := store.Authenticate("admin", "admin"); err != nil || !ok {
+		t.Fatalf("default login: ok=%v err=%v", ok, err)
+	}
+	if err := store.Create("alice", "alice-password", authn.RoleUser); err != nil {
+		t.Fatal(err)
+	}
+	if err := store.Create("bob", "bob-password", authn.RoleUser); err != nil {
+		t.Fatal(err)
+	}
+
+	service := NewService()
+	router := gin.New()
+	router.POST("/login", service.Login)
+	authenticated := router.Group("/").Use(middleware.CheckToken())
+	authenticated.GET("/account", service.GetAccount)
+	authenticated.POST("/logout", service.Logout)
+
+	aliceCookie := loginCookie(t, router, "alice", "alice-password")
+	bobCookie := loginCookie(t, router, "bob", "bob-password")
+	if code := requestJSON(router, http.MethodPost, "/logout", nil, aliceCookie); code != http.StatusOK {
+		t.Fatalf("logout status = %d", code)
+	}
+	if code := requestJSON(router, http.MethodGet, "/account", nil, aliceCookie); code != http.StatusUnauthorized {
+		t.Fatalf("logged out session status = %d", code)
+	}
+	if code := requestJSON(router, http.MethodGet, "/account", nil, bobCookie); code != http.StatusOK {
+		t.Fatalf("other user's session status = %d", code)
+	}
+}
+
+func TestNormalUserPasswordNeverChangesSystemPassword(t *testing.T) {
+	store := authn.NewStore(filepath.Join(t.TempDir(), "pwd"))
+	restore := useTestStore(store)
+	defer restore()
+	if _, ok, err := store.Authenticate("admin", "admin"); err != nil || !ok {
+		t.Fatalf("default login: ok=%v err=%v", ok, err)
+	}
+	if err := store.Create("alice", "alice-password", authn.RoleUser); err != nil {
+		t.Fatal(err)
+	}
+
+	originalUpdater := systemPasswordUpdater
+	updates := 0
+	systemPasswordUpdater = func(string) error {
+		updates++
+		return nil
+	}
+	defer func() { systemPasswordUpdater = originalUpdater }()
+
+	if err := changeUserPassword("alice", encryptForRequest("new-password")); err != nil {
+		t.Fatal(err)
+	}
+	if updates != 0 {
+		t.Fatalf("system password updated %d times for a normal user", updates)
+	}
+	if _, ok, err := store.Authenticate("alice", "new-password"); err != nil || !ok {
+		t.Fatalf("new web password login: ok=%v err=%v", ok, err)
+	}
+}
+
+func TestSelfPasswordChangeRequiresCurrentPassword(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	store := authn.NewStore(filepath.Join(t.TempDir(), "pwd"))
+	restore := useTestStore(store)
+	defer restore()
+	if _, ok, err := store.Authenticate("admin", "admin"); err != nil || !ok {
+		t.Fatalf("default login: ok=%v err=%v", ok, err)
+	}
+	if err := store.Create("alice", "alice-password", authn.RoleUser); err != nil {
+		t.Fatal(err)
+	}
+
+	service := NewService()
+	router := gin.New()
+	router.POST("/login", service.Login)
+	authenticated := router.Group("/").Use(middleware.CheckToken())
+	authenticated.POST("/password", service.ChangePassword)
+	cookie := loginCookie(t, router, "alice", "alice-password")
+
+	recorder := requestJSONRecorder(router, http.MethodPost, "/password", map[string]any{
+		"currentPassword": encryptForRequest("wrong-password"),
+		"password":        encryptForRequest("new-password"),
+	}, cookie)
+	var response proto.Response
+	if err := json.Unmarshal(recorder.Body.Bytes(), &response); err != nil {
+		t.Fatalf("decode wrong-current-password response: %v", err)
+	}
+	if response.Code != -3 || response.Msg != "current password is incorrect" {
+		t.Fatalf("wrong-current-password response = %+v", response)
+	}
+	if _, ok, err := store.Authenticate("alice", "new-password"); err != nil || ok {
+		t.Fatalf("password changed without current credential: ok=%v err=%v", ok, err)
+	}
+
+	requestJSON(router, http.MethodPost, "/password", map[string]any{
+		"currentPassword": encryptForRequest("alice-password"),
+		"password":        encryptForRequest("new-password"),
+	}, cookie)
+	if _, ok, err := store.Authenticate("alice", "new-password"); err != nil || !ok {
+		t.Fatalf("valid password change failed: ok=%v err=%v", ok, err)
+	}
+}
+
+func TestAdministratorCannotResetDeviceOwnerPassword(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	store := authn.NewStore(filepath.Join(t.TempDir(), "pwd"))
+	restore := useTestStore(store)
+	defer restore()
+	if _, ok, err := store.Authenticate("admin", "admin"); err != nil || !ok {
+		t.Fatalf("default login: ok=%v err=%v", ok, err)
+	}
+	if err := store.Create("second-admin", "second-password", authn.RoleAdmin); err != nil {
+		t.Fatal(err)
+	}
+
+	originalUpdater := systemPasswordUpdater
+	updates := 0
+	systemPasswordUpdater = func(string) error {
+		updates++
+		return nil
+	}
+	defer func() { systemPasswordUpdater = originalUpdater }()
+
+	service := NewService()
+	router := gin.New()
+	router.POST("/login", service.Login)
+	admin := router.Group("/").Use(middleware.CheckToken(), middleware.RequireRole(authn.RoleAdmin))
+	admin.POST("/users/:username/password", service.ChangeUserPassword)
+	cookie := loginCookie(t, router, "second-admin", "second-password")
+	requestJSON(router, http.MethodPost, "/users/admin/password", map[string]any{
+		"password": encryptForRequest("new-password"),
+	}, cookie)
+
+	if updates != 0 {
+		t.Fatalf("administrator changed the device owner's system password %d times", updates)
+	}
+	if _, ok, err := store.Authenticate("admin", "admin"); err != nil || !ok {
+		t.Fatalf("device owner password changed: ok=%v err=%v", ok, err)
+	}
+	if _, ok, err := store.Authenticate("admin", "new-password"); err != nil || ok {
+		t.Fatalf("unauthorized password became active: ok=%v err=%v", ok, err)
+	}
+}
+
+func TestSystemPasswordFailureRollsBackWebPassword(t *testing.T) {
+	store := authn.NewStore(filepath.Join(t.TempDir(), "pwd"))
+	restore := useTestStore(store)
+	defer restore()
+	if _, ok, err := store.Authenticate("admin", "admin"); err != nil || !ok {
+		t.Fatalf("default login: ok=%v err=%v", ok, err)
+	}
+
+	originalUpdater := systemPasswordUpdater
+	systemPasswordUpdater = func(string) error { return errors.New("passwd failed") }
+	defer func() { systemPasswordUpdater = originalUpdater }()
+
+	if err := changeUserPassword("admin", encryptForRequest("new-password")); err == nil {
+		t.Fatal("system password failure was ignored")
+	}
+	if _, ok, err := store.Authenticate("admin", "admin"); err != nil || !ok {
+		t.Fatalf("old web password was not restored: ok=%v err=%v", ok, err)
+	}
+	if _, ok, err := store.Authenticate("admin", "new-password"); err != nil || ok {
+		t.Fatalf("failed password stayed active: ok=%v err=%v", ok, err)
+	}
+}
+
+func loginCookie(t *testing.T, handler http.Handler, username, password string) *http.Cookie {
+	t.Helper()
+	body := map[string]any{"username": username, "password": encryptForRequest(password)}
+	recorder := httptest.NewRecorder()
+	request := jsonRequest(http.MethodPost, "/login", body)
+	handler.ServeHTTP(recorder, request)
+	if recorder.Code != http.StatusOK {
+		t.Fatalf("login status = %d", recorder.Code)
+	}
+	if bytes.Contains(recorder.Body.Bytes(), []byte("token")) {
+		t.Fatalf("login exposed JWT in response: %s", recorder.Body.String())
+	}
+	for _, cookie := range recorder.Result().Cookies() {
+		if cookie.Name == middleware.CookieName {
+			return cookie
+		}
+	}
+	t.Fatal("login did not set session cookie")
+	return nil
+}
+
+func requestJSON(handler http.Handler, method, path string, body any, cookie *http.Cookie) int {
+	return requestJSONRecorder(handler, method, path, body, cookie).Code
+}
+
+func requestJSONRecorder(handler http.Handler, method, path string, body any, cookie *http.Cookie) *httptest.ResponseRecorder {
+	recorder := httptest.NewRecorder()
+	request := jsonRequest(method, path, body)
+	if cookie != nil {
+		request.AddCookie(cookie)
+	}
+	handler.ServeHTTP(recorder, request)
+	return recorder
+}
+
+func jsonRequest(method, path string, body any) *http.Request {
+	var data []byte
+	if body != nil {
+		data, _ = json.Marshal(body)
+	}
+	request := httptest.NewRequest(method, path, bytes.NewReader(data))
+	request.Header.Set("Content-Type", "application/json")
+	return request
+}
+
+func encryptForRequest(password string) string {
+	return url.QueryEscape(aes256.Encrypt(password, utils.SecretKey))
+}
+
+func useTestStore(store *authn.Store) func() {
+	originalStore := authn.DefaultStore
+	conf := config.GetInstance()
+	originalAuthentication := conf.Authentication
+	originalSecret := conf.JWT.SecretKey
+	originalDuration := conf.JWT.RefreshTokenDuration
+	originalRevokeOnLogout := conf.JWT.RevokeTokensOnLogout
+	authn.DefaultStore = store
+	conf.Authentication = "enable"
+	conf.JWT.SecretKey = "test-secret"
+	conf.JWT.RefreshTokenDuration = 3600
+	conf.JWT.RevokeTokensOnLogout = true
+	return func() {
+		authn.DefaultStore = originalStore
+		conf.Authentication = originalAuthentication
+		conf.JWT.SecretKey = originalSecret
+		conf.JWT.RefreshTokenDuration = originalDuration
+		conf.JWT.RevokeTokensOnLogout = originalRevokeOnLogout
+	}
+}

server/service/auth/users.go

@@ -0,0 +1,127 @@
+package auth
+
+import (
+	"errors"
+
+	"NanoKVM-Server/authn"
+	"NanoKVM-Server/middleware"
+	"NanoKVM-Server/proto"
+	"NanoKVM-Server/utils"
+
+	"github.com/gin-gonic/gin"
+	log "github.com/sirupsen/logrus"
+)
+
+var errInvalidPassword = errors.New("invalid password")
+
+func (s *Service) ListUsers(c *gin.Context) {
+	var rsp proto.Response
+	users, err := authn.DefaultStore.List()
+	if err != nil {
+		rsp.ErrRsp(c, -1, "failed to load users")
+		return
+	}
+	result := make([]proto.UserInfo, 0, len(users))
+	for _, user := range users {
+		result = append(result, proto.UserInfo{
+			Username:      user.Username,
+			Role:          string(user.Role),
+			Enabled:       user.Enabled,
+			SystemAccount: user.SystemAccount,
+		})
+	}
+	rsp.OkRspWithData(c, &proto.ListUsersRsp{Users: result})
+}
+
+func (s *Service) CreateUser(c *gin.Context) {
+	var req proto.CreateUserReq
+	var rsp proto.Response
+	if err := proto.ParseFormRequest(c, &req); err != nil {
+		rsp.ErrRsp(c, -1, "invalid parameters")
+		return
+	}
+	password, err := decodePassword(req.Password)
+	if err != nil {
+		rsp.ErrRsp(c, -2, err.Error())
+		return
+	}
+	if err = authn.DefaultStore.Create(req.Username, password, authn.Role(req.Role)); err != nil {
+		rsp.ErrRsp(c, -3, err.Error())
+		return
+	}
+	rsp.OkRsp(c)
+	log.Infof("user created: %s (%s)", req.Username, req.Role)
+}
+
+func (s *Service) UpdateUser(c *gin.Context) {
+	var req proto.UpdateUserReq
+	var rsp proto.Response
+	if err := proto.ParseFormRequest(c, &req); err != nil || (req.Role == nil && req.Enabled == nil) {
+		rsp.ErrRsp(c, -1, "invalid parameters")
+		return
+	}
+	principal, _ := middleware.CurrentPrincipal(c)
+	patch := authn.UserPatch{Enabled: req.Enabled}
+	if req.Role != nil {
+		role := authn.Role(*req.Role)
+		patch.Role = &role
+	}
+	username := c.Param("username")
+	if _, err := authn.DefaultStore.Update(principal.Username, username, patch); err != nil {
+		rsp.ErrRsp(c, -2, err.Error())
+		return
+	}
+	middleware.RevokeUserSessions(username)
+	rsp.OkRsp(c)
+	log.Infof("user updated: %s", username)
+}
+
+func (s *Service) DeleteUser(c *gin.Context) {
+	var rsp proto.Response
+	principal, _ := middleware.CurrentPrincipal(c)
+	username := c.Param("username")
+	if err := authn.DefaultStore.Delete(principal.Username, username); err != nil {
+		rsp.ErrRsp(c, -1, err.Error())
+		return
+	}
+	middleware.RevokeUserSessions(username)
+	rsp.OkRsp(c)
+	log.Infof("user deleted: %s", username)
+}
+
+func (s *Service) ChangeUserPassword(c *gin.Context) {
+	var req proto.ChangePasswordReq
+	var rsp proto.Response
+	if err := proto.ParseFormRequest(c, &req); err != nil {
+		rsp.ErrRsp(c, -1, "invalid parameters")
+		return
+	}
+	username := c.Param("username")
+	user, err := authn.DefaultStore.Get(username)
+	if err != nil {
+		rsp.ErrRsp(c, -2, err.Error())
+		return
+	}
+	if user.SystemAccount {
+		rsp.ErrRsp(c, -3, "the device owner must change its own password")
+		return
+	}
+	if err := changeUserPassword(username, req.Password); err != nil {
+		rsp.ErrRsp(c, -4, err.Error())
+		return
+	}
+	middleware.RevokeUserSessions(username)
+	rsp.OkRsp(c)
+	log.Infof("password reset for user: %s", username)
+}
+
+func decodePassword(encrypted string) (string, error) {
+	password, err := utils.DecodeDecrypt(encrypted)
+	if err != nil || password == "" {
+		return "", errInvalidPassword
+	}
+	if err = authn.ValidatePassword(password); err != nil {
+		return "", err
+	}
+	return password, nil
+}

server/service/controlmode/activity.go

@@ -0,0 +1,97 @@
+package controlmode
+
+import (
+	"errors"
+	"sync"
+	"time"
+)
+
+var ErrActivityWaitTimeout = errors.New("timed out waiting for active control operations")
+
+// activityGate allows normal control operations to share the current mode while
+// giving mode transitions exclusive access. Unlike sync.RWMutex, exclusive
+// acquisition is bounded so an abandoned client cannot leave the manager stuck
+// in the transitioning state forever.
+type activityGate struct {
+	mu        sync.Mutex
+	active    int
+	exclusive bool
+	changed   chan struct{}
+}
+
+func (g *activityGate) acquireShared() func() {
+	for {
+		g.mu.Lock()
+		if !g.exclusive {
+			g.active++
+			g.mu.Unlock()
+
+			var once sync.Once
+			return func() {
+				once.Do(func() {
+					g.mu.Lock()
+					if g.active > 0 {
+						g.active--
+					}
+					g.signalLocked()
+					g.mu.Unlock()
+				})
+			}
+		}
+
+		changed := g.changedLocked()
+		g.mu.Unlock()
+		<-changed
+	}
+}
+
+func (g *activityGate) acquireExclusive(timeout time.Duration) (func(), error) {
+	if timeout <= 0 {
+		return nil, ErrActivityWaitTimeout
+	}
+
+	timer := time.NewTimer(timeout)
+	defer timer.Stop()
+
+	for {
+		g.mu.Lock()
+		if !g.exclusive && g.active == 0 {
+			g.exclusive = true
+			g.mu.Unlock()
+
+			var once sync.Once
+			return func() {
+				once.Do(func() {
+					g.mu.Lock()
+					g.exclusive = false
+					g.signalLocked()
+					g.mu.Unlock()
+				})
+			}, nil
+		}
+
+		changed := g.changedLocked()
+		g.mu.Unlock()
+
+		select {
+		case <-changed:
+		case <-timer.C:
+			return nil, ErrActivityWaitTimeout
+		}
+	}
+}
+
+func (g *activityGate) changedLocked() <-chan struct{} {
+	if g.changed == nil {
+		g.changed = make(chan struct{})
+	}
+	return g.changed
+}
+
+func (g *activityGate) signalLocked() {
+	if g.changed == nil {
+		return
+	}
+	close(g.changed)
+	g.changed = make(chan struct{})
+}

server/service/controlmode/manager.go

@@ -0,0 +1,555 @@
+package controlmode
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+)
+
+const ModeFile = "/etc/kvm/ai-control.mode"
+
+const defaultActivityWaitTimeout = 30 * time.Second
+
+type Mode string
+
+const (
+	ModeOff      Mode = "off"
+	ModeMCP      Mode = "mcp"
+	ModePicoclaw Mode = "picoclaw"
+)
+
+var ErrModeConflict = errors.New("AI control mode conflict")
+
+type Status struct {
+	Mode          Mode      `json:"mode"`
+	Transitioning bool      `json:"transitioning"`
+	LastError     string    `json:"last_error,omitempty"`
+	ChangedAt     time.Time `json:"changed_at,omitempty"`
+}
+
+type Manager struct {
+	transitionMu        sync.Mutex
+	activity            activityGate
+	mu                  sync.Mutex
+	path                string
+	defaultMode         Mode
+	activityWaitTimeout time.Duration
+	loaded              bool
+	mode                Mode
+	modeFileExists      bool
+	modeFileSize        int64
+	modeFileModTime     time.Time
+	transitioning       bool
+	lastError           string
+	changedAt           time.Time
+}
+
+var (
+	defaultManagerOnce sync.Once
+	defaultManager     *Manager
+)
+
+func GetManager() *Manager {
+	defaultManagerOnce.Do(func() {
+		defaultManager = NewManager(ModeFile, ModePicoclaw)
+	})
+	return defaultManager
+}
+
+func NewManager(path string, defaultMode Mode) *Manager {
+	if !validMode(defaultMode) {
+		defaultMode = ModeOff
+	}
+	return &Manager{
+		path:                path,
+		defaultMode:         defaultMode,
+		activityWaitTimeout: defaultActivityWaitTimeout,
+	}
+}
+
+func (m *Manager) Status() (Status, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if err := m.loadLocked(); err != nil {
+		return Status{Mode: ModeOff, Transitioning: m.transitioning, LastError: err.Error(), ChangedAt: m.changedAt}, err
+	}
+	return m.statusLocked(), nil
+}
+
+func (m *Manager) Current() Mode {
+	status, err := m.Status()
+	if err != nil {
+		return ModeOff
+	}
+	return status.Mode
+}
+
+func (m *Manager) RequireWrite(expected Mode) error {
+	status, err := m.Status()
+	if err != nil {
+		return err
+	}
+	if status.Transitioning || status.Mode != expected {
+		return fmt.Errorf("%w: current=%s expected=%s", ErrModeConflict, status.Mode, expected)
+	}
+	return nil
+}
+
+func (m *Manager) Require(expected Mode) error {
+	return m.RequireWrite(expected)
+}
+
+func (m *Manager) RequireMode(expected Mode) error {
+	status, err := m.Status()
+	if err != nil {
+		return err
+	}
+	if status.Mode != expected {
+		return fmt.Errorf("%w: current=%s expected=%s", ErrModeConflict, status.Mode, expected)
+	}
+	return nil
+}
+
+func (m *Manager) AcquireWrite(expected Mode) (func(), error) {
+	if err := m.RequireWrite(expected); err != nil {
+		return nil, err
+	}
+	release := m.activity.acquireShared()
+	if err := m.RequireWrite(expected); err != nil {
+		release()
+		return nil, err
+	}
+	return release, nil
+}
+
+func (m *Manager) Acquire(expected Mode) (func(), error) {
+	return m.AcquireWrite(expected)
+}
+
+// AcquireStable holds the current control mode stable while a non-AI input
+// operation is in flight. Mode transitions take the exclusive side of the
+// activity gate, so they wait until the returned release function is called.
+func (m *Manager) AcquireStable() (Status, func(), error) {
+	status, err := m.Status()
+	if err != nil {
+		return Status{Mode: ModeOff}, nil, err
+	}
+	if status.Transitioning {
+		return status, nil, fmt.Errorf("%w: control mode is transitioning", ErrModeConflict)
+	}
+
+	release := m.activity.acquireShared()
+	status, err = m.Status()
+	if err != nil {
+		release()
+		return Status{Mode: ModeOff}, nil, err
+	}
+	if status.Transitioning {
+		release()
+		return status, nil, fmt.Errorf("%w: control mode is transitioning", ErrModeConflict)
+	}
+
+	return status, release, nil
+}
+
+func (m *Manager) Switch(next Mode, preempt func() error) error {
+	return m.SwitchWithCleanup(next, preempt, nil)
+}
+
+func (m *Manager) SwitchWithCleanup(next Mode, preempt func() error, cleanup func() error) error {
+	startedAt := time.Now()
+	timings := log.Fields{
+		"to": string(next),
+	}
+
+	m.transitionMu.Lock()
+	defer m.transitionMu.Unlock()
+
+	stageStartedAt := time.Now()
+	status, err := m.Status()
+	timings["load_status_ms"] = elapsedMilliseconds(stageStartedAt)
+	if err != nil {
+		logModeSwitchFailure("AI control mode switch failed while loading status", timings, err, startedAt)
+		return err
+	}
+	timings["from"] = string(status.Mode)
+	if !validMode(next) {
+		err := fmt.Errorf("invalid AI control mode %q", next)
+		logModeSwitchFailure("AI control mode switch rejected invalid target", timings, err, startedAt)
+		return err
+	}
+	if status.Mode == next {
+		timings["total_ms"] = elapsedMilliseconds(startedAt)
+		log.WithFields(timings).Debug("AI control mode switch skipped")
+		return nil
+	}
+
+	m.setTransitioning(true)
+	defer m.setTransitioning(false)
+	if preempt != nil {
+		stageStartedAt = time.Now()
+		if err := callModeTransitionHook(preempt); err != nil {
+			timings["preempt_ms"] = elapsedMilliseconds(stageStartedAt)
+			m.setLastError(err)
+			logModeSwitchFailure("AI control mode switch preempt failed", timings, err, startedAt)
+			return err
+		}
+		timings["preempt_ms"] = elapsedMilliseconds(stageStartedAt)
+	}
+
+	stageStartedAt = time.Now()
+	releaseActivity, err := m.acquireExclusiveActivity()
+	timings["activity_wait_ms"] = elapsedMilliseconds(stageStartedAt)
+	if err != nil {
+		m.setLastError(err)
+		logModeSwitchFailure("AI control mode switch activity wait failed", timings, err, startedAt)
+		return err
+	}
+	defer releaseActivity()
+
+	if cleanup != nil {
+		stageStartedAt = time.Now()
+		if err := callModeTransitionHook(cleanup); err != nil {
+			timings["cleanup_ms"] = elapsedMilliseconds(stageStartedAt)
+			if rollbackErr := m.save(ModeOff); rollbackErr != nil {
+				err = errors.Join(err, rollbackErr)
+			}
+			m.setLastError(err)
+			logModeSwitchFailure("AI control mode switch cleanup failed", timings, err, startedAt)
+			return err
+		}
+		timings["cleanup_ms"] = elapsedMilliseconds(stageStartedAt)
+	}
+
+	stageStartedAt = time.Now()
+	if err := m.save(next); err != nil {
+		timings["save_mode_ms"] = elapsedMilliseconds(stageStartedAt)
+		m.setLastError(err)
+		logModeSwitchFailure("AI control mode switch save failed", timings, err, startedAt)
+		return err
+	}
+	timings["save_mode_ms"] = elapsedMilliseconds(stageStartedAt)
+	m.setLastError(nil)
+	timings["total_ms"] = elapsedMilliseconds(startedAt)
+	log.WithFields(timings).Info("AI control mode switch completed")
+	return nil
+}
+
+func (m *Manager) SwitchIf(expected Mode, next Mode, preempt func() error) (bool, error) {
+	return m.SwitchIfWithCleanup(expected, next, preempt, nil)
+}
+
+func (m *Manager) SwitchIfWithCleanup(expected Mode, next Mode, preempt func() error, cleanup func() error) (bool, error) {
+	startedAt := time.Now()
+	timings := log.Fields{
+		"expected": string(expected),
+		"to":       string(next),
+	}
+
+	if !validMode(expected) || !validMode(next) {
+		err := fmt.Errorf("invalid AI control mode transition %q -> %q", expected, next)
+		logModeSwitchFailure("conditional AI control mode switch rejected invalid transition", timings, err, startedAt)
+		return false, err
+	}
+
+	m.transitionMu.Lock()
+	defer m.transitionMu.Unlock()
+
+	stageStartedAt := time.Now()
+	status, err := m.Status()
+	timings["load_status_ms"] = elapsedMilliseconds(stageStartedAt)
+	if err != nil {
+		logModeSwitchFailure("conditional AI control mode switch failed while loading status", timings, err, startedAt)
+		return false, err
+	}
+	timings["from"] = string(status.Mode)
+	if status.Mode != expected {
+		timings["matched"] = false
+		timings["total_ms"] = elapsedMilliseconds(startedAt)
+		log.WithFields(timings).Debug("conditional AI control mode switch skipped")
+		return false, nil
+	}
+	if status.Mode == next {
+		timings["matched"] = true
+		timings["total_ms"] = elapsedMilliseconds(startedAt)
+		log.WithFields(timings).Debug("conditional AI control mode switch already satisfied")
+		return true, nil
+	}
+
+	m.setTransitioning(true)
+	defer m.setTransitioning(false)
+	if preempt != nil {
+		stageStartedAt = time.Now()
+		if err := callModeTransitionHook(preempt); err != nil {
+			timings["preempt_ms"] = elapsedMilliseconds(stageStartedAt)
+			m.setLastError(err)
+			logModeSwitchFailure("conditional AI control mode switch preempt failed", timings, err, startedAt)
+			return false, err
+		}
+		timings["preempt_ms"] = elapsedMilliseconds(stageStartedAt)
+	}
+
+	stageStartedAt = time.Now()
+	releaseActivity, err := m.acquireExclusiveActivity()
+	timings["activity_wait_ms"] = elapsedMilliseconds(stageStartedAt)
+	if err != nil {
+		m.setLastError(err)
+		logModeSwitchFailure("conditional AI control mode switch activity wait failed", timings, err, startedAt)
+		return false, err
+	}
+	defer releaseActivity()
+
+	if cleanup != nil {
+		stageStartedAt = time.Now()
+		if err := callModeTransitionHook(cleanup); err != nil {
+			timings["cleanup_ms"] = elapsedMilliseconds(stageStartedAt)
+			if rollbackErr := m.save(ModeOff); rollbackErr != nil {
+				err = errors.Join(err, rollbackErr)
+			}
+			m.setLastError(err)
+			logModeSwitchFailure("conditional AI control mode switch cleanup failed", timings, err, startedAt)
+			return false, err
+		}
+		timings["cleanup_ms"] = elapsedMilliseconds(stageStartedAt)
+	}
+
+	stageStartedAt = time.Now()
+	if err := m.save(next); err != nil {
+		timings["save_mode_ms"] = elapsedMilliseconds(stageStartedAt)
+		m.setLastError(err)
+		logModeSwitchFailure("conditional AI control mode switch save failed", timings, err, startedAt)
+		return false, err
+	}
+	timings["save_mode_ms"] = elapsedMilliseconds(stageStartedAt)
+	m.setLastError(nil)
+	timings["matched"] = true
+	timings["total_ms"] = elapsedMilliseconds(startedAt)
+	log.WithFields(timings).Info("conditional AI control mode switch completed")
+	return true, nil
+}
+
+func (m *Manager) SwitchToMCP(preempt func() error) error {
+	return m.Switch(ModeMCP, preempt)
+}
+
+func (m *Manager) SwitchToMCPWithPreempt(preempt func() error) error {
+	return m.Switch(ModeMCP, preempt)
+}
+
+func (m *Manager) SwitchToPicoclaw(preempt func() error) error {
+	return m.Switch(ModePicoclaw, preempt)
+}
+
+func (m *Manager) SwitchToPicoclawWithPreempt(preempt func() error) error {
+	return m.Switch(ModePicoclaw, preempt)
+}
+
+func (m *Manager) SwitchOff(preempt func() error) error {
+	return m.Switch(ModeOff, preempt)
+}
+
+func (m *Manager) SwitchOffIf(expected Mode, preempt func() error) (bool, error) {
+	return m.SwitchIf(expected, ModeOff, preempt)
+}
+
+func (m *Manager) SwitchOffIfWithPreempt(expected Mode, preempt func() error) (bool, error) {
+	return m.SwitchIf(expected, ModeOff, preempt)
+}
+
+func callModeTransitionHook(hook func() error) (err error) {
+	defer func() {
+		if recovered := recover(); recovered != nil {
+			err = fmt.Errorf("panic: %v", recovered)
+		}
+	}()
+	return hook()
+}
+
+func (m *Manager) setTransitioning(transitioning bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.transitioning = transitioning
+}
+
+func (m *Manager) setLastError(err error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if err == nil {
+		m.lastError = ""
+		return
+	}
+	m.lastError = err.Error()
+}
+
+func (m *Manager) statusLocked() Status {
+	return Status{
+		Mode:          m.mode,
+		Transitioning: m.transitioning,
+		LastError:     m.lastError,
+		ChangedAt:     m.changedAt,
+	}
+}
+
+func (m *Manager) acquireExclusiveActivity() (func(), error) {
+	timeout := m.activityWaitTimeout
+	if timeout <= 0 {
+		timeout = defaultActivityWaitTimeout
+	}
+
+	release, err := m.activity.acquireExclusive(timeout)
+	if err != nil {
+		return nil, fmt.Errorf("wait for active control operations: %w", err)
+	}
+	return release, nil
+}
+
+func (m *Manager) save(mode Mode) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.saveLocked(mode)
+}
+
+func (m *Manager) loadLocked() error {
+	if m.loaded && m.transitioning {
+		return nil
+	}
+
+	info, statErr := os.Stat(m.path)
+	if m.loaded && statErr == nil && m.modeFileExists && info.Size() == m.modeFileSize && info.ModTime().Equal(m.modeFileModTime) {
+		return nil
+	}
+	if m.loaded && errors.Is(statErr, os.ErrNotExist) && !m.modeFileExists {
+		return nil
+	}
+	if statErr != nil && !errors.Is(statErr, os.ErrNotExist) {
+		return fmt.Errorf("stat AI control mode: %w", statErr)
+	}
+
+	data, err := os.ReadFile(m.path)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			m.mode = m.defaultMode
+			m.loaded = true
+			m.modeFileExists = false
+			m.modeFileSize = 0
+			m.modeFileModTime = time.Time{}
+			if m.changedAt.IsZero() {
+				m.changedAt = time.Now()
+			}
+			return nil
+		}
+		return fmt.Errorf("read AI control mode: %w", err)
+	}
+
+	mode := Mode(strings.TrimSpace(string(data)))
+	if !validMode(mode) {
+		m.mode = ModeOff
+		m.loaded = true
+		m.lastError = fmt.Sprintf("invalid AI control mode %q", strings.TrimSpace(string(data)))
+		m.cacheModeFileInfoLocked(info, data)
+		return nil
+	}
+	m.mode = mode
+	m.loaded = true
+	m.lastError = ""
+	m.cacheModeFileInfoLocked(info, data)
+	return nil
+}
+
+func (m *Manager) saveLocked(mode Mode) error {
+	if !validMode(mode) {
+		return fmt.Errorf("invalid AI control mode %q", mode)
+	}
+
+	dir := filepath.Dir(m.path)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return fmt.Errorf("create AI control mode directory: %w", err)
+	}
+
+	tmp, err := os.CreateTemp(dir, ".ai-control.mode.*")
+	if err != nil {
+		return fmt.Errorf("create temporary AI control mode: %w", err)
+	}
+	tmpPath := tmp.Name()
+	defer func() { _ = os.Remove(tmpPath) }()
+
+	if err := tmp.Chmod(0o600); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("set AI control mode permissions: %w", err)
+	}
+	if _, err := tmp.WriteString(string(mode) + "\n"); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("write AI control mode: %w", err)
+	}
+	if err := tmp.Sync(); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("sync AI control mode: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("close AI control mode: %w", err)
+	}
+	if err := os.Rename(tmpPath, m.path); err != nil {
+		return fmt.Errorf("replace AI control mode: %w", err)
+	}
+	m.mode = mode
+	m.loaded = true
+	if info, err := os.Stat(m.path); err == nil {
+		m.cacheModeFileInfoLocked(info, []byte(string(mode)+"\n"))
+	} else {
+		m.modeFileExists = true
+		m.modeFileSize = int64(len(string(mode) + "\n"))
+		m.modeFileModTime = time.Now()
+	}
+	m.changedAt = time.Now()
+
+	directory, err := os.Open(dir)
+	if err == nil {
+		if syncErr := directory.Sync(); syncErr != nil {
+			_ = directory.Close()
+			return fmt.Errorf("sync AI control mode directory: %w", syncErr)
+		}
+		_ = directory.Close()
+	}
+
+	return nil
+}
+
+func (m *Manager) cacheModeFileInfoLocked(info os.FileInfo, data []byte) {
+	m.modeFileExists = true
+	if info != nil {
+		m.modeFileSize = info.Size()
+		m.modeFileModTime = info.ModTime()
+		if m.changedAt.IsZero() || info.ModTime().After(m.changedAt) {
+			m.changedAt = info.ModTime()
+		}
+		return
+	}
+	m.modeFileSize = int64(len(data))
+	m.modeFileModTime = time.Now()
+	m.changedAt = m.modeFileModTime
+}
+
+func validMode(mode Mode) bool {
+	switch mode {
+	case ModeOff, ModeMCP, ModePicoclaw:
+		return true
+	default:
+		return false
+	}
+}
+
+func elapsedMilliseconds(startedAt time.Time) int64 {
+	return time.Since(startedAt).Milliseconds()
+}
+
+func logModeSwitchFailure(message string, fields log.Fields, err error, startedAt time.Time) {
+	fields["total_ms"] = elapsedMilliseconds(startedAt)
+	log.WithFields(fields).WithError(err).Warn(message)
+}

server/service/controlmode/manager_test.go

@@ -0,0 +1,202 @@
+package controlmode
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestManagerDefaultsToPicoclaw(t *testing.T) {
+	manager := NewManager(filepath.Join(t.TempDir(), "mode"), ModePicoclaw)
+	if got := manager.Current(); got != ModePicoclaw {
+		t.Fatalf("mode = %q, want %q", got, ModePicoclaw)
+	}
+}
+
+func TestSwitchPreemptsBeforeWaitingForActiveWrite(t *testing.T) {
+	manager := NewManager(filepath.Join(t.TempDir(), "mode"), ModeMCP)
+	release, err := manager.AcquireWrite(ModeMCP)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	preempted := make(chan struct{})
+	done := make(chan error, 1)
+	go func() {
+		done <- manager.Switch(ModePicoclaw, func() error {
+			close(preempted)
+			return nil
+		})
+	}()
+
+	select {
+	case <-preempted:
+	case <-time.After(time.Second):
+		t.Fatal("preempt callback was not called before waiting")
+	}
+	if _, err := manager.AcquireWrite(ModeMCP); err == nil {
+		t.Fatal("new write acquired control during transition")
+	}
+
+	release()
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatal(err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("switch did not resume after active write was released")
+	}
+	if got := manager.Current(); got != ModePicoclaw {
+		t.Fatalf("mode = %q, want picoclaw", got)
+	}
+}
+
+func TestSwitchRunsCleanupAfterActiveWritesDrain(t *testing.T) {
+	manager := NewManager(filepath.Join(t.TempDir(), "mode"), ModePicoclaw)
+	release, err := manager.AcquireWrite(ModePicoclaw)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	cleanupCalled := make(chan struct{})
+	done := make(chan error, 1)
+	go func() {
+		done <- manager.SwitchWithCleanup(ModeMCP, nil, func() error {
+			close(cleanupCalled)
+			return nil
+		})
+	}()
+
+	select {
+	case <-cleanupCalled:
+		t.Fatal("cleanup ran before active write drained")
+	case <-time.After(20 * time.Millisecond):
+	}
+
+	release()
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatal(err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("switch did not finish")
+	}
+	select {
+	case <-cleanupCalled:
+	default:
+		t.Fatal("cleanup was not called")
+	}
+}
+
+func TestSwitchCleanupFailureFailsClosed(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "mode")
+	manager := NewManager(path, ModePicoclaw)
+	wantErr := errors.New("hid release failed")
+
+	if err := manager.SwitchWithCleanup(ModeMCP, nil, func() error { return wantErr }); !errors.Is(err, wantErr) {
+		t.Fatalf("error = %v, want %v", err, wantErr)
+	}
+	if got := manager.Current(); got != ModeOff {
+		t.Fatalf("mode = %q, want off after cleanup failure", got)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(data) != "off\n" {
+		t.Fatalf("mode file = %q, want off", data)
+	}
+}
+
+func TestSwitchIfKeepsDifferentMode(t *testing.T) {
+	manager := NewManager(filepath.Join(t.TempDir(), "mode"), ModePicoclaw)
+	switched, err := manager.SwitchIf(ModeMCP, ModeOff, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if switched || manager.Current() != ModePicoclaw {
+		t.Fatalf("switched=%v mode=%q, want unchanged picoclaw", switched, manager.Current())
+	}
+}
+
+func TestSwitchTimeoutDoesNotLeaveManagerTransitioning(t *testing.T) {
+	manager := NewManager(filepath.Join(t.TempDir(), "mode"), ModeMCP)
+	manager.activityWaitTimeout = 20 * time.Millisecond
+	cleanupCalled := false
+
+	status, release, err := manager.AcquireStable()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if status.Mode != ModeMCP {
+		t.Fatalf("mode = %q, want MCP", status.Mode)
+	}
+
+	err = manager.SwitchWithCleanup(ModePicoclaw, nil, func() error {
+		cleanupCalled = true
+		return nil
+	})
+	if !errors.Is(err, ErrActivityWaitTimeout) {
+		t.Fatalf("switch error = %v, want %v", err, ErrActivityWaitTimeout)
+	}
+	if cleanupCalled {
+		t.Fatal("cleanup ran even though exclusive activity lease was not acquired")
+	}
+	status, err = manager.Status()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if status.Mode != ModeMCP || status.Transitioning {
+		t.Fatalf("status after timeout = %+v, want stable MCP", status)
+	}
+
+	release()
+	if err := manager.Switch(ModePicoclaw, nil); err != nil {
+		t.Fatalf("switch after lease release failed: %v", err)
+	}
+}
+
+func TestInvalidModeFailsClosed(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "mode")
+	if err := os.WriteFile(path, []byte("invalid\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	manager := NewManager(path, ModePicoclaw)
+	status, err := manager.Status()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if status.Mode != ModeOff {
+		t.Fatalf("mode = %q, want off", status.Mode)
+	}
+	if !strings.Contains(status.LastError, "invalid") {
+		t.Fatalf("last_error = %q, want invalid mode detail", status.LastError)
+	}
+}
+
+func TestStatusReloadsExternallyModifiedModeFile(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "mode")
+	if err := os.WriteFile(path, []byte("off\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	manager := NewManager(path, ModePicoclaw)
+	if got := manager.Current(); got != ModeOff {
+		t.Fatalf("initial mode = %q, want off", got)
+	}
+
+	if err := os.WriteFile(path, []byte("mcp\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	modTime := time.Now().Add(time.Second)
+	if err := os.Chtimes(path, modTime, modTime); err != nil {
+		t.Fatal(err)
+	}
+	if got := manager.Current(); got != ModeMCP {
+		t.Fatalf("mode after external write = %q, want MCP", got)
+	}
+}

server/service/download/service.go

@@ -2,54 +2,166 @@ package download
 
 import (
 	"NanoKVM-Server/proto"
+	"NanoKVM-Server/utils"
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
 	"fmt"
-	"github.com/gin-gonic/gin"
-	log "github.com/sirupsen/logrus"
 	"io"
 	"net/http"
 	"net/url"
 	"os"
 	"path/filepath"
-	"strings"
-	"time"
 	"regexp"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	log "github.com/sirupsen/logrus"
 )
 
-type Service struct{}
+type downloadStatus string
 
-var sentinelPath = "/tmp/.download_in_progress"
+const (
+	transferSentinelPath                        = utils.TransferSentinelPath
+	downloadStatusIdle           downloadStatus = "idle"
+	downloadStatusInProgress     downloadStatus = "in_progress"
+	downloadStatusSuccess        downloadStatus = "success"
+	downloadStatusFailed         downloadStatus = "failed"
+	downloadStatusChecksumFailed downloadStatus = "checksum_failed"
+)
+
+var (
+	errDownloadInProgress = errors.New("download in progress")
+	errSHA256Mismatch     = errors.New("sha256 mismatch")
+	validISOFilename      = regexp.MustCompile(`^[a-zA-Z0-9._-]+$`)
+)
+
+type Service struct {
+	downloadMutex      sync.Mutex
+	downloadCancel     context.CancelFunc
+	downloadDone       chan struct{}
+	downloadStatus     downloadStatus
+	downloadFile       string
+	downloadPercentage string
+}
 
 func NewService() *Service {
-	// Clear sentinel
-	// If we are starting from scratch, we need to remove the sentinel file as any downloads at this point are done or broken
-	_ = os.Remove(sentinelPath)
-	return &Service{}
+	// A running transfer cannot survive a server restart, so any remaining lock
+	// file is stale at this point.
+	_ = os.Remove(transferSentinelPath)
+	return &Service{downloadStatus: downloadStatusIdle}
+}
+
+func (s *Service) CancelDownloadImage(c *gin.Context) {
+	var rsp proto.Response
+
+	s.downloadMutex.Lock()
+	cancel := s.downloadCancel
+	done := s.downloadDone
+	s.downloadMutex.Unlock()
+
+	if cancel == nil || done == nil {
+		rsp.ErrRsp(c, -1, "no cancellable download in progress")
+		return
+	}
+
+	cancel()
+	select {
+	case <-done:
+		rsp.OkRsp(c)
+	case <-time.After(10 * time.Second):
+		rsp.ErrRsp(c, -1, "cancel download timed out")
+	}
+}
+
+func (s *Service) beginDownload(file string, cancel context.CancelFunc) (chan struct{}, error) {
+	s.downloadMutex.Lock()
+	defer s.downloadMutex.Unlock()
+
+	if s.downloadDone != nil {
+		return nil, errDownloadInProgress
+	}
+
+	lockFile, err := os.OpenFile(
+		transferSentinelPath,
+		os.O_WRONLY|os.O_CREATE|os.O_EXCL,
+		0o644,
+	)
+	if err != nil {
+		if os.IsExist(err) {
+			return nil, errDownloadInProgress
+		}
+		return nil, fmt.Errorf("acquire transfer lock failed: %w", err)
+	}
+	if err := lockFile.Close(); err != nil {
+		_ = os.Remove(transferSentinelPath)
+		return nil, fmt.Errorf("close transfer lock failed: %w", err)
+	}
+
+	done := make(chan struct{})
+	s.downloadCancel = cancel
+	s.downloadDone = done
+	s.downloadStatus = downloadStatusInProgress
+	s.downloadFile = file
+	s.downloadPercentage = ""
+
+	return done, nil
+}
+
+func (s *Service) setDownloadFile(done chan struct{}, file string) {
+	s.downloadMutex.Lock()
+	defer s.downloadMutex.Unlock()
+
+	if s.downloadDone == done {
+		s.downloadFile = file
+	}
+}
+
+func (s *Service) setDownloadProgress(done chan struct{}, percentage string) {
+	s.downloadMutex.Lock()
+	defer s.downloadMutex.Unlock()
+
+	if s.downloadDone == done {
+		s.downloadPercentage = percentage
+	}
+}
+
+func (s *Service) finishDownload(done chan struct{}, status downloadStatus) {
+	s.downloadMutex.Lock()
+	if s.downloadDone != done {
+		s.downloadMutex.Unlock()
+		return
+	}
+
+	s.downloadCancel = nil
+	s.downloadDone = nil
+	s.downloadStatus = status
+	s.downloadFile = ""
+	s.downloadPercentage = ""
+	_ = os.Remove(transferSentinelPath)
+	s.downloadMutex.Unlock()
+
+	close(done)
 }
 
 func (s *Service) ImageEnabled(c *gin.Context) {
 	var rsp proto.Response
 
-	// Check if /data mount is RO/RW
 	testFile := "/data/.testfile"
 	file, err := os.Create(testFile)
-	defer file.Close()
-	defer os.Remove(testFile)
 	if err != nil {
-		if os.IsPermission(err) {
-			rsp.OkRspWithData(c, &proto.ImageEnabledRsp{
-				Enabled: false,
-			})
-			return
-		}
-		rsp.OkRspWithData(c, &proto.ImageEnabledRsp{
-			Enabled: false,
-		})
+		rsp.OkRspWithData(c, &proto.ImageEnabledRsp{Enabled: false})
 		return
 	}
+	defer file.Close()
+	defer os.Remove(testFile)
 
-	rsp.OkRspWithData(c, &proto.ImageEnabledRsp{
-		Enabled: true,
-	})
+	rsp.OkRspWithData(c, &proto.ImageEnabledRsp{Enabled: true})
 }
 
 func isISO9660(path string) (bool, error) {
@@ -59,15 +171,13 @@ func isISO9660(path string) (bool, error) {
 	}
 	defer f.Close()
 
-	// ISO-9660 Magic "CD001" bei Offset 32769
-	_, err = f.Seek(0x8001, io.SeekStart)
-	if err != nil {
+	// ISO-9660 magic "CD001" at offset 32769.
+	if _, err = f.Seek(0x8001, io.SeekStart); err != nil {
 		return false, err
 	}
 
 	buf := make([]byte, 5)
-	_, err = io.ReadFull(f, buf)
-	if err != nil {
+	if _, err = io.ReadFull(f, buf); err != nil {
 		return false, err
 	}
 
@@ -77,211 +187,141 @@ func isISO9660(path string) (bool, error) {
 func (s *Service) StatusImage(c *gin.Context) {
 	var rsp proto.Response
 
-	// Check if the sentinel file exists
-	log.Debug("StatusImage")
-	if _, err := os.Stat(sentinelPath); err == nil {
-		content, err := os.ReadFile(sentinelPath)
-		if err != nil {
-			log.Error("Failed to read sentinel file")
-			rsp.OkRspWithData(c, &proto.StatusImageRsp{
-				Status:     "in_progress",
-				File:       "",
-				Percentage: "",
-			})
-			return
-		}
-		splitted := strings.Split(string(content), ";")
-		if len(splitted) == 1 {
-			// No percentage, just the URL
-			rsp.OkRspWithData(c, &proto.StatusImageRsp{
-				Status:     "in_progress",
-				File:       splitted[0],
-				Percentage: "",
-			})
-		} else {
-			// Percentage is available
-			rsp.OkRspWithData(c, &proto.StatusImageRsp{
-				Status:     "in_progress",
-				File:       splitted[0],
-				Percentage: splitted[1],
-			})
-		}
+	s.downloadMutex.Lock()
+	status := s.downloadStatus
+	file := s.downloadFile
+	percentage := s.downloadPercentage
+	s.downloadMutex.Unlock()
 
-		return
-	}
 	rsp.OkRspWithData(c, &proto.StatusImageRsp{
-		Status:     "idle",
-		File:       "",
-		Percentage: "",
+		Status:     string(status),
+		File:       file,
+		Percentage: percentage,
 	})
 }
 
 func (s *Service) DownloadImageFile(c *gin.Context) {
 	var rsp proto.Response
 
-	log.Debug("DownloadImage")
-
-	// Set a sentinel file to mark that there is a download in progress
-	// This is to prevent multiple downloads at the same time
-	if _, err := os.Stat(sentinelPath); err == nil {
-		log.Debug("Download in progress")
-		rsp.ErrRsp(c, -1, "download in progress")
-		return
-	}
-
-	// Create the sentinel file
-	err := os.WriteFile(sentinelPath, []byte("start"), 0644)
+	log.Debug("DownloadImageFile")
+	expectedSHA256, err := parseSHA256(c.GetHeader("X-SHA256-Sum"))
 	if err != nil {
-		log.Error("Failed to create sentinel file")
-		rsp.ErrRsp(c, -1, "failed to create sentinel file")
+		rsp.ErrRsp(c, -1, err.Error())
 		return
 	}
 
-    // Multipart Reader direkt nutzen (keine FormFile!)
-    reader, err := c.Request.MultipartReader()
-    if err != nil {
+	done, err := s.beginDownload("", nil)
+	if err != nil {
+		rsp.ErrRsp(c, -1, err.Error())
+		return
+	}
+	finalStatus := downloadStatusFailed
+	defer func() {
+		s.finishDownload(done, finalStatus)
+	}()
+
+	reader, err := c.Request.MultipartReader()
+	if err != nil {
 		log.Error("invalid multipart data")
 		rsp.ErrRsp(c, -1, "invalid multipart data")
-		defer os.Remove(sentinelPath)
-        return
-    }
+		return
+	}
 
-	
-	var lw *loggingWriter
-
-    for {
-        part, err := reader.NextPart()
-        if err == io.EOF {
-            break
-        }
-        if err != nil {
+	for {
+		part, err := reader.NextPart()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
 			log.Error("failed to read part")
 			rsp.ErrRsp(c, -1, "failed to read part")
-			lw.stopTicker()
-			defer os.Remove(sentinelPath)
-            return
-        }
-
-        if part.FormName() != "file" {
-            continue
-        }
-
-        filename := part.FileName()
-        if filename == "" {
-			log.Error("no filename")
-			rsp.ErrRsp(c, -1, "no filename")
-			lw.stopTicker()
-			defer os.Remove(sentinelPath)
-            return
-        }
-
-		filename = filepath.Base(filename)
-
-		if filename != part.FileName() {
-			log.Warn("path detected in filename")
-			rsp.ErrRsp(c, -1, "invalid filename")
-			defer os.Remove(sentinelPath)
 			return
 		}
-
-		if strings.Contains(filename, "..") {
-			log.Warn("path traversal attempt")
-			rsp.ErrRsp(c, -1, "invalid filename")
-			defer os.Remove(sentinelPath)
-			return
+		if part.FormName() != "file" {
+			_ = part.Close()
+			continue
 		}
 
-		if !strings.HasSuffix(strings.ToLower(filename), ".iso") {
-			rsp.ErrRsp(c, -1, "only .iso files allowed")
-			defer os.Remove(sentinelPath)
+		filename := part.FileName()
+		if err := validateISOFilename(filename); err != nil {
+			_ = part.Close()
+			rsp.ErrRsp(c, -1, err.Error())
 			return
 		}
+		s.setDownloadFile(done, filename)
 
-		valid := regexp.MustCompile(`^[a-zA-Z0-9._-]+$`)
-		if !valid.MatchString(filename) {
-			rsp.ErrRsp(c, -1, "invalid filename")
-			defer os.Remove(sentinelPath)
-			return
-		}
-
-		data, err := os.ReadFile(sentinelPath)
+		out, err := os.CreateTemp("/data", ".nanokvm-upload-*")
 		if err != nil {
-			log.Error("Read failed")
-			rsp.ErrRsp(c, -1, "Read failed")
-			lw.stopTicker()
-			defer os.Remove(sentinelPath)
+			_ = part.Close()
+			log.Error("cannot create temporary file")
+			rsp.ErrRsp(c, -1, "cannot create temporary file")
 			return
 		}
+		tempPath := out.Name()
+		defer os.Remove(tempPath)
 
-        outPath := "/data/" + filename
-        out, err := os.Create(outPath)
-        if err != nil {
-			log.Error("cannot create file")
-			rsp.ErrRsp(c, -1, "cannot create file")
-			lw.stopTicker()
-			defer os.Remove(sentinelPath)
-            return
-        }
-        defer out.Close()
-
-		if strings.Contains(string(data), "start") {
-			err = os.WriteFile(sentinelPath, []byte(filename), 0644)
-			if err != nil {
-				log.Error("Failed to create sentinel file")
-				rsp.ErrRsp(c, -1, "failed to create sentinel file")
-				lw.stopTicker()
-				defer os.Remove(outPath)
-				defer os.Remove(sentinelPath)
-				return
-			}
-			
-			lw = &loggingWriter{writer: out, totalSize: c.Request.ContentLength}
-			lw.startTicker()
-		} else {
-			if !strings.Contains(string(data), filename) {
-				log.Error("failed")
-				rsp.ErrRsp(c, -1, "failed")
-				lw.stopTicker()
-				defer os.Remove(outPath)
-				defer os.Remove(sentinelPath)
-				return
-			}
-		}
-
-        // Direkt streamen → kein RAM-Bedarf außer kleinem Buffer
-        _, err = io.Copy(lw, part)
-        if err != nil {
+		hasher := sha256.New()
+		lw := newLoggingWriter(io.MultiWriter(out, hasher), c.Request.ContentLength, func(percentage string) {
+			s.setDownloadProgress(done, percentage)
+		})
+		_, copyErr := io.Copy(lw, part)
+		lw.stopTicker()
+		partCloseErr := part.Close()
+		outCloseErr := out.Close()
+		if copyErr != nil || partCloseErr != nil || outCloseErr != nil {
 			log.Error("write failed")
 			rsp.ErrRsp(c, -1, "write failed")
-			lw.stopTicker()
-			defer os.Remove(outPath)
-			defer os.Remove(sentinelPath)
-            return
-        }
-
-		ok, err := isISO9660(outPath)
-		if err != nil || !ok {
-			rsp.ErrRsp(c, -1, "file is not a valid ISO image")
-			lw.stopTicker()
-			defer os.Remove(outPath)
-			defer os.Remove(sentinelPath)
 			return
 		}
-    }
-	lw.stopTicker()
 
-	rsp.OkRspWithData(c, &proto.StatusImageRsp{
-		Status:     "idle",
-		File:       "",
-		Percentage: "",
-	})
-	
-	defer os.Remove(sentinelPath)
-    return
+		if expectedSHA256 != nil && !bytes.Equal(hasher.Sum(nil), expectedSHA256) {
+			finalStatus = downloadStatusChecksumFailed
+			rsp.ErrRsp(c, -1, errSHA256Mismatch.Error())
+			return
+		}
+
+		valid, err := isISO9660(tempPath)
+		if err != nil || !valid {
+			rsp.ErrRsp(c, -1, "file is not a valid ISO image")
+			return
+		}
+
+		outPath := filepath.Join("/data", filename)
+		if err := os.Rename(tempPath, outPath); err != nil {
+			rsp.ErrRsp(c, -1, "cannot install uploaded image")
+			return
+		}
+
+		finalStatus = downloadStatusIdle
+		rsp.OkRspWithData(c, &proto.StatusImageRsp{
+			Status:     string(downloadStatusIdle),
+			File:       "",
+			Percentage: "",
+		})
+		return
+	}
+
+	rsp.ErrRsp(c, -1, "file is required")
+}
+
+func validateISOFilename(filename string) error {
+	if filename == "" {
+		return errors.New("no filename")
+	}
+	if filepath.Base(filename) != filename || strings.Contains(filename, "..") {
+		return errors.New("invalid filename")
+	}
+	if !strings.HasSuffix(strings.ToLower(filename), ".iso") {
+		return errors.New("only .iso files allowed")
+	}
+	if !validISOFilename.MatchString(filename) {
+		return errors.New("invalid filename")
+	}
+	return nil
 }
 
 func (s *Service) DownloadImage(c *gin.Context) {
-	var req proto.MountImageReq
+	var req proto.DownloadImageReq
 	var rsp proto.Response
 
 	log.Debug("DownloadImage")
@@ -291,127 +331,190 @@ func (s *Service) DownloadImage(c *gin.Context) {
 		return
 	}
 
-	if req.File == "" {
-		rsp.ErrRsp(c, -1, "invalid arguments")
+	expectedSHA256, err := parseSHA256(req.SHA256Sum)
+	if err != nil {
+		rsp.ErrRsp(c, -1, err.Error())
 		return
 	}
-	// Parse the URI to see if its valid http/s
+
 	u, err := url.Parse(req.File)
-	if err != nil || u.Scheme == "" || u.Host == "" {
+	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" || u.Path == "" {
+		rsp.ErrRsp(c, -1, "invalid url")
+		return
+	}
+	filename := filepath.Base(u.Path)
+	if filename == "." || filename == "/" || filename == "" {
 		rsp.ErrRsp(c, -1, "invalid url")
 		return
 	}
 
-	// Set a sentinel file to mark that there is a download in progress
-	// This is to prevent multiple downloads at the same time
-	if _, err := os.Stat(sentinelPath); err == nil {
-		log.Debug("Download in progress")
-		rsp.ErrRsp(c, -1, "download in progress")
-		return
-	}
-	// Create the sentinel file
-	err = os.WriteFile(sentinelPath, []byte(req.File), 0644)
+	ctx, cancel := context.WithCancel(context.Background())
+	done, err := s.beginDownload(req.File, cancel)
 	if err != nil {
-		log.Error("Failed to create sentinel file")
-		rsp.ErrRsp(c, -1, "failed to create sentinel file")
+		cancel()
+		rsp.ErrRsp(c, -1, err.Error())
 		return
 	}
 
-	// Check if it actually exists and fail if it doesn't
-	resp, err := http.Head(req.File)
-	if resp.StatusCode != http.StatusOK || err != nil {
-		rsp.ErrRsp(c, resp.StatusCode, "failed when checking the url")
-		log.Error("Failed to check the URL")
-		defer os.Remove(sentinelPath)
-		return
-	}
-	defer resp.Body.Close()
-
-	// Download the image in a goroutine to not block the request
 	go func() {
-		defer os.Remove(sentinelPath)
-		resp, err = http.Get(req.File)
-		if err != nil {
-			log.Error("Failed to download the file")
-			rsp.ErrRsp(c, -1, "failed to download the file")
-			return
-		}
-		defer resp.Body.Close()
-		// Create the destination file
-		destPath := filepath.Join("/data", filepath.Base(u.Path))
-		out, err := os.Create(destPath)
-		if err != nil {
-			log.Error("Failed to create destination file")
-			rsp.ErrRsp(c, -1, "failed to create destination file")
-			return
-		}
-		defer out.Close()
+		defer cancel()
 
-		lw := &loggingWriter{writer: out, totalSize: resp.ContentLength}
-		lw.startTicker()
-		_, err = io.Copy(lw, resp.Body)
-		if err != nil {
-			log.Error("Failed to save the file")
-			rsp.ErrRsp(c, -1, "failed to save the file")
-			lw.stopTicker()
+		if err := s.downloadRemoteImage(ctx, req.File, expectedSHA256, filename, func(percentage string) {
+			s.setDownloadProgress(done, percentage)
+		}); err != nil {
+			if errors.Is(err, context.Canceled) {
+				log.Debug("Image download canceled")
+				s.finishDownload(done, downloadStatusIdle)
+				return
+			}
+
+			log.Errorf("Failed to download image: %v", err)
+			status := downloadStatusFailed
+			if errors.Is(err, errSHA256Mismatch) {
+				status = downloadStatusChecksumFailed
+			}
+			s.finishDownload(done, status)
 			return
 		}
-		lw.stopTicker()
+		s.finishDownload(done, downloadStatusSuccess)
 	}()
+
 	rsp.OkRspWithData(c, &proto.StatusImageRsp{
-		Status:     "in_progress",
+		Status:     string(downloadStatusInProgress),
 		File:       req.File,
 		Percentage: "",
 	})
 }
 
+func parseSHA256(value string) ([]byte, error) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return nil, nil
+	}
+
+	sum, err := hex.DecodeString(value)
+	if err != nil || len(sum) != sha256.Size {
+		return nil, errors.New("invalid sha256sum")
+	}
+
+	return sum, nil
+}
+
+func (s *Service) downloadRemoteImage(
+	ctx context.Context,
+	rawURL string,
+	expectedSHA256 []byte,
+	filename string,
+	onProgress func(string),
+) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
+	if err != nil {
+		return fmt.Errorf("create download request failed: %w", err)
+	}
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("download request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("download request returned status %d", resp.StatusCode)
+	}
+
+	tempFile, err := os.CreateTemp("/data", ".nanokvm-download-*")
+	if err != nil {
+		return fmt.Errorf("create temporary image failed: %w", err)
+	}
+	tempPath := tempFile.Name()
+	defer os.Remove(tempPath)
+
+	hasher := sha256.New()
+	lw := newLoggingWriter(io.MultiWriter(tempFile, hasher), resp.ContentLength, onProgress)
+	_, copyErr := io.Copy(lw, resp.Body)
+	lw.stopTicker()
+	closeErr := tempFile.Close()
+	if ctx.Err() != nil {
+		return ctx.Err()
+	}
+	if copyErr != nil {
+		return fmt.Errorf("save downloaded image failed: %w", copyErr)
+	}
+	if closeErr != nil {
+		return fmt.Errorf("close downloaded image failed: %w", closeErr)
+	}
+
+	if expectedSHA256 != nil && !bytes.Equal(hasher.Sum(nil), expectedSHA256) {
+		return errSHA256Mismatch
+	}
+	if ctx.Err() != nil {
+		return ctx.Err()
+	}
+
+	destPath := filepath.Join("/data", filename)
+	if err := os.Rename(tempPath, destPath); err != nil {
+		return fmt.Errorf("install downloaded image failed: %w", err)
+	}
+
+	return nil
+}
+
 type loggingWriter struct {
-	writer    io.Writer
-	total     int64
-	totalSize int64
-	ticker    *time.Ticker
-	done      chan bool
+	writer     io.Writer
+	total      atomic.Int64
+	totalSize  int64
+	ticker     *time.Ticker
+	done       chan struct{}
+	stopOnce   sync.Once
+	onProgress func(string)
+}
+
+func newLoggingWriter(writer io.Writer, totalSize int64, onProgress func(string)) *loggingWriter {
+	lw := &loggingWriter{
+		writer:     writer,
+		totalSize:  totalSize,
+		onProgress: onProgress,
+	}
+	lw.startTicker()
+	return lw
 }
 
 func (lw *loggingWriter) startTicker() {
 	lw.ticker = time.NewTicker(2500 * time.Millisecond)
-	lw.done = make(chan bool)
+	lw.done = make(chan struct{})
 	go func() {
 		for {
 			select {
 			case <-lw.done:
 				return
 			case <-lw.ticker.C:
-				lw.updateSentinel()
+				lw.updateProgress()
 			}
 		}
 	}()
 }
 
 func (lw *loggingWriter) stopTicker() {
-	lw.ticker.Stop()
-	lw.done <- true
+	if lw == nil {
+		return
+	}
+	lw.stopOnce.Do(func() {
+		lw.ticker.Stop()
+		close(lw.done)
+	})
 }
 
-func (lw *loggingWriter) updateSentinel() {
-	percentage := float64(lw.total) / float64(lw.totalSize) * 100
-	content, err := os.ReadFile(sentinelPath)
-	if err != nil {
-		log.Error("Failed to read sentinel file")
+func (lw *loggingWriter) updateProgress() {
+	if lw.totalSize <= 0 || lw.onProgress == nil {
 		return
 	}
-	splitted := strings.Split(string(content), ";")
-	if len(splitted) == 0 {
-		return
-	}
-	err = os.WriteFile(sentinelPath, []byte(fmt.Sprintf("%s;%.2f%%", splitted[0], percentage)), 0644)
-	if err != nil {
-		log.Error("Failed to update sentinel file")
-	}
+
+	percentage := float64(lw.total.Load()) / float64(lw.totalSize) * 100
+	lw.onProgress(fmt.Sprintf("%.2f%%", percentage))
 }
 
 func (lw *loggingWriter) Write(p []byte) (int, error) {
 	n, err := lw.writer.Write(p)
-	lw.total += int64(n)
+	lw.total.Add(int64(n))
 	return n, err
 }

server/service/extensions/tailscale/service.go

@@ -20,11 +20,13 @@ const (
 )
 
 var StateMap = map[string]proto.TailscaleState{
-	"NoState":    proto.TailscaleNotRunning,
-	"Starting":   proto.TailscaleNotRunning,
-	"NeedsLogin": proto.TailscaleNotLogin,
-	"Running":    proto.TailscaleRunning,
-	"Stopped":    proto.TailscaleStopped,
+	"NoState":          proto.TailscaleNotRunning,
+	"Starting":         proto.TailscaleNotRunning,
+	"NeedsLogin":       proto.TailscaleNotLogin,
+	"NeedsMachineAuth": proto.TailscaleNotLogin,
+	"InUseOtherUser":   proto.TailscaleNotLogin,
+	"Running":          proto.TailscaleRunning,
+	"Stopped":          proto.TailscaleStopped,
 }
 
 func NewService() *Service {

server/service/hid/hid.go

@@ -2,19 +2,28 @@ package hid
 
 import (
 	"errors"
+	"fmt"
+	"io"
 	"os"
 	"sync"
+	"syscall"
 	"time"
 
 	log "github.com/sirupsen/logrus"
 )
 
 type Hid struct {
-	g0         *os.File
-	g1         *os.File
-	g2         *os.File
-	kbMutex    sync.Mutex
-	mouseMutex sync.Mutex
+	g0                     *os.File
+	g0Reader               *os.File
+	g1                     *os.File
+	g2                     *os.File
+	ledReaderNotifyReader  *os.File
+	ledReaderNotifyWriter  *os.File
+	ledReaderNotifyReadFD  int
+	ledReaderNotifyWriteFD int
+	kbMutex                sync.Mutex
+	mouseMutex             sync.Mutex
+	ledReaderStartOnce     sync.Once
 }
 
 const (
@@ -23,6 +32,24 @@ const (
 	HID2 = "/dev/hidg2" // Touchpad (Absolute Mode)
 )
 
+const (
+	hidWriteTimeout     = 50 * time.Millisecond
+	hidWriteRetryDelay  = time.Millisecond
+	hidReopenTimeout    = 2 * time.Second
+	hidReopenRetryDelay = 100 * time.Millisecond
+)
+
+type hidWriter interface {
+	Write([]byte) (int, error)
+}
+
+type hidDevice struct {
+	path string
+	mu   *sync.Mutex
+	get  func() *os.File
+	set  func(*os.File)
+}
+
 var (
 	hid     *Hid
 	hidOnce sync.Once
@@ -45,33 +72,214 @@ func (h *Hid) Unlock() {
 	h.mouseMutex.Unlock()
 }
 
-func (h *Hid) OpenNoLock() {
-	var err error
-	h.CloseNoLock()
-
-	h.g0, err = os.OpenFile(HID0, os.O_WRONLY, 0o666)
-	if err != nil {
-		log.Errorf("open %s failed: %s", HID0, err)
-	}
-
-	h.g1, err = os.OpenFile(HID1, os.O_WRONLY, 0o666)
-	if err != nil {
-		log.Errorf("open %s failed: %s", HID1, err)
-	}
-
-	h.g2, err = os.OpenFile(HID2, os.O_WRONLY, 0o666)
-	if err != nil {
-		log.Errorf("open %s failed: %s", HID2, err)
+func (h *Hid) keyboardDevice(path string) hidDevice {
+	return hidDevice{
+		path: path,
+		mu:   &h.kbMutex,
+		get: func() *os.File {
+			return h.g0
+		},
+		set: func(file *os.File) {
+			h.g0 = file
+		},
 	}
 }
 
-func (h *Hid) CloseNoLock() {
-	for _, file := range []*os.File{h.g0, h.g1, h.g2} {
-		if file != nil {
-			_ = file.Sync()
-			_ = file.Close()
+func (h *Hid) relativeMouseDevice(path string) hidDevice {
+	return hidDevice{
+		path: path,
+		mu:   &h.mouseMutex,
+		get: func() *os.File {
+			return h.g1
+		},
+		set: func(file *os.File) {
+			h.g1 = file
+		},
+	}
+}
+
+func (h *Hid) absoluteMouseDevice(path string) hidDevice {
+	return hidDevice{
+		path: path,
+		mu:   &h.mouseMutex,
+		get: func() *os.File {
+			return h.g2
+		},
+		set: func(file *os.File) {
+			h.g2 = file
+		},
+	}
+}
+
+func (h *Hid) devices() []hidDevice {
+	return []hidDevice{
+		h.keyboardDevice(HID0),
+		h.relativeMouseDevice(HID1),
+		h.absoluteMouseDevice(HID2),
+	}
+}
+
+func (h *Hid) OpenNoLock() error {
+	h.CloseNoLock()
+
+	var errs []error
+	for _, device := range h.devices() {
+		if err := h.openDeviceNoLock(device); err != nil {
+			log.Errorf("open %s failed: %s", device.path, err)
+			errs = append(errs, err)
 		}
 	}
+
+	if h.g0 != nil {
+		if err := h.openKeyboardLedReaderNoLock(); err != nil {
+			log.Errorf("open keyboard LED reader failed: %s", err)
+			errs = append(errs, err)
+		} else {
+			h.startKeyboardLedReader()
+		}
+	}
+
+	return errors.Join(errs...)
+}
+
+func (h *Hid) OpenNoLockWithRetry(timeout, delay time.Duration) error {
+	return openNoLockWithRetry(h.OpenNoLock, timeout, delay)
+}
+
+func openNoLockWithRetry(open func() error, timeout, delay time.Duration) error {
+	if timeout <= 0 {
+		return open()
+	}
+	if delay <= 0 {
+		delay = hidReopenRetryDelay
+	}
+
+	deadline := time.Now().Add(timeout)
+	var lastErr error
+	for {
+		if err := open(); err != nil {
+			lastErr = err
+		} else {
+			return nil
+		}
+
+		remaining := time.Until(deadline)
+		if remaining <= 0 {
+			break
+		}
+		if remaining > delay {
+			remaining = delay
+		}
+		time.Sleep(remaining)
+	}
+
+	return fmt.Errorf("open HID devices within %s: %w", timeout, lastErr)
+}
+
+func (h *Hid) CloseNoLock() {
+	h.closeKeyboardLedReaderNoLock()
+
+	for _, device := range h.devices() {
+		h.closeDeviceNoLock(device)
+	}
+}
+
+func (h *Hid) openDeviceNoLock(device hidDevice) error {
+	if device.get() != nil {
+		return nil
+	}
+
+	file, err := os.OpenFile(device.path, os.O_WRONLY|syscall.O_NONBLOCK, 0o666)
+	if err != nil {
+		return fmt.Errorf("%s: %w", device.path, err)
+	}
+
+	device.set(file)
+	return nil
+}
+
+func (h *Hid) closeDeviceNoLock(device hidDevice) {
+	file := device.get()
+	if file == nil {
+		return
+	}
+
+	device.set(nil)
+	if err := file.Close(); err != nil {
+		log.Debugf("close %s failed: %s", device.path, err)
+	}
+}
+
+func (h *Hid) openKeyboardLedReaderNoLock() error {
+	if h.g0Reader != nil {
+		return nil
+	}
+
+	if err := h.ensureKeyboardLedReaderNotifierNoLock(); err != nil {
+		return err
+	}
+
+	// Keep this descriptor blocking. The LED reader waits for either an output
+	// report or a lifecycle notification, so an idle host does not cause a
+	// periodic EAGAIN retry loop.
+	file, err := os.OpenFile(HID0, os.O_RDONLY, 0o666)
+	if err != nil {
+		return fmt.Errorf("%s: %w", HID0, err)
+	}
+
+	h.g0Reader = file
+	h.notifyKeyboardLedReaderNoLock()
+	return nil
+}
+
+func (h *Hid) closeKeyboardLedReaderNoLock() {
+	if h.g0Reader == nil {
+		return
+	}
+
+	file := h.g0Reader
+	h.g0Reader = nil
+	h.notifyKeyboardLedReaderNoLock()
+	if err := file.Close(); err != nil {
+		log.Debugf("close keyboard LED reader failed: %s", err)
+	}
+}
+
+// writeWithTimeout bounds how long callers hold HID locks when writing to a
+// nonblocking descriptor. EAGAIN means the host is not accepting HID reports
+// yet, so retry until the caller's deadline expires.
+func writeWithTimeout(writer hidWriter, data []byte, timeout time.Duration) error {
+	deadline := time.Now().Add(timeout)
+
+	for {
+		n, err := writer.Write(data)
+		if err == nil {
+			if n != len(data) {
+				return io.ErrShortWrite
+			}
+			return nil
+		}
+
+		if n != 0 {
+			return io.ErrShortWrite
+		}
+		if !isRetryableWriteError(err) {
+			return err
+		}
+
+		remaining := time.Until(deadline)
+		if timeout <= 0 || remaining <= 0 {
+			return os.ErrDeadlineExceeded
+		}
+		if remaining > hidWriteRetryDelay {
+			remaining = hidWriteRetryDelay
+		}
+		time.Sleep(remaining)
+	}
+}
+
+func isRetryableWriteError(err error) bool {
+	return errors.Is(err, syscall.EAGAIN) || errors.Is(err, syscall.EWOULDBLOCK)
 }
 
 func (h *Hid) Open() {
@@ -80,8 +288,6 @@ func (h *Hid) Open() {
 	h.mouseMutex.Lock()
 	defer h.mouseMutex.Unlock()
 
-	h.CloseNoLock()
-
 	h.OpenNoLock()
 }
 
@@ -95,73 +301,92 @@ func (h *Hid) Close() {
 }
 
 func (h *Hid) WriteHid0(data []byte) {
-	deadline := time.Now().Add(8 * time.Millisecond)
-
-	h.kbMutex.Lock()
-	_ = h.g0.SetWriteDeadline(deadline)
-	_, err := h.g0.Write(data)
-	h.kbMutex.Unlock()
-
-	if err != nil {
-		switch {
-		case errors.Is(err, os.ErrClosed):
-			log.Errorf("hid already closed, reopen it...")
-			h.OpenNoLock()
-		case errors.Is(err, os.ErrDeadlineExceeded):
-			log.Debugf("write to %s timeout", HID0)
-		default:
-			log.Errorf("write to %s failed: %s", HID0, err)
-		}
-		return
+	if err := h.WriteKeyboardReport(data); err != nil {
+		log.Errorf("write to %s failed: %s", HID0, err)
 	}
-
-	log.Debugf("write to %s: %v", HID0, data)
 }
 
 func (h *Hid) WriteHid1(data []byte) {
-	deadline := time.Now().Add(8 * time.Millisecond)
-
-	h.mouseMutex.Lock()
-	_ = h.g1.SetWriteDeadline(deadline)
-	_, err := h.g1.Write(data)
-	h.mouseMutex.Unlock()
-
-	if err != nil {
-		switch {
-		case errors.Is(err, os.ErrClosed):
-			log.Errorf("hid already closed, reopen it...")
-			h.OpenNoLock()
-		case errors.Is(err, os.ErrDeadlineExceeded):
-			log.Debugf("write to %s timeout", HID1)
-		default:
-			log.Errorf("write to %s failed: %s", HID1, err)
-		}
-		return
+	if err := h.WriteRelativeMouseReport(data); err != nil {
+		log.Errorf("write to %s failed: %s", HID1, err)
 	}
-
-	log.Debugf("write to %s: %v", HID1, data)
 }
 
 func (h *Hid) WriteHid2(data []byte) {
-	deadline := time.Now().Add(8 * time.Millisecond)
+	if err := h.WriteAbsoluteMouseReport(data); err != nil {
+		log.Errorf("write to %s failed: %s", HID2, err)
+	}
+}
 
-	h.mouseMutex.Lock()
-	_ = h.g2.SetWriteDeadline(deadline)
-	_, err := h.g2.Write(data)
-	h.mouseMutex.Unlock()
+func (h *Hid) WriteKeyboardReport(data []byte) error {
+	if len(data) != 8 {
+		return fmt.Errorf("invalid keyboard report length: %d", len(data))
+	}
+	return h.writeHID(h.keyboardDevice(HID0), data)
+}
 
-	if err != nil {
-		switch {
-		case errors.Is(err, os.ErrClosed):
-			log.Errorf("hid already closed, reopen it...")
-			h.OpenNoLock()
-		case errors.Is(err, os.ErrDeadlineExceeded):
-			log.Debugf("write to %s timeout", HID2)
-		default:
-			log.Errorf("write to %s failed: %s", HID2, err)
+func (h *Hid) WriteRelativeMouseReport(data []byte) error {
+	if len(data) != 4 {
+		return fmt.Errorf("invalid relative mouse report length: %d", len(data))
+	}
+	return h.writeHID(h.relativeMouseDevice(HID1), data)
+}
+
+func (h *Hid) WriteAbsoluteMouseReport(data []byte) error {
+	if len(data) != 6 {
+		return fmt.Errorf("invalid absolute mouse report length: %d", len(data))
+	}
+	return h.writeHID(h.absoluteMouseDevice(HID2), data)
+}
+
+func (h *Hid) writeHIDReport(device hidDevice, data []byte) bool {
+	if err := h.writeHID(device, data); err != nil {
+		log.Errorf("write to %s failed: %s", device.path, err)
+		return false
+	}
+	return true
+}
+
+func (h *Hid) writeHID(device hidDevice, data []byte) error {
+	device.mu.Lock()
+	defer device.mu.Unlock()
+
+	if err := h.openDeviceNoLock(device); err != nil {
+		return err
+	}
+	if device.path == HID0 {
+		if err := h.openKeyboardLedReaderNoLock(); err != nil {
+			log.Debugf("open keyboard LED reader failed: %s", err)
+		} else {
+			h.startKeyboardLedReader()
 		}
-		return
 	}
 
-	log.Debugf("write to %s: %v", HID2, data)
+	file := device.get()
+	if file == nil {
+		return fmt.Errorf("%s: hid handle is nil", device.path)
+	}
+
+	deadline := time.Now().Add(hidWriteTimeout)
+	if err := file.SetWriteDeadline(deadline); err != nil {
+		log.Debugf("set write deadline for %s failed: %s", device.path, err)
+	}
+
+	if err := writeWithTimeout(file, data, hidWriteTimeout); err != nil {
+		if device.path == HID0 {
+			h.closeKeyboardLedReaderNoLock()
+		}
+		h.closeDeviceNoLock(device)
+		switch {
+		case errors.Is(err, os.ErrClosed):
+			return fmt.Errorf("hid already closed: %w", err)
+		case errors.Is(err, os.ErrDeadlineExceeded):
+			return fmt.Errorf("timeout after %s: %w", hidWriteTimeout, err)
+		default:
+			return err
+		}
+	}
+
+	log.Debugf("write to %s: %v", device.path, data)
+	return nil
 }

server/service/hid/hid_test.go

@@ -0,0 +1,28 @@
+package hid
+
+import (
+	"testing"
+	"time"
+)
+
+func TestReportLengthValidation(t *testing.T) {
+	h := &Hid{}
+	if err := h.WriteKeyboardReport(make([]byte, 7)); err == nil {
+		t.Fatal("expected keyboard length error")
+	}
+	if err := h.WriteRelativeMouseReport(make([]byte, 5)); err == nil {
+		t.Fatal("expected relative mouse length error")
+	}
+	if err := h.WriteAbsoluteMouseReport(make([]byte, 7)); err == nil {
+		t.Fatal("expected absolute mouse length error")
+	}
+}
+
+func TestPasteDurationLeavesModeSwitchMargin(t *testing.T) {
+	if maxPasteDuration >= 30*time.Second {
+		t.Fatalf("maxPasteDuration = %s, want below 30s mode switch wait budget", maxPasteDuration)
+	}
+	if got := time.Duration(maxPasteContentRunes) * defaultPasteDelay; got > maxPasteDuration {
+		t.Fatalf("max paste content duration = %s, want <= %s", got, maxPasteDuration)
+	}
+}

server/service/hid/keyboard.go

@@ -5,12 +5,108 @@ import (
 )
 
 func (h *Hid) Keyboard(queue <-chan []byte) {
+	legacy := make(chan QueuedReport)
+	go func() {
+		defer close(legacy)
+		for report := range queue {
+			legacy <- QueuedReport{Data: report}
+		}
+	}()
+	h.KeyboardReports(legacy)
+}
+
+func (h *Hid) KeyboardReports(queue <-chan QueuedReport) {
+	h.keyboardReports(queue, HID0)
+}
+
+func (h *Hid) keyboardReports(queue <-chan QueuedReport, path string) {
+	var execute func(func() error) error
+	var resetKeyboard func()
+	keyboardActive := false
+	defer func() {
+		if !keyboardActive {
+			return
+		}
+		if err := runCleanup(execute, func() error {
+			return h.writeHID(h.keyboardDevice(path), keyboardReleaseReport())
+		}); err != nil {
+			log.Errorf("release keyboard on queue close failed: %s", err)
+			return
+		}
+		if resetKeyboard != nil {
+			resetKeyboard()
+		}
+	}()
+
 	for event := range queue {
-		if len(event) != 8 {
-			log.Debugf("invalid keyboard event: %v", event)
+		execute = event.Execute
+		resetKeyboard = event.ResetKeyboard
+		if len(event.Data) != 8 {
+			event.complete(false)
+			log.Debugf("invalid keyboard event: %v", event.Data)
 			continue
 		}
 
-		h.WriteHid0(event)
+		if err := event.run(func() error {
+			return h.writeHID(h.keyboardDevice(path), event.Data)
+		}); err != nil {
+			log.Errorf("write to %s failed: %s", path, err)
+			if dropped := drainHIDQueue(queue); dropped > 0 {
+				log.Debugf("dropped %d stale keyboard HID reports after write failure", dropped)
+			}
+			cleanupErr := runCleanup(execute, func() error {
+				return h.writeHID(h.keyboardDevice(path), keyboardReleaseReport())
+			})
+			if cleanupErr != nil {
+				log.Errorf("release keyboard after write failure failed: %s", cleanupErr)
+				keyboardActive = keyboardActive || keyboardReportActive(event.Data)
+				event.complete(false)
+				continue
+			}
+			keyboardActive = false
+			if resetKeyboard != nil {
+				resetKeyboard()
+			}
+			event.complete(false)
+			continue
+		}
+
+		keyboardActive = keyboardReportActive(event.Data)
+		event.complete(true)
+	}
+}
+
+func keyboardReportActive(report []byte) bool {
+	if len(report) != 8 {
+		return false
+	}
+	if report[0] != 0 {
+		return true
+	}
+	for _, key := range report[2:] {
+		if key != 0 {
+			return true
+		}
+	}
+	return false
+}
+
+func keyboardReleaseReport() []byte {
+	return []byte{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}
+}
+
+func drainHIDQueue(queue <-chan QueuedReport) int {
+	dropped := 0
+	for {
+		select {
+		case report, ok := <-queue:
+			if !ok {
+				return dropped
+			}
+			report.complete(false)
+			dropped++
+		default:
+			return dropped
+		}
 	}
 }

server/service/hid/leader_key.go

@@ -0,0 +1,63 @@
+package hid
+
+import (
+	"os"
+	"strings"
+
+	"NanoKVM-Server/proto"
+	"github.com/gin-gonic/gin"
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	LeaderKeyFile = "/etc/kvm/leader-key"
+)
+
+func (s *Service) SetLeaderKey(c *gin.Context) {
+	var req proto.SetLeaderKeyReq
+	var rsp proto.Response
+
+	if err := proto.ParseFormRequest(c, &req); err != nil {
+		rsp.ErrRsp(c, -1, "invalid arguments")
+		return
+	}
+
+	if req.Key == "" {
+		err := os.Remove(LeaderKeyFile)
+		if err != nil && !os.IsNotExist(err) {
+			rsp.ErrRsp(c, -2, "reset failed")
+			return
+		}
+	} else {
+		err := os.WriteFile(LeaderKeyFile, []byte(req.Key), 0o644)
+		if err != nil {
+			rsp.ErrRsp(c, -3, "write failed")
+			return
+		}
+	}
+
+	rsp.OkRsp(c)
+	log.Debugf("set leader key: %s", req.Key)
+}
+
+func (s *Service) GetLeaderKey(c *gin.Context) {
+	var rsp proto.Response
+
+	data, err := os.ReadFile(LeaderKeyFile)
+	if err != nil {
+		if os.IsNotExist(err) {
+			rsp.OkRspWithData(c, &proto.GetLeaderKeyRsp{
+				Key: "",
+			})
+			return
+		}
+		rsp.ErrRsp(c, -1, "read leader key failed")
+		return
+	}
+
+	rsp.OkRspWithData(c, &proto.GetLeaderKeyRsp{
+		Key: strings.Replace(string(data), "\n", "", -1),
+	})
+
+	log.Debugf("get leader key successful")
+}

server/service/hid/leds.go

@@ -0,0 +1,279 @@
+package hid
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"sync"
+	"syscall"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+	"golang.org/x/sys/unix"
+)
+
+const (
+	KeyboardLedStatusEvent = "hid-led-status"
+)
+
+// KeyboardLedStatus is the lock-key LED state last reported by the remote host
+// through the keyboard HID output report.
+type KeyboardLedStatus struct {
+	NumLock    bool      `json:"numLock"`
+	CapsLock   bool      `json:"capsLock"`
+	ScrollLock bool      `json:"scrollLock"`
+	Known      bool      `json:"known"`
+	UpdatedAt  time.Time `json:"updatedAt"`
+}
+
+type keyboardLedStatusStore struct {
+	mutex       sync.RWMutex
+	status      KeyboardLedStatus
+	subscribers map[int]func(KeyboardLedStatus)
+	nextID      int
+	now         func() time.Time
+}
+
+var keyboardLeds = newKeyboardLedStatusStore(time.Now)
+
+func newKeyboardLedStatusStore(now func() time.Time) *keyboardLedStatusStore {
+	return &keyboardLedStatusStore{
+		subscribers: make(map[int]func(KeyboardLedStatus)),
+		now:         now,
+	}
+}
+
+// GetKeyboardLedStatus returns a snapshot. Known is false until the host has
+// sent at least one keyboard HID output report.
+func GetKeyboardLedStatus() KeyboardLedStatus {
+	return keyboardLeds.Get()
+}
+
+// SubscribeKeyboardLedStatus subscribes to state changes and returns a
+// function that removes the subscription.
+func SubscribeKeyboardLedStatus(subscriber func(KeyboardLedStatus)) func() {
+	return keyboardLeds.Subscribe(subscriber)
+}
+
+func (s *keyboardLedStatusStore) Get() KeyboardLedStatus {
+	s.mutex.RLock()
+	defer s.mutex.RUnlock()
+	return s.status
+}
+
+func (s *keyboardLedStatusStore) Subscribe(subscriber func(KeyboardLedStatus)) func() {
+	s.mutex.Lock()
+	id := s.nextID
+	s.nextID++
+	s.subscribers[id] = subscriber
+	s.mutex.Unlock()
+
+	return func() {
+		s.mutex.Lock()
+		delete(s.subscribers, id)
+		s.mutex.Unlock()
+	}
+}
+
+func (s *keyboardLedStatusStore) Update(report byte) {
+	next := keyboardLedStatusFromReport(report, s.now())
+
+	s.mutex.Lock()
+	previous := s.status
+	s.status = next
+	if sameKeyboardLedState(previous, next) {
+		s.mutex.Unlock()
+		return
+	}
+
+	subscribers := make([]func(KeyboardLedStatus), 0, len(s.subscribers))
+	for _, subscriber := range s.subscribers {
+		subscribers = append(subscribers, subscriber)
+	}
+	s.mutex.Unlock()
+
+	for _, subscriber := range subscribers {
+		subscriber(next)
+	}
+}
+
+func keyboardLedStatusFromReport(report byte, updatedAt time.Time) KeyboardLedStatus {
+	return KeyboardLedStatus{
+		NumLock:    report&0x01 != 0,
+		CapsLock:   report&0x02 != 0,
+		ScrollLock: report&0x04 != 0,
+		Known:      true,
+		UpdatedAt:  updatedAt,
+	}
+}
+
+func sameKeyboardLedState(a, b KeyboardLedStatus) bool {
+	return a.NumLock == b.NumLock &&
+		a.CapsLock == b.CapsLock &&
+		a.ScrollLock == b.ScrollLock &&
+		a.Known == b.Known
+}
+
+func (h *Hid) startKeyboardLedReader() {
+	h.ledReaderStartOnce.Do(func() {
+		go h.readKeyboardLeds()
+	})
+}
+
+func (h *Hid) readKeyboardLeds() {
+	buf := make([]byte, 64)
+
+	for {
+		file, notifierFD := h.keyboardLedReaderHandles()
+		if file == nil {
+			if err := waitForKeyboardLedReaderChange(notifierFD); err != nil {
+				log.Debugf("wait for keyboard LED reader failed: %s", err)
+			}
+			continue
+		}
+
+		changed, err := waitForKeyboardLedReportOrChange(file, notifierFD)
+		if err != nil {
+			if !errors.Is(err, os.ErrClosed) {
+				log.Debugf("wait for keyboard LED report failed: %s", err)
+			}
+			h.reopenKeyboardLedReader(file)
+			continue
+		}
+		if changed {
+			continue
+		}
+
+		n, err := file.Read(buf)
+		if n > 0 {
+			// Both keyboard gadget descriptors in kvmapp/system/init.d declare
+			// boot-keyboard reports without a Report ID (no 0x85 item). Their LED
+			// output report is one byte: bits 0-4 are the LED bitmap and bits 5-7
+			// are padding. report_length is 8 because it also covers input reports.
+			keyboardLeds.Update(buf[0])
+		}
+
+		if err == nil && n > 0 {
+			continue
+		}
+		if err != nil && !errors.Is(err, os.ErrClosed) {
+			log.Debugf("read keyboard LED report failed: %s", err)
+		}
+		h.reopenKeyboardLedReader(file)
+	}
+}
+
+func (h *Hid) keyboardLedReaderHandles() (*os.File, int) {
+	h.kbMutex.Lock()
+	defer h.kbMutex.Unlock()
+	if h.ledReaderNotifyReader == nil {
+		return h.g0Reader, -1
+	}
+	return h.g0Reader, h.ledReaderNotifyReadFD
+}
+
+func (h *Hid) reopenKeyboardLedReader(file *os.File) {
+	h.kbMutex.Lock()
+	defer h.kbMutex.Unlock()
+
+	// A reset may have installed a new reader while the old descriptor was
+	// reporting an error. Never let that stale reader close the replacement.
+	if h.g0Reader != file {
+		return
+	}
+	h.closeKeyboardLedReaderNoLock()
+	if h.g0 == nil {
+		return
+	}
+	if err := h.openKeyboardLedReaderNoLock(); err != nil {
+		log.Debugf("reopen keyboard LED reader failed: %s", err)
+	}
+}
+
+func (h *Hid) ensureKeyboardLedReaderNotifierNoLock() error {
+	if h.ledReaderNotifyReader != nil {
+		return nil
+	}
+
+	reader, writer, err := os.Pipe()
+	if err != nil {
+		return fmt.Errorf("create keyboard LED reader notifier: %w", err)
+	}
+	readerFD := int(reader.Fd())
+	writerFD := int(writer.Fd())
+	if err := unix.SetNonblock(readerFD, true); err != nil {
+		_ = reader.Close()
+		_ = writer.Close()
+		return fmt.Errorf("set keyboard LED reader notifier read end nonblocking: %w", err)
+	}
+	if err := unix.SetNonblock(writerFD, true); err != nil {
+		_ = reader.Close()
+		_ = writer.Close()
+		return fmt.Errorf("set keyboard LED reader notifier write end nonblocking: %w", err)
+	}
+	h.ledReaderNotifyReader = reader
+	h.ledReaderNotifyWriter = writer
+	h.ledReaderNotifyReadFD = readerFD
+	h.ledReaderNotifyWriteFD = writerFD
+	return nil
+}
+
+func (h *Hid) notifyKeyboardLedReaderNoLock() {
+	if h.ledReaderNotifyWriter == nil {
+		return
+	}
+	_, err := unix.Write(h.ledReaderNotifyWriteFD, []byte{1})
+	if err != nil && !errors.Is(err, syscall.EAGAIN) && !errors.Is(err, syscall.EWOULDBLOCK) {
+		log.Debugf("notify keyboard LED reader failed: %s", err)
+	}
+}
+
+func waitForKeyboardLedReaderChange(notifierFD int) error {
+	if notifierFD < 0 {
+		return fmt.Errorf("keyboard LED reader notifier is nil")
+	}
+	_, err := unix.Poll([]unix.PollFd{{Fd: int32(notifierFD), Events: unix.POLLIN}}, -1)
+	if err != nil {
+		return err
+	}
+	drainKeyboardLedReaderNotifier(notifierFD)
+	return nil
+}
+
+// waitForKeyboardLedReportOrChange blocks until a HID output report arrives or
+// the reader is replaced/closed. Its bool result is true for the latter.
+func waitForKeyboardLedReportOrChange(file *os.File, notifierFD int) (bool, error) {
+	if file == nil || notifierFD < 0 {
+		return false, fmt.Errorf("keyboard LED reader or notifier is nil")
+	}
+
+	fds := []unix.PollFd{
+		{Fd: int32(file.Fd()), Events: unix.POLLIN},
+		{Fd: int32(notifierFD), Events: unix.POLLIN},
+	}
+	_, err := unix.Poll(fds, -1)
+	if err != nil {
+		return false, err
+	}
+	if fds[1].Revents&unix.POLLIN != 0 {
+		drainKeyboardLedReaderNotifier(notifierFD)
+		return true, nil
+	}
+	if fds[0].Revents&(unix.POLLIN|unix.POLLERR|unix.POLLHUP|unix.POLLNVAL) != 0 {
+		return false, nil
+	}
+	return false, fmt.Errorf("keyboard LED poll returned without an event")
+}
+
+func drainKeyboardLedReaderNotifier(notifierFD int) {
+	buf := make([]byte, 64)
+	for {
+		_, err := unix.Read(notifierFD, buf)
+		if err != nil {
+			if !errors.Is(err, syscall.EAGAIN) && !errors.Is(err, syscall.EWOULDBLOCK) {
+				log.Debugf("drain keyboard LED reader notifier failed: %s", err)
+			}
+			return
+		}
+	}
+}

server/service/hid/leds_test.go

@@ -0,0 +1,168 @@
+package hid
+
+import (
+	"os"
+	"testing"
+	"time"
+)
+
+func TestKeyboardLedStatusFromReport(t *testing.T) {
+	updatedAt := time.Date(2026, time.July, 24, 12, 0, 0, 0, time.UTC)
+	status := keyboardLedStatusFromReport(0x17, updatedAt)
+
+	if !status.NumLock || !status.CapsLock || !status.ScrollLock || !status.Known {
+		t.Fatalf("unexpected parsed status: %+v", status)
+	}
+	if !status.UpdatedAt.Equal(updatedAt) {
+		t.Fatalf("updatedAt = %s, want %s", status.UpdatedAt, updatedAt)
+	}
+}
+
+func TestKeyboardLedStatusStoreOnlyNotifiesStateChanges(t *testing.T) {
+	now := time.Date(2026, time.July, 24, 12, 0, 0, 0, time.UTC)
+	store := newKeyboardLedStatusStore(func() time.Time { return now })
+	notifications := make(chan KeyboardLedStatus, 2)
+	store.Subscribe(func(status KeyboardLedStatus) {
+		notifications <- status
+	})
+
+	store.Update(0x01)
+	store.Update(0x01)
+	now = now.Add(time.Second)
+	store.Update(0x03)
+
+	first := <-notifications
+	second := <-notifications
+	if !first.NumLock || first.CapsLock || !second.NumLock || !second.CapsLock {
+		t.Fatalf("unexpected notifications: first=%+v second=%+v", first, second)
+	}
+
+	select {
+	case status := <-notifications:
+		t.Fatalf("unexpected duplicate notification: %+v", status)
+	default:
+	}
+
+	if status := store.Get(); !status.UpdatedAt.Equal(now) {
+		t.Fatalf("latest updatedAt = %s, want %s", status.UpdatedAt, now)
+	}
+}
+
+func TestWaitForKeyboardLedReaderChangeWaitsForNotification(t *testing.T) {
+	h := &Hid{}
+	h.kbMutex.Lock()
+	if err := h.ensureKeyboardLedReaderNotifierNoLock(); err != nil {
+		h.kbMutex.Unlock()
+		t.Fatal(err)
+	}
+	notifierFD := h.ledReaderNotifyReadFD
+	h.kbMutex.Unlock()
+	defer h.ledReaderNotifyReader.Close()
+	defer h.ledReaderNotifyWriter.Close()
+
+	done := make(chan error, 1)
+	go func() { done <- waitForKeyboardLedReaderChange(notifierFD) }()
+
+	select {
+	case err := <-done:
+		t.Fatalf("wait returned before a notification: %v", err)
+	case <-time.After(25 * time.Millisecond):
+	}
+
+	h.kbMutex.Lock()
+	h.notifyKeyboardLedReaderNoLock()
+	h.kbMutex.Unlock()
+
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("wait returned error: %v", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("wait did not wake after a notification")
+	}
+}
+
+func TestWaitForKeyboardLedReportOrChangeReturnsForReport(t *testing.T) {
+	reader, writer, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer reader.Close()
+	defer writer.Close()
+
+	h := &Hid{}
+	h.kbMutex.Lock()
+	if err := h.ensureKeyboardLedReaderNotifierNoLock(); err != nil {
+		h.kbMutex.Unlock()
+		t.Fatal(err)
+	}
+	notifierFD := h.ledReaderNotifyReadFD
+	h.kbMutex.Unlock()
+	defer h.ledReaderNotifyReader.Close()
+	defer h.ledReaderNotifyWriter.Close()
+
+	done := make(chan struct {
+		changed bool
+		err     error
+	}, 1)
+	go func() {
+		changed, err := waitForKeyboardLedReportOrChange(reader, notifierFD)
+		done <- struct {
+			changed bool
+			err     error
+		}{changed, err}
+	}()
+
+	if _, err := writer.Write([]byte{0x03}); err != nil {
+		t.Fatal(err)
+	}
+
+	select {
+	case result := <-done:
+		if result.err != nil || result.changed {
+			t.Fatalf("result = changed=%t, err=%v; want report", result.changed, result.err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("wait did not wake for report")
+	}
+}
+
+func TestReopenKeyboardLedReaderDoesNotCloseReplacement(t *testing.T) {
+	oldReader, oldWriter, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer oldReader.Close()
+	defer oldWriter.Close()
+	replacement, replacementWriter, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer replacement.Close()
+	defer replacementWriter.Close()
+
+	h := &Hid{g0Reader: oldReader}
+	h.kbMutex.Lock()
+	if err := h.ensureKeyboardLedReaderNotifierNoLock(); err != nil {
+		h.kbMutex.Unlock()
+		t.Fatal(err)
+	}
+	h.g0Reader = replacement // Simulate reset/reopen replacing the reader.
+	h.kbMutex.Unlock()
+	defer h.ledReaderNotifyReader.Close()
+	defer h.ledReaderNotifyWriter.Close()
+
+	h.reopenKeyboardLedReader(oldReader)
+	current, _ := h.keyboardLedReaderHandles()
+	if current != replacement {
+		t.Fatal("stale reader close replaced the active reader")
+	}
+	if _, err := replacementWriter.Write([]byte{0x01}); err != nil {
+		t.Fatalf("replacement reader was closed: %v", err)
+	}
+	buf := make([]byte, 1)
+	if _, err := replacement.Read(buf); err != nil {
+		t.Fatalf("replacement reader was closed: %v", err)
+	}
+}