Administrator/NanoKVM-MIRROR
1
0
Fork 1
mirror of https://github.com/sipeed/NanoKVM.git synced 2026-11-10 01:49:00 -06:00
Code Issues Packages Projects Releases Wiki Activity

Compare commits

base: Administrator:2.3.5
Branches Tags
Administrator:main
Administrator:2.5.4 Administrator:2.5.3 Administrator:2.5.2 Administrator:2.5.1 Administrator:2.5.0 Administrator:v1.4.3 Administrator:2.4.3 Administrator:2.4.2 Administrator:2.4.1 Administrator:2.4.0 Administrator:2.3.6 Administrator:2.3.5 Administrator:2.3.4 Administrator:v1.4.2 Administrator:2.3.3 Administrator:2.3.2 Administrator:2.3.1 Administrator:2.3.0 Administrator:2.2.9 Administrator:2.2.8 Administrator:2.2.7 Administrator:2.2.6 Administrator:2.2.5 Administrator:2.2.4 Administrator:2.2.3 Administrator:2.2.2 Administrator:2.2.1 Administrator:v1.4.0 Administrator:2.2.0 Administrator:2.1.6 Administrator:v1.3.0 Administrator:v1.2.1 Administrator:v1.2.0 Administrator:v1.1.0 Administrator:NanoKVM
...
compare: Administrator:2.5.4
Branches Tags
Administrator:main
Administrator:2.5.4 Administrator:2.5.3 Administrator:2.5.2 Administrator:2.5.1 Administrator:2.5.0 Administrator:v1.4.3 Administrator:2.4.3 Administrator:2.4.2 Administrator:2.4.1 Administrator:2.4.0 Administrator:2.3.6 Administrator:2.3.5 Administrator:2.3.4 Administrator:v1.4.2 Administrator:2.3.3 Administrator:2.3.2 Administrator:2.3.1 Administrator:2.3.0 Administrator:2.2.9 Administrator:2.2.8 Administrator:2.2.7 Administrator:2.2.6 Administrator:2.2.5 Administrator:2.2.4 Administrator:2.2.3 Administrator:2.2.2 Administrator:2.2.1 Administrator:v1.4.0 Administrator:2.2.0 Administrator:2.1.6 Administrator:v1.3.0 Administrator:v1.2.1 Administrator:v1.2.0 Administrator:v1.1.0 Administrator:NanoKVM

114 Commits
2.3.5 ... 2.5.4

Author SHA1 Message Date
Guoguo
d8553cf40b docs: add 2.5.4 changelog entries 2026-11-10 10:27:44 +08:00
梁子月
bb7194eb6c Merge pull request #982 from liangzhuohua/feat/storage-file-manager-ui 
feat(storage): adopt the NanoKVM Go file-manager UI
 2026-11-06 18:52:26 +08:00
916BGAI
44c420e28b fix: prevent black screen after application upgrades 
Serialize service operations and finish migration before starting services.
Install the startup script atomically, remove recursive restarts, and keep
the migration marker until required changes succeed.

Claim video ownership before clearing orphan VENC/VPSS resources, always
finish recovery SYS cleanup, and retain resource state on teardown failures.
Rebuild the bundled libkvm_mmf.so with these fixes.

Validated cross-builds, ABI and recovery failure paths, plus a 2.4.3 to 2.5.3
upgrade on hardware with 1080p browser WebRTC and MJPEG playback.
 2026-11-04 19:45:09 +08:00
916BGAI
4b54fc4768 refactor(video): use Sophgo SDK for H.264 and MJPEG 
Use per-codec capture locks and encoder backpressure, simplify frame ownership, and follow HDMI input dimensions. Refresh prebuilt video libraries while preserving server-only builds and deployment instructions.
 2026-11-04 14:57:49 +08:00
Guoguo
02242c1908 docs: add 2.5.2 and 2.5.3 changelog entries 2026-11-03 09:59:38 +08:00
watermeko
509a22f6bd feat: add multiuser permission system (#958) 
* feat(auth): add fine-grained feature permissions for multi-user access

Introduce a grantable permission catalog on top of the admin/user roles:
administrators keep implicit full access, while regular users receive an
explicit permission set covering console view/control, power, media
mount/manage, terminal, device, network, update, mcp, tailscale and ai
feature groups. Media access splits along the trust boundary: mounting
library media and reading it is media.mount, while changing library
contents (uploads, deletes, file exchange with the target) is media.manage.

Server:
- store permissions on the account record; nil keeps the pre-permission
  user behavior (console view/control and power) so upgrades are seamless
- add RequirePermission middleware and map every route to its group;
  user management stays admin-only
- require console.view in the grant set a regular user ends up with,
  including when a role change alone would leave an account without it,
  since nothing in the app renders without that grant
- let a user who may mount media read the library and follow an image
  download, while starting, cancelling or deleting stays media.manage
- scope console.control to input: keyboard, mouse, paste, and the input
  region that maps pointer motion onto the target screen. Video encoding,
  quality, resolution and capture recovery need only console.view, since
  every account holds it and a watcher still has to pick a quality its
  link can carry
- websocket console drops keyboard/mouse reports for view-only sessions
- permission changes keep the login valid: TokenVersion is only bumped
  for role/enabled changes, a grant that changes a long-lived
  connection's cached state drops that channel with a dedicated 4403
  close code so the client reconnects with fresh permissions, and the
  frontend is notified over the console websocket to refresh in place;
  a rejected request also triggers a silent account refresh
- document the catalog, the media split, the input-only scope of
  console.control and the grants that reach the whole device (terminal,
  device, update, mcp, ai) in server/README.md and README_ZH.md
- warn in the account editor that mcp hands out a device-wide API key
  which keeps working after the grant is revoked, the same way the ai
  grant is flagged for reaching the device outside the other grants

Web:
- account endpoint returns effective permissions; menus, settings tabs,
  storage page actions and editors render per permission instead of the
  isAdmin flag, and the terminal and storage routes are guarded by the
  matching grant
- a session without console.control stops capturing the pointer and the
  keyboard, hides the input-region editor and its stale-region cleanup,
  and marks the console as view only, mirroring the server that drops
  those reports; the client also gates a report already in flight
- user management gains a grouped permission editor with the console-view
  grant pinned, and warning hints on the mcp and ai grants; rows use
  aligned icon actions with tooltips
- every page refreshes the account when its grants change: the console
  socket handles the auth event itself, pages without a socket re-read on
  route change and when they become visible, and the ai sidebar closes
  once the grant is gone
- the terminal, the WebRTC viewer and the console all honor the 4403
  permission-change close instead of stranding the page or the login

Localization:
- ship every string this feature adds, including the permission editor,
  the view-only badge and the mcp/ai warnings, in all 24 supported
  locales

Verified with go vet, go test for authn/middleware/service auth, tsc
--noEmit, eslint, prettier, and a key-by-key comparison of every locale
against en.ts (694 keys, none missing).

* fix(auth): keep the emulated USB devices under the device grant

The virtual disk and the RNDIS adapter toggle the emulated USB gadget in
Settings > Device: the disk hands the target machine the raw data
partition, the adapter hands it a network interface. Neither is a media
or a network operation, so both follow `device` instead of media.mount
and network.

- route /vm/device/virtual through `device` only, so no handler has to
  narrow a union to the device a request touches
- render both switches wherever the device settings are visible, and
  read the medium state, stop a transfer, or pick the disk warning only
  with the matching media grant
- the storage page offers to enable the virtual disk only to accounts
  that may toggle it; the others are told which account has to do it,
  with the new string added in every locale
- document that attaching a medium needs the virtual disk, and that
  `device` can hand out the raw data partition and a network interface

Verified with go vet, go test for authn/middleware/service auth, tsc
--noEmit, eslint, prettier, and a key-by-key comparison of every locale
against en.ts (695 keys, none missing).

* fix(auth): repair the permission editor and the refresh path

The permission editor and the code around it shipped with several defects:

- the editor kept its field values after the modal was destroyed (antd forms
  preserve values by default), so opening it for a second account showed the
  previous account's grants and saving wrote them onto that account. The
  selection now lives in component state and is seeded when the editor opens,
  so a cancelled edit is dropped as well
- a save closed the dialog even when the server refused the change, and the
  reason was replaced by a generic message. updateUser reports success now and
  the server's own refusal (an omitted console.view, an invalid role, ...) is
  shown next to the failure
- a refused virtual-disk toggle in Settings > Device only reached the console.
  A device holder without media.manage cannot cancel the transfer that holds
  /data, so that refusal is expected and now says why the switch did not move
- losing the grant behind an open settings tab left an empty panel, and a
  vanished update tab could keep the modal locked and unclosable
- a role change bumped the token version and logged the account out mid
  session, while a permission change did not. Only disabling an account
  invalidates the login now: a role change resolves to its implicit grants and
  takes the same notify-and-reconnect path as a grant edit, so a promoted or
  demoted account keeps working and simply reconnects with new capabilities
- the console offered a mouse menu whose items only shape input, and mounted
  the on-screen keyboard, for accounts that cannot send input at all
- the account rows stopped wrapping on narrow screens and the icon-only
  actions had no accessible name
- the editor groups grants by what they reach, with media.mount next to
  media.manage instead of under the console grants, and gained a title, a
  Save/Cancel pair and a localized Media section

Server side, authn.Has replaces three copies of the same lookup, the
permission-aware channel map documents that console.view is pinned, and the
HDMI reset keeps its console.view grant with the reasoning written down.
The documentation follows: a permission change no longer claims to interrupt
the video stream, HDMI reset is listed with the view operations, and only
disabling an account invalidates a login.

* feat(auth): give the service grants their own permission group

mcp, tailscale and ai reach the device on their own — an API key outside the
web session, a VPN mesh, an agent driving the local loopback interface —
instead of through the settings the remaining grants cover, so they no longer
share the Administration section with terminal, device, network and update.

The editor renders them as a Services section between Media and
Administration, and the label ships in all 24 locales.

* refactor(auth): model grants as a catalog with implied grants

Replace the media-aware flat grant list with a catalog the server serves to the
account editor: each grant carries a group, a risk level and the grants it
implies, so labels, sections and risk marks cannot drift from what the server
enforces.

Server:
- resolve implied grants before answering a request, which removes the
  route-level unions: console.control implies console.view, and both
  medium.attach and library.write imply library.read
- split media access three ways along the trust boundary: medium.attach mounts,
  ejects and writes into the shared partition the target machine reads,
  library.write changes what the library keeps, and library.read lists and
  downloads. The file endpoints serve an image and the partition through one
  path, so they admit either grant and check the medium type in the request
- stop pinning console.view: with control implying view, an account may hold no
  console access at all, and the web app lands on a page that offers the
  sections its grants open
- materialize the grant set when the account file is read, so a record written
  before fine-grained permissions keeps exactly what the user role granted, and
  nil no longer means different behavior later; the split media grants are
  translated on load
- keep grants this build does not know instead of refusing the file, so a
  downgrade cannot lock the device out
- serve the stored set to the account list and the effective closure to the
  account endpoint

Web:
- render the editor from the catalog: grouped sections, a per-grant tooltip with
  a risk marker, implied grants shown as included, and the grants that amount to
  full device control summarized in one line
- show an administrator's stored set read-only with what a demotion restores,
  and refuse to edit while the catalog cannot be loaded
- guard the terminal, storage and console routes and the in-page actions that
  were gated by the isAdmin flag by the matching grant instead
- add a landing page for an account without console access, and let the account
  list say how many grants each account holds
- ship the new strings in all 24 locales

Docs: describe the catalog, the media split, the implied grants and the
unpinned console in server/README.md and server/README_ZH.md.

* fix(web): align the settings icons with the rest of the menu

The settings icon carried a 3px top padding to compensate for the baseline gap
an inline svg leaves inside an antd Badge, which pushed it below the other menu
icons. A flex wrapper removes the gap instead, so the icon centers the way every
MenuItem does.

- center the settings modal tab icons in their 16px box instead of leaving them
  on the box baseline
- draw the account and the Tailscale tabs at 16px: both used an 18px icon inside
  a 16px box, and the Tailscale icon now takes a size prop instead of a class

* fix(web): draw CJK punctuation with a CJK face

antd components (tooltips, dialogs) and the Tailwind-styled page text used
different font stacks, so the ideographic comma and full stop could resolve to
different faces: a Latin font in antd's stack draws them above the baseline,
which made Chinese and Japanese tooltips look misaligned.

- pin U+3001 and U+3002 to a real CJK face through a @font-face with
  unicode-range, falling back to the rest of the stack when none of the local
  fonts is installed
- give the app one stack, shared by html/body and antd's font-family token

* feat(web): list administrators above regular users

An account that can change everyone else belongs at the top of the list, and the
row reads differently at a glance: administrators get a lighter card than the
regular accounts they administer.

The sort is stable, so accounts keep the order the account file lists them in
within each group.

* fix(auth): keep a granted capability reachable from the page that configures it

Two defects in the same catalog. The grants whose controls live in the
console menu could be handed out without console.view, and nothing outside
the console renders them, so an account could hold a capability no page
offered. And the catalog carried a third risk level the editor never used.

- imply console.view from power, device, network, update, mcp, tailscale
  and ai, the way console.control already did, so every grant has a page
  that can use it; terminal and the media grants keep their own pages
- collapse risk to two levels: warn now marks the three grants that amount
  to full device control (terminal, mcp, ai), while device, update and the
  grants that change settings everyone shares are plain info
- default a user-role account created without naming a grant set to what
  the user role granted before grants existed, so a script that only knows
  about roles keeps working; an explicit empty set still means empty
- document the implied console, the two levels and the create default

* fix(web): repair the account permission editor and its confirmations

The editor treated an explicitly stored grant that another selection
already implies as editable, so console.view looked free to uncheck on an
account where device settings brought it back; it also attributed the
grant to that other selection, which describes a default permission
backwards. Saving closed the dialog, and an administrator's reference set
was described by a banner above thirteen boxes it contradicted.

- lock any grant a selected grant already brings in, and only add the
  "included by" note to a grant the account does not store itself
- keep the dialog open after a save and let the footer button say Saved
  for a moment; editing again drops the confirmation
- drop the administrator banner and render the whole catalog as its
  read-only set, so a freshly created administrator no longer trips the
  empty-set warning
- render the catalog's two risk levels: warn draws the shield and the
  full-control summary, info stays a plain help mark
- ship the new Saved label, rename the summary key and retire the demote
  hint in all 24 locales, and mirror the catalog in the mocked handlers

* fix(web): honor the grants for the storage mount mode and the mouse menu

The full storage page still offered the mount-mode selector to an account
that cannot attach, where the console menu already hid it, and the mouse
menu vanished for a view-only account even though its cursor style is
local to the screen and needs no grant.

- hide the mount-mode selector on the storage page unless medium.attach,
  the way the console menu does
- keep the mouse menu for a view-only account with the cursor style as its
  only entry, instead of returning nothing

* refactor(web): use antd for the chat composer and drop the scroll-area primitive

The chat input was the last visible raw form control, and the settings
dialog and shortcut lists scrolled through a Radix primitive whose styling
does not match the scrollbars the rest of the app draws.

- send the chat message through antd's Input.TextArea; the composer's
  shape is carried by important utilities rather than a second styling
  system, and Enter-to-send plus the IME handling stay as they were
- replace the Radix scroll area with the native scroll container the other
  pages use, so the settings dialog and the shortcut lists scroll alike
- remove the component that wrapped it and the @radix-ui/react-scroll-area
  dependency

* fix(auth): close the gaps between grants and what they reach

- require library.write for a partition upload of an .iso/.img and for
  deleting a partition file or folder that holds one: every image on /data
  is a library entry, so medium.attach alone could add or remove them
- mark update as warn: an offline package is checked only against the
  checksum its uploader supplies, so the grant amounts to root
- regenerate the device-wide MCP API key when an account loses the mcp
  grant (revoked, demoted, disabled or deleted), so a copied key stops
  working with the grant
- re-read the account after a session registers, so a grant edit landing
  between authentication and registration can no longer leave a
  long-lived connection on the old grants
- return the account before and after from Store.Update under one lock,
  so concurrent edits diff against the state they actually changed
- keep stored grants this build does not know when a request replaces
  the set, instead of refusing or dropping them
- push the auth refresh event off the admin request path
- cover the catalog closure, legacy translation, unknown-grant carry-over,
  warn levels and the library guard with tests

* fix(web): follow the grant fixes in the account and tailscale pages

- show the memory and swap settings in the Tailscale menu only with
  device, which their endpoints require
- let only the latest account refresh set the state, and coalesce the
  focus and visibilitychange events that fire together on tab return
- keep the storage page console socket across auth pushes by depending
  on the grant instead of the hasPermission identity
- send only catalog grants from the permission editor; the server keeps
  stored ones it does not know
- describe the MCP key rotation in all 24 locales, add the singular
  grant count, and mirror the update risk level in the mocks

* fix(auth): check the on-disk name and report a failed key rotation

- check a partition upload against the file it actually replaces: exFAT
  folds case with its own table, so a name that is not an image in the
  request can still overwrite one on disk
- report a failed MCP key rotation to the administrator instead of
  answering OK while the old key keeps working
- re-read the account after registration only for the long-lived
  channels a grant edit can drop, so short requests do not read the
  account file twice

* feat(auth): let the administrator choose whether to rotate the MCP key

Regenerating the device-wide MCP API key disconnects every MCP client, so
rotating it on every revocation took a decision away from the person who
has to live with it. A change that takes the mcp grant away now warns
first and leaves the rotation to the administrator.

- server: rotate only when the request asks for it (rotateMcpKey in the
  update body, a query parameter on delete) and report mcpKeyRotated in
  the response; a kept key is logged as a warning
- web: before saving a grant set, changing the role, disabling or deleting
  an account that would lose the key, show a warning with a "Regenerate
  the MCP API key" checkbox, checked by default; unchecking it explains
  that a copied key stays valid, and a rotation is confirmed afterwards
- describe the choice in the mcp grant help and the server READMEs, and
  ship the new strings in all 24 locales

---------

Co-authored-by: Guoguo <i@qwq.trade>
 2026-10-21 15:19:45 +08:00
watermeko
5572e1de35 feat(storage): browse a medium and exchange files with the target machine (#957) 
* feat(storage): browse a medium and exchange files with the target machine

The image menu and the download page are replaced by one storage page: it
lists the media the emulated USB disk can carry, mounts and ejects them, and
browses the files inside a medium over that same gadget, so the two machines
exchange files without going through the terminal.

Mediated media:

* Add the media API (list, state, mount, eject, delete, download, files) and a
  file browser on top of it, and keep the pre-2.6 image endpoints working as a
  compatibility layer over the same code.
* Add diskfs: an image is mounted through a loop device so the kernel's exFAT
  and FAT drivers read it, and the data partition is browsed in place, because
  the emulated disk already hands that very directory to the target machine.
* Keep the one-writer policy the read-only mounts introduced: an image is
  served read-only in every mode, and the whole data partition is remounted
  read-only here while the target machine is its writer, through the same
  SetDataWritable the virtual disk switch uses. The file manager refuses those
  writes itself as well, so a request does not depend on a mount state.
* Name the mounted medium and the USB device after the image file, cut to the
  SCSI inquiry product field and the USB product string, and restore the
  defaults when the medium is released.
* Close the HID devices around a gadget re-enumeration and reopen them after,
  since mounting and a forced eject drop them.
* Report transfers through one job slot with progress, queueing behind a
  running transfer, and a free space preflight before an upload starts. Image
  uploads keep the volume descriptor and partition table check, so an unusable
  image is rejected while it streams.

The shared folder view:

* Refresh it on a timer while the target machine owns the partition. The
  target's block level writes land in this device's page cache, which the
  mounted exFAT shares, so the file data here is already current - but the
  dentry and inode caches are not, and a file the target grew keeps the size
  it was first read with. Dropping those caches and pushing a storage event
  makes the web UI follow the target machine within a second of its own
  writeback. The partition's write counter cannot drive this: it only moves
  once this side writes its dirty pages back, which is tens of seconds later
  or never.
* Send the refresh notifications from their own goroutine, so a client that
  stopped reading cannot hold up the refresh loop.

The web UI:

* Add the storage page: the medium list with mount and eject, the file browser
  with search and sorting, uploads, downloads and deletes, and transfer
  progress.
* Gate writing on the target machine owning the disk - image uploads and file
  uploads alike - instead of letting the server answer with an error the page
  has to surface, and drop the medium rows' download and delete buttons there
  too.
* Give the shared folder, .iso and .img their own glyphs, and pick the file
  icon from the extension, so a listing can be read at a glance.
* Name the partition the way the storage page does in the desktop menu as
  well, instead of showing the API's untranslated string.
* Read the mounted medium in Settings - Device from the media state, now that
  the storage API it used is gone.
* Tell an ISO 9660 image apart from a filesystem that cannot be read at all:
  the kernel of this device carries no iso9660 support (CONFIG_ISO9660_FS), so
  the contents of an ISO cannot be listed while the image itself is served to
  the target machine like any other medium.

Localization:

* Translate the new strings for every locale, keep the Settings - Device
  strings the read-only mounts added, and drop the keys the retired image menu
  and download page left behind.

Chores:

* Remove the desktop image menu, the download page and the API they used.

* fix(storage): harden media file transfers

Serialize medium deletion with gadget attachment and restore /data write access after failed mount transitions.

Use available filesystem space for upload limits, refine virtual-device and shared-file handling, and update media path and installation test coverage.

Pin an image while it is streamed out, so a writable mount cannot start between the check and the last byte; sweep stale upload temporaries from the whole data partition at startup, which the file manager itself cannot delete; and preflight URL downloads against the response size, which only the upload path did.

Show dot files in the file browser again: only the two transfer temporary prefixes stay hidden, which is what the dot filter was for.

Delete folders recursively after the web UI confirms, refusing when an attached or mounted medium lives inside the directory; accept every .iso and .img upload by name instead of sniffing volume descriptors; and show image and file transfers in one progress display at the top of the storage page.

* fix(storage): make cache drops work and close delete and gadget races

- drop_caches only accepts 1..4 on 5.10: write 4 once to silence the log,
  then 2/3. Writing 6/7 failed with EINVAL, so the shared folder never
  saw what the target machine wrote.
- Resolve a delete path to its on-disk spelling (exFAT is case-insensitive)
  before checking it against the attached and loop-mounted media, refuse
  deleting a loop-mounted image or a folder holding an upload target, and
  fail closed when the disk state cannot be read.
- GetMediaState no longer fails when the virtual disk is off and lun.0 does
  not exist; browsing works with the virtual disk off.
- An explicit enable for the virtual disk compares against the disk being
  configured, so it leaves a served image alone; the settings toggle keeps
  the #937 semantics.
- Restore /data write access after a failed gadget script or network switch.
- eject clears the LUN file before resetting ro/cdrom, so a refused eject
  does not change the type of the medium still being served.
- Mount loop images with MS_NOSYMFOLLOW and open files with O_NOFOLLOW.
- Accept UDF images as optical media.
- Only refuse deleting transfer temporaries while a transfer runs; sweep
  stale ones in the background, by exact name, and not on a read-only /data;
  hide them from listings.
- Cap URL downloads without Content-Length at the free space and verify the
  received length.
- Encode Content-Disposition filename* strictly per RFC 5987.
- Restore image_test.go and add tests for the above.

* fix(web): keep the file browser and transfers consistent on the storage page

- Tag a listing with the medium and path it belongs to, so entries of the
  previous directory are never shown or acted on under a new path.
- Poll the desktop storage menu only while it is open.
- Show a dedicated message for a checksum mismatch.
- Bring back the USB / SCP / TF card hints behind a help button.
- Pick up a transfer already running when the page opens; make uploads
  cancellable; track concurrent uploads separately; let a failed job be
  dismissed; show a success state and guard the progress display by task.
- Handle request errors that were left unhandled.
- Dedicated confirmation for deleting a folder recursively.
- Treat UDF images as optical, send credentials on the image download
  pre-check, translate the remaining Hungarian string.

---------

Co-authored-by: Guoguo <i@qwq.trade>
 2026-10-19 09:44:30 +08:00
watermeko
d0ff328db8 fix(web): import react-simple-keyboard by its named export 
`react-simple-keyboard` ships only a UMD/CJS bundle whose `module.exports`
is `{ KeyboardReact, default: KeyboardReact }` with `__esModule: true`.

Vite 8 applies Node-compatible CJS interop for ESM importers, so the
default import resolved to the whole `module.exports` object instead of
the component. Rendering it made React throw "Minified React error #130"
(`got: object`) as soon as the on-screen keyboard was opened.

Import the `KeyboardReact` named export, which is the same component,
and keep `KeyboardButtonTheme` as a type-only import.

Fixes #936
 2026-09-29 10:15:53 +08:00
watermeko
ff45b46c49 feat(storage): mount images read-only and hand /data to one writer (#937) 
Only one side may write the mounted image or the /data partition at a time,
and uploaded images are validated before they are stored.

Image mounts:

* Serve every mounted image read-only, in CD-ROM and mass storage mode alike:
  detach the LUN first and set the read-only flag before the image is
  attached, so the target machine can neither write to nor format it. The
  flags were previously only written for CD-ROM mounts, so a mass storage
  mount inherited ro=0 and the image stayed writable from the host.
* Report the virtual disk as on only while the LUN really carries the /data
  partition. With an image mounted the switch used to stay active but
  unchangeable, and enabling the disk is now a confirmed action instead of a
  rejected one: it cancels the mounted image, and the confirm also warns that
  the image download is interrupted because /data becomes read-only here.
* Ask before mounting: the image list warns that the virtual disk is released
  for the image, or offers to enable it first when it is off, instead of
  dropping the /data share silently. The new strings are translated for every
  locale.
* Name the mounted medium and the USB device after the image file, cut to the
  16 bytes of the SCSI inquiry product field and the 126 bytes of the USB
  product string, and restore the previous names on unmount.
* Reset the LUN flags on every gadget restart. They survived a restart, so
  the shared partition came back to the host read-only, or as an optical
  drive, after an image had been mounted.

The /data handover:

* Mount /data read-only at boot whenever the virtual disk serves the raw
  partition as a writable disk, so the handover holds from the first boot on.
* Add SetDataWritable(), which remounts /data and verifies the new state.
  Enabling the virtual disk makes /data read-only before the host can write
  it, and refuses to expose the disk when the remount fails instead of taking
  the risk. Unmounting an image, which hands the raw partition back to the
  host, does the same, while mounting an image switches /data back to
  writable because a served image is read-only for the host.
* Cancel a running image transfer before the handover and wait for it to
  stop, and report the state in the image list, where mounting still works
  while deleting and uploading do not. The delete action is disabled with a
  hint, and the downloader offers to turn the virtual disk off.

Image uploads:

* Validate the volume descriptors while streaming, so an unusable image is
  rejected in seconds instead of after the whole transfer: accept ISO 9660 and
  UDF volume descriptors (CD001, BEA01) as well as raw disk images (GPT, APFS,
  HFS+, MBR), and reject anything else. Require the image to fit in /data with
  a 128 MiB reserve before any of it is received, log the underlying errors on
  the rejection paths, and keep the temporary file, the progress ticker and the
  close handling in defers.

Add unit tests for the upload header check, the free space preflight and the
image name truncation.
 2026-09-24 09:17:24 +08:00
Guoguo
bd070b2f5c docs: add 2.5.1 changelog entries (#929) 2026-09-09 16:38:14 +08:00
watermeko
5c0bef019f fix(terminal): start a root login shell 
Launch Web terminal sessions in /root as login shells so they load the root profile and display the configured prompt.
 2026-09-04 17:25:51 +08:00
watermeko
283c1390e5 feat(shell): add informative SSH prompt 
Create a default root profile when one does not already exist. Show the user, hostname, and working directory while preserving custom profiles.
 2026-09-04 17:25:51 +08:00
watermeko
7f95fe9bbd fix(stream): isolate H264 subscribers 
Keep slow WebRTC consumers from blocking the shared H264 source by dropping buffered frames until the next keyframe. Restore the WebRTC NACK and RTCP report interceptors while retaining a safe RTP MTU, and enable linker --as-needed for libkvm to remove unused OpenCV dependencies.
 2026-09-01 15:34:20 +08:00
watermeko
a9e1ef2459 perf(stream): share H264 capture frames 
Route Direct and WebRTC consumers through one H264 capture source to avoid duplicate VENC reads. Overlap WebRTC capture with ordered RTP/SRTP writes and packetize each access unit once for all WebRTC clients.

Add libopencv_video.so.409 into dl_lib.
 2026-09-01 15:34:20 +08:00
watermeko
2ba45a2147 feat(web): enhance configurable input regions 
Make input-region calibration work across MJPEG and H.264 video modes, including robust four-sided black-border detection and initial-selection edge snapping. Persist multiple reusable manual regions, keep manual and original-resolution choices mutually exclusive, migrate legacy settings, and localize the new controls for every supported language.
 2026-08-25 09:36:13 +08:00
watermeko
9e6d280826 feat(web): add configurable mouse input regions 
Add device-level input-region APIs for reading, validating, and atomically persisting absolute mouse calibration settings, including automatic, manual, and disabled modes.

Introduce a shared screen viewport that keeps the rendered media geometry and configured input region aligned across MJPEG, direct H.264, and WebRTC streams. Add automatic black-border detection and a manual selection overlay with dragging, resizing, magnified preview, keyboard locking, and cancellation support.

Provide original-resolution presets so manual calibration can be recalculated for common aspect ratios, expose the controls from the desktop mouse menu, close menus before entering selection mode, and preserve active file transfers when the download menu closes.

Add localized control-region labels and messages for all supported locales, and update direct-frame rendering so media dimensions are reported after the canvas has been drawn.
 2026-08-25 09:36:13 +08:00
watermeko
527caeff6a fix(web): correct mouse coordinates for direct h264 frames 2026-08-25 09:36:13 +08:00
肆月
71ab9127dd feat: add secure multi-user support (#876) 2026-08-20 14:29:56 +08:00
肆月
d382f0621d fix: report and retry WebRTC connection failures (#866) 2026-08-13 14:56:01 +08:00
watermeko
9415afb359 fix(mouse): improve touch interaction and screen fitting (#857) 
- Add touch gestures for relative mouse mode, including tap, drag, long press, double-tap drag, and two-finger scrolling.

- Improve absolute mouse touch handling and prevent black letterbox areas from generating remote mouse events.

- Fit H.264 and MJPEG screens with contain scaling and disable browser touch handling on the screen elements.

- Move golang.org/x/sys to the direct dependency list.
 2026-08-11 09:47:04 +08:00
肆月
e5f6dfabaa fix(ota): isolate updates in persistent workspaces (#863) 
* fix(ota): isolate updates in persistent workspaces

Stage online and offline update archives under /root/.kvmcache/nanokvm-update-* and validate storage, manifests, and archive contents before changing the installed application.

* fix(ota): harden storage safety and release gates

Preserve the last rollback backup when update storage is insufficient, and verify the actual application mount point before installation.

Move the shared transfer sentinel from /tmp to /run, enforce device package limits in release verification, and run that verification in package CI.
 2026-08-10 14:49:29 +08:00
watermeko
757e0f61c5 feature: provide HDMI status in /api/vm/hdmi (#859) 
* feature: provide HDMI status in  /api/vm/hdmi

* fix: return false when HDMI idle in  /api/vm/hdmi
 2026-08-07 09:43:22 +08:00
肆月
761b02ed7e feat(web): upgrade build tooling to Vite 8 (#853) 
Upgrade Vite to 8.2.0 and @vitejs/plugin-react to 6.0.5.

Use Vite's native tsconfig path resolver and remove vite-tsconfig-paths.

Verified with pnpm build and pnpm lint (existing warnings only).
 2026-08-06 14:25:55 +08:00
Guoguo
562ea8277c feat: add dev container for full-stack development (#861) 
Layer the frontend toolchain on top of the existing release builder
image so a single container covers Go, C support-layer and web
development, with the builder image remaining the single source of
truth for the cross toolchain, Go and MaixCDK.

- Mount the workspace at /home/build/NanoKVM, where the Makefile and
  support/sg2002/build expect it, and resync MaixCDK components via
  update_lib on create so C builds never use stale sources
- Install Node from official dist tarballs (integrity-checked, pinned
  to the major used by CI), with NODE_DIST_MIRROR / NPM_REGISTRY /
  BASE_IMAGE build args for restrictive or mirrored corporate networks
- Export the MaixCDK virtualenv via remoteEnv so non-interactive
  processes (tasks, extensions, exec) get it too; make
  updateRemoteUserUID explicit since the published builder image bakes
  the CI runner's uid
- Run pnpm non-interactively during post-create (no TTY) and give the
  skeleton-less home a standard ~/.profile -> ~/.bashrc chain
- Make the web toolchain convention explicit via package.json engines
  (Node >= 22, pnpm >= 11, matching CI) and document it in web/README
- Document the dev container in the README, point server/README at the
  container flow that works on any host OS, and ignore .pnpm-store/
 2026-08-06 11:00:40 +08:00
Guoguo
7abec3cbad docs: add 2.5.0 changelog entries (#860) 2026-08-06 10:18:29 +08:00
Guoguo
8fc31553f7 ci: prefix GitHub Release titles with nanokvm (#856) 2026-08-05 11:52:22 +08:00
watermeko
9e50040713 fix(ota): keep update lock through service restart 2026-08-05 11:50:39 +08:00
watermeko
0f8ef20fb5 feat(ota): verify offline update checksums 2026-08-05 11:50:39 +08:00
watermeko
7cda3b2920 feat(ota): add custom update server support 
+ Add persistent custom update server configuration, authenticated URL support, manifest validation, and the settings UI.

+ Keep application updates rebootless by coordinating video shutdown, migration-time service startup, and online/offline service restarts.

+ Localize the custom update server workflow across all supported languages.
 2026-08-05 11:50:39 +08:00
Guoguo
40bbeab8ae ci: split package, tag, and release workflows (#855) 2026-08-04 16:33:56 +08:00
肆月
eb20fb41aa feat: show remote keyboard lock status (#838) 
* feat: show remote keyboard lock status

* fix(keyboard-led-status): eliminate polling and improve delivery

* fix(keyboard-led-status): simplify indicator labels
 2026-08-04 09:28:14 +08:00
watermeko
21e834b4c8 perf: reduce latency in 60 Hz mode (#844) 
- Add decode-driven flow control and bounded GOP-aware queues to prevent stale H.264 frames from accumulating in TCP and WebSocket buffers.
- Isolate slow clients with dedicated writer goroutines, write deadlines, and safer connection lifecycle handling.
- Move the Direct H.264 socket into the worker, simplify the low-latency decode path, and improve reconnect behavior.
 2026-07-31 19:08:07 +08:00
916BGAI
8773605715 Merge pull request #845 from imguoguo/ci/release-package 
ci: release package
 2026-07-31 19:00:18 +08:00
Guoguo
b23eb33611 ci: build identifiable NanoKVM release packages 2026-07-31 03:47:54 -07:00
Guoguo
ef432da2fe build: allow overriding the builder image and install patchelf 
Groundwork for building outside an interactive terminal.

- IMAGE_NAME becomes overridable so a prebuilt image can be used instead
  of building one locally
- docker run no longer hardcodes -it on the app and support recipes:
  allocating a TTY fails where there is none. shell stays interactive
- install patchelf, which server/build.sh needs to set the RPATH on the
  server binary
 2026-07-30 19:55:30 -07:00
Guoguo
96c86f6098 fix(build): correct exit codes in support/sg2002/build 
The script has no error handling of its own, so these all pass silently.

- update_lib exited 1 after succeeding, so callers could not chain it
- a failed maixcdk build printed "Build Error!" and exited 0, letting a
  caller carry on with no artifacts
- add_to_kvmapp did the same when the source did not exist
- the copies in update_lib were unchecked; since update_lib is what keeps
  the SDK components in sync with the source tree, a silent failure there
  yields libraries built from stale sources
 2026-07-30 19:52:34 -07:00
watermeko
a7d7574e70 fix: warn about mixed H264 stream modes (#843) 2026-07-31 10:48:52 +08:00
watermeko
b587b9f912 fix: stop HDMI capture when logged out (#841) 
* fix: stop HDMI capture when logged out

* feat: stop HDMI capture when viewers are idle

* fix: keep HDMI capture active for consumers
 2026-07-30 17:29:07 +08:00
watermeko
004fd59093 fix(sg2002): harden VI state sharing 2026-07-30 16:08:48 +08:00
watermeko
774d314ce9 fix(sg2002): share VI debug state between processes 2026-07-30 16:08:48 +08:00
watermeko
e4d23014ba fix(sg2002): read VI debug state without shell pipelines 2026-07-30 16:08:48 +08:00
BeaconCat
dc050d1f19 fix(usb): assign deterministic gadget MAC so the host NIC stays stable (#828) 
The USB network gadget (rndis.usb0 / ncm.usb0) is created without dev_addr or
host_addr, so the kernel picks a random MAC for both the device side and the
host side on every bind. S10uuid later pins the device-side usb0 via
'ip link set', but the host_addr -- the MAC the attached PC's RNDIS/NCM adapter
uses -- stays random and changes on every re-enumeration/reboot. The host then
registers a brand-new network adapter each time, piling up stale adapters/MACs
(e.g. ~10 after a few reboots) and breaking anything that keys off the MAC.

Derive both MACs from the chip UID (same scheme S10uuid already uses for eth0
and usb0), before binding the gadget:
  dev_addr  = 48:da:35:6e:<uid>
  host_addr = 48:da:35:6d:<uid>

Verified on a NanoKVM Cube: host_addr went from random a6:3f:5d:8a:7d:52 to a
stable 48:da:35:6d:26:62, identical across two reboots.

Fixes #740

Co-authored-by: BeaconCat <BeaconCat@users.noreply.github.com>
 2026-07-29 16:29:53 +08:00
SiYue-ZO
57e1f6a4d6 fix(picoclaw): cancel runtime lifecycle on mode switch 
Cancel PicoClaw start/readiness waits when MCP takes control, clear held manual input state after failed release reports, and keep paste duration below the control-mode wait budget.

Also add MCP copy failure translations and avoid reconnect effect churn when the locale changes.
 2026-07-29 15:16:06 +08:00
SiYue-ZO
d578c63036 i18n(picoclaw): add MCP control translations 
Add locale coverage for MCP settings, AI-control ownership, PicoClaw runtime operations, and related conflict states.
 2026-07-29 15:16:06 +08:00
SiYue-ZO
6b98f5415f feat(web): add MCP settings and control handoff UI 
Add the MCP settings view and frontend API bindings for configuring remote-control access.

Expose AI-control ownership state in PicoClaw, lock conflicting keyboard input paths, and preserve chat state when control is released.
 2026-07-29 15:16:06 +08:00
SiYue-ZO
64ce12cc0d feat(mcp): add authenticated remote control backend 
Add an MCP Streamable HTTP server with token authentication, screenshot capture, keyboard, and mouse tools.

Introduce shared control-mode and input-control coordination so MCP, PicoClaw, and local HID paths serialize ownership safely.

Integrate PicoClaw gateway/runtime control handoff with PID-managed startup and focused unit coverage.
 2026-07-29 15:16:06 +08:00
watermeko
183f8dc983 fix: reuse existing container users and groups 2026-07-27 10:28:46 +08:00
watermeko
7eee77a33d fix: fix container slow caused by uid/gid 2026-07-27 10:28:46 +08:00
watermeko
c1986acf65 fix(web): keep direct H264 playback low latency 2026-07-24 15:41:02 +08:00
watermeko
c999a883bd perf(sg2002): integrate zero-copy H.264 capture 
Move frame ownership and zero-copy VENC handling into the tracked MMF
and Vision sources instead of relying on a preload hook. Keep the sensor
name mapping aligned with middleware enums and release deferred VI frames
safely across encoder lifecycle changes.
 2026-07-24 15:41:02 +08:00
肆月
70f8503cbb fix: prevent OLED sleep duration truncation (#834) 
OLED sleep settings are stored as seconds, but the kvm_system reader parsed the value into a uint8_t before assigning it to the uint16_t state field. Values above 255 seconds wrapped, so 5 min, 10 min, 30 min, and 1 hour did not behave as selected.

Parse the setting into a uint16_t-sized temporary value and terminate the read buffer before atoi so all configured durations up to 3600 seconds are preserved.

Closes #826
 2026-07-22 17:46:39 +08:00
Guoguo
5b0a7d2a91 feat: add sha256sum check (#832) 
* feat(download): add sha256sum check and cancellable downloads

+ server/proto/download.go
	+ add DownloadImageReq and sha256 argument

server/router/download.go
	+ add cancel download router

server/service/download/service.go
	+ sha256 decode and check
	+ remove HEAD request
	+ cancel download

* refactor(download): synchronize image and application transfers

sovel the the problem that image downloading and app downloading would conflict
at same time

* fix: optimized UI of image download and locale issue

* fix: locale
 2026-07-17 18:17:04 +08:00
watermeko
4fee758ff0 fix: fix api/storage/image/mounted error when using HID-Only mode (#833) 2026-07-17 18:02:07 +08:00
watermeko
736259baa3 fix: locale 2026-07-17 07:47:25 +00:00
watermeko
83b600bbee fix: optimized UI of image download and locale issue 2026-07-16 11:16:36 +00:00
watermeko
6071a6f57c refactor(download): synchronize image and application transfers 
sovel the the problem that image downloading and app downloading would conflict
at same time
 2026-07-16 11:03:07 +00:00
watermeko
69f5da6fc7 feat(download): add sha256sum check and cancellable downloads 
+ server/proto/download.go
	+ add DownloadImageReq and sha256 argument

server/router/download.go
	+ add cancel download router

server/service/download/service.go
	+ sha256 decode and check
	+ remove HEAD request
	+ cancel download
 2026-07-16 11:03:07 +00:00
916BGAI
3b2ba7c0c1 docs: add 2.4.3 changelog entries 2026-06-09 18:06:03 +08:00
916BGAI
208998c13a support lt6911d 2026-06-09 18:00:32 +08:00
wenjie
3de4a18eb4 chore: update js-cookie for security fix 2026-05-22 10:43:17 +08:00
wenjie
863fea9ab8 release: nanokvm@2.4.2 2026-05-20 16:23:16 +08:00
wenjie
f65c1b06aa chore: refresh desktop menu ordering and community links 
- Replace the Discussion community link with Discord
- Align terminal and script ordering in the menu and appearance settings
- Remove the divider before the leader key menu item
 2026-05-20 15:07:59 +08:00
wenjie
fe34008ce3 fix: handle left-button touch cancel and contextmenu cleanup 2026-05-20 14:49:33 +08:00
wenjie
961d7f2e89 fix: validate Wi-Fi password field 2026-05-20 11:53:53 +08:00
wenjie
94749ea621 fix: harden Wake-on-LAN MAC handling 
Normalize stored MAC addresses, avoid shell execution for ether-wake, handle missing WOL history gracefully, and improve the WOL menu display for named MAC entries.
 2026-05-20 11:38:14 +08:00
wenjie
6ae742deed fix: improve WebRTC loading indicator 2026-05-19 17:31:19 +08:00
wenjie
b653f905e4 perf: improve H264 streaming client handling 
Use client snapshots for stream fanout, reduce frame queue latency, expose backend ICE server configuration to the WebRTC client, and clean up disconnected WebRTC clients more aggressively.
 2026-05-19 17:04:57 +08:00
wenjie
af19795c29 refactor: remove legacy h264 stream package 2026-05-19 16:49:41 +08:00
wenjie
be7584d908 feat: show HDMI capture status on desktop screen 
Track capture results for each stream mode, broadcast status updates over WebSocket, and display localized warning/error overlays in the desktop view.
 2026-05-19 15:02:34 +08:00
wenjie
a960417739 fix: stabilize PicoClaw session switching 
- Wait for gateway session release before reconnecting to a new or selected session
- Refresh runtime status before deciding whether a selected history session can reconnect
- Render structured thought messages from gateway payload metadata
- Prevent PicoClaw history rows from overflowing horizontally
- Add localized labels for the verifying install stage
 2026-05-18 17:26:00 +08:00
wenjie
3f0621e7ed Merge pull request #799 from BeaconCat/feat/picoclaw-v3-session-history 
feat(picoclaw): support sk_v1_ opaque session keys for V3 history
 2026-05-18 15:31:39 +08:00
wenjie
515c5e2a76 Merge pull request #798 from BeaconCat/feat/picoclaw-v3-config 
feat(picoclaw): adapt to PicoClaw V3 config format
 2026-05-18 15:23:05 +08:00
wenjie
cb025f04b4 chore(web): update PostCSS and MSW worker 
- Bump PostCSS to 8.5.10 and refresh the pnpm lockfile
- Regenerate the MSW service worker for msw 2.12.10
- Add pnpm build approvals for frontend tooling
 2026-05-18 15:02:31 +08:00
wenjie
2ca5b19efe release: nanokvm@2.4.1 2026-05-08 18:16:58 +08:00
wenjie
40f3917014 fix: update translation of DNS description 2026-05-08 17:34:27 +08:00
wenjie
a40433522c fix: improve DHCP DNS fallback detection 
Read DHCP DNS from /tmp/resolv.conf when the cached DHCP resolv file is empty, and only fall back to the active resolv.conf when DHCP mode is active or no manual boot config exists.
 2026-05-08 17:13:13 +08:00
wenjie
8470b89214 fix(i18n): sync translations for supported locales 
- Add missing localized strings for recent UI features, including keyboard shortcuts, clipboard paste, Wi-Fi AP auth, terminal options, device settings, Tailscale, updates, and PicoClaw.
- Align non-English locale resources with the English translation keys.
 2026-05-08 16:19:37 +08:00
wenjie
5a08170518 ui: optimize the scrollbar style of the settings 2026-05-08 14:56:50 +08:00
BeaconCat
dff794cee4 feat(picoclaw): adapt to PicoClaw V3 config format 
- channels -> channel_list with nested settings struct (V3 format)
- security channels -> channel_list.pico.settings.token
- Remove broken pico- prefix token composition logic
- Token now uses exact match with PicoClaw gateway
- Add GitHub Actions CI for building update package
- Version: 2.4.0.Beacon
 2026-05-08 08:30:08 +08:00
wenjie
36cf9c30d8 feat: add DNS management to Network settings 
- Add DNS configuration APIs for manual and DHCP modes, including persistence and udhcpc hook support.
- Add a Network settings tab with DNS controls, move Wi-Fi and HTTPS settings into it, and update translations.
- Update locales
 2026-05-07 17:03:25 +08:00
wenjie
1c43542919 fix: harden HID recovery and cleanup 
- Open HID gadget handles lazily in nonblocking mode and clear stale handles on write failures
- Release keyboard and mouse state when HID queues close or writes fail
- Reopen HID devices with retry after USB PHY reset
- Make websocket client close idempotent and close HID queues safely
- Expire and renew PicoClaw session locks during gateway relay
 2026-05-06 16:44:42 +08:00
BeaconCat
8eca1edf47 feat(picoclaw): support sk_v1_ opaque session keys for V3 history 2026-05-06 10:21:52 +08:00
wenjie
4080788cab chore: update README.md 2026-04-24 14:30:10 +08:00
wenjie
424302789e chore: update README.md 2026-04-24 14:17:32 +08:00
wenjie
6651167dd8 chore: upgrade vulnerable web dependencies 
- Bump Axios, Vite, ESLint, TypeScript ESLint, and related lockfile entries.
- Add yaml as an explicit frontend dev dependency.
 2026-04-24 10:40:20 +08:00
wenjie
2d67720022 fix: preserve loopback access for host configuration 
- Keep internal loopback HTTP APIs reachable when the server is bound to a
specific non-loopback host by adding a dedicated 127.0.0.1 listener.

- Move listener address helpers into utils and normalize HTTPS redirect hosts so
IPv6 request hosts are not double-bracketed.
 2026-04-24 10:29:16 +08:00
wenjie
1893912ba7 Merge pull request #792 from kmw0410/main 
update korean translation for picoclaw
 2026-04-24 10:05:43 +08:00
wenjie
e41ce2d6b8 Merge pull request #788 from ilyesAj/feat/add_french_layout 
Add French keyboard layout support on paste window
 2026-04-24 10:05:23 +08:00
wenjie
a5c6489f19 Merge pull request #770 from Voranto/Voranto-patch-2 
Fix wrong message during support build
 2026-04-24 09:55:51 +08:00
wenjie
fafef3d89a Merge pull request #779 from allmazz/feature/server_listen_host 
Add `host` server config parameter
 2026-04-24 09:46:11 +08:00
kmw0410
4b5f539445 update korean translation for picoclaw 2026-04-23 13:55:39 +09:00
wenjie
cefe0f9ab2 feat: add internal USB recovery and initialize picoclaw token 2026-04-16 17:00:16 +08:00
Kirill Nikiforov
7f3d29eba2 fix ipv6 2026-04-16 00:51:02 +04:00
Kirill Nikiforov
64681e2aac add host server config parameter 2026-04-14 06:51:06 +04:00
ilyesAj
fcb1f1c7fe Add French keyboard layout support and update language options 2026-04-11 22:39:40 +02:00
wenjie
aa0546ff37 release: nanokvm@2.4.0 2026-04-10 18:07:23 +08:00
wenjie
3254412017 Squashed commit of the following: 
commit 3dea4b1cfcb866d50c9c093b797c0f4f48fec23f
Author: wenjie <meetwenjie@gmail.com>
Date:   Fri Apr 10 17:11:07 2026 +0800

    fix(picoclaw): clean temp media and surface MCP screenshots in chat

    - remove shared load_image staging and pass source paths through directly
    - delete /tmp/picoclaw_media when a gateway session closes
    - push MCP screenshot observations to downstream websocket clients
    - hide null tool feedback messages and auto-scroll when screenshots load

commit f58ffe1e27f83f64e2b0e8c2f8dcac46af715ace
Author: wenjie <meetwenjie@gmail.com>
Date:   Fri Apr 10 15:55:59 2026 +0800

    Harden PicoClaw local API auth and session locking

    Split PicoClaw routes by caller trust level and require the internal loopback token for local-only endpoints. Update the NanoKVM bridge script to send the internal token for loopback requests. Relax session lock acquisition for screenshot and action calls so the active session can perform local operations without permanently taking over the lock, and stop forcing the runtime dm_scope default.

commit 462a0670bbc5138c893fbd1155e72465b82c2065
Author: wenjie <meetwenjie@gmail.com>
Date:   Fri Apr 10 13:52:39 2026 +0800

    fix(picoclaw): improve KVM reliability and sidebar behavior

    - follow HTTPS loopback redirects in the NanoKVM bridge script
    - enable MJPEG frame caching only during active PicoClaw gateway sessions
    - restore legacy screen zoom behavior across MJPEG and H264 renderers
    - keep the PicoClaw sidebar available on mobile without splitter layout conflicts
    - hide empty "null"/"undefined" chat messages and keep MJPEG failures on a black screen

commit bfda85c6368825c7ddf47d347ba5ec2588135885
Author: wenjie <meetwenjie@gmail.com>
Date:   Fri Apr 10 11:37:15 2026 +0800

    fix(picoclaw): verify runtime downloads and remove unused config API

    - verify the downloaded runtime archive against the published SHA-512 checksum
    - remove the unused /api/picoclaw/config endpoints and related frontend state
    - rename runtime_control.go to runtime_constants.go for clearer intent

commit 10b34aaea59e10d70c3cdecb01915444561ceaf7
Author: wenjie <meetwenjie@gmail.com>
Date:   Thu Apr 9 16:32:30 2026 +0800

    fix: stabilize picoclaw runtime defaults and secure local MCP access

    - persist required NanoKVM startup defaults before launching picoclaw and after saving model config
    - force-enable the pico channel when loading config so runtime status can recover to ready
    - derive the local MCP URL from the configured HTTP port and keep loopback-only HTTP access behind an internal token
    - move loopback HTTP redirect logic into middleware to simplify main server startup
    - improve runtime/sidebar state handling and add the load-image endpoint for active picoclaw sessions

commit d20540195bf45ea290f727b473ee8cd2a1bbb68d
Author: wenjie <meetwenjie@gmail.com>
Date:   Fri Mar 27 17:55:29 2026 +0800

    feat(picoclaw): add picoclaw integration
 2026-04-10 17:28:28 +08:00
BuGu
fda3c6b1a8 Add default mask for static IP 2026-03-27 10:50:18 +08:00
BuGu
97832557fb Fix the issue of occasional IP not displaying 2026-03-26 18:21:47 +08:00
wenjie
590db5b08c release: nanokvm@2.3.6 2026-03-12 16:02:18 +08:00
wenjie
10a512ec96 feat: Implement AP password authentication for the WiFi configuration page 2026-03-12 15:21:18 +08:00
wenjie
08093dddad Merge pull request #769 from Voranto/Voranto-patch-1 
Enable support for 640x480 resolution
 2026-03-12 11:21:17 +08:00
wenjie
86a85a61b7 Merge pull request #761 from klim4-bot/main 
feat : Add Korean and Japanese virtual keyboard layouts
 2026-03-12 11:20:54 +08:00
wenjie
cb3a2c562e Merge pull request #744 from tkmsst/pull-request 
Update Japanese translation
 2026-03-12 11:18:12 +08:00
Voranto
832832a716 Fix project name in build script for kvm_vision 2026-03-05 16:02:24 +01:00
Voranto
5fe6d0d48f Fix wrong message during ./build kvm_vision add_to_kvmapp 2026-03-05 15:57:44 +01:00
Voranto
67fe57f189 Enable support for 640x480 resolution 2026-03-05 15:52:49 +01:00
BuGu
44caee21ab Add encryption parameters for OLED distribution network 2026-03-04 17:11:42 +08:00
BuGu
5b2a1ff788 Add webpage logo generation tool and method 2026-03-04 17:09:52 +08:00
BuGu
dc5ba29bcf Add a logo file generator based on TUI 2026-03-03 19:12:59 +08:00
BuGu
89c14310c7 Add custom logo function 2026-03-03 18:50:35 +08:00
BuGu
3322a3c07f Add update mechanism for tailscale startup script 2026-03-03 18:49:02 +08:00
jason
57887f3f69 Add Korean and Japanese virtual keyboard layouts 2026-02-19 07:47:41 +09:00
tkmsst
2b8f640957 Update Japanese translation 2026-02-02 01:14:57 +09:00
439 changed files with 71639 additions and 10542 deletions
Expand all files Collapse all files

52
.devcontainer/Dockerfile Normal file
View File

@@ -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

49
.devcontainer/devcontainer.json Normal file
View File

@@ -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"
]
}
}
}

37
.devcontainer/post-create.sh Executable file
View File

@@ -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

132
.github/workflows/builder-image.yml vendored Normal file
View File

@@ -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"

108
.github/workflows/create-tag.yml vendored Normal file
View File

@@ -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"

296
.github/workflows/package.yml vendored Normal file
View File

@@ -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 }}

244
.github/workflows/release.yml vendored Normal file
View File

@@ -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"

9
.gitignore vendored
View File

@@ -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,8 @@ 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/
kvmapp/server
kvmapp/version

275
CHANGELOG.md
View File

@@ -1,3 +1,278 @@
## 2.5.4 (2026-11-10)
### Features
* Reworked the storage page around the NanoKVM Go file manager: the storage menu is now a two-card picker, "Disk mount" and "File sharing", that opens dedicated windows, and file sharing became a real file manager for the shared folder with list and icon views (remembered per browser), sorting by name, size, type and modified time, search in the current folder, breadcrumbs, inline folder expansion, new folder, download, delete, and uploads from the picker or by drag and drop, including folder upload with nested directories (thanks to [@liangzhuohua](https://github.com/liangzhuohua))
* Kept the two storage windows openable while the virtual disk is switched off, and let a disabled write action name the steps that unlock it: eject the virtual USB drive on the target machine and turn off the Virtual Disk switch in Settings > Device
* Removed the manual resolution setting: the video now follows the HDMI input resolution automatically, and the pointer and input-region code use the size of the frame the browser is actually showing
### Bug Fixes
* Fixed an application update leaving the page black or answering 404: service operations are serialized with an init-script lock, the migration finishes before services start, the startup script is installed atomically, recursive restarts are gone and the migration marker is kept until every required change succeeds
* Fixed video recovery after an application update leaving the encoder and VPSS in a broken state: video ownership is claimed before orphan VENC/VPSS resources are cleared, and the recovery SYS cleanup always runs to completion
* Fixed an updated web interface being hidden by a cached document: `index.html` now revalidates on every load and content-hashed assets are cached as immutable only while the file exists, so a stale document or a cached 404 is never pinned in the browser
* Fixed keyboard input being stolen from text fields: forwarding now skips events aimed at an input, textarea, select or contenteditable element and releases held keys when focus moves into one, so typing and pasting in the new dialogs works
* Fixed `/data` staying read-only while no medium was attached after a failed remount or an exFAT error; the media state poll now heals it and writable opens and transfers retry before failing
* Fixed the disk mount window reporting transfers it did not start by keeping the media job in the file manager
### Performance
* Reworked H.264 and MJPEG capture on the Sophgo SDK: each codec gets its own capture session and lock with encoder backpressure, frame ownership is explicit, capture stops as soon as the last viewer leaves, and the bundled video libraries were rebuilt
### UI Improvements
* Made a menu picker that opens its own window close without collapsing the menu bar
### Localization
* Translated the new storage page and file manager strings for all supported locales
### Chores
* Added a `POST /api/storage/media/files/mkdir` endpoint for recreating a folder tree during upload, with the same permission model as upload and delete, path and symlinked-parent validation, and a distinct error when the name is already taken by a file
* Rebuilt the bundled `libkvm.so` and `libkvm_mmf.so` against the Sophgo SDK and refreshed the build and deployment instructions
* Added unit tests for media file creation, read-only `/data` healing and the static file cache headers
## 2.5.3 (2026-11-03)
### Features
* Replaced the desktop image menu and the download page with a storage page that lists the media the emulated USB disk can carry, mounts and ejects them, and browses the files inside a medium over the same gadget, so the two machines exchange files without going through the terminal
* Added uploads, downloads and deletes to the storage page, with search, sorting, folder deletion behind a confirmation, one transfer display for image and file transfers, cancellable uploads, a free space preflight and a checksum mismatch report
* Browsed only media whose filesystem this device can read, so an ISO 9660 image is still served to the target machine but cannot be listed here, and limited CD-ROM mode to ISO 9660 and UDF images
* Made the shared folder follow the target machine: while it owns the data partition the listing refreshes on a timer after dropping the dentry and inode caches, so a file the target machine wrote shows up within a second of its own writeback
* Added a fine-grained permission system on top of the `admin` and `user` roles: administrators keep implicit full access, while every other account receives an explicit set of grants covering the console, power, media, terminal, device, network, updates, MCP, Tailscale and AI features, with the groups, risk marks and implied grants shown in a permission editor; mounting a medium needs the virtual disk, and the storage page names the account that has to enable it when the current account cannot
* Added a view-only console session for an account that may watch but not send input: the pointer and keyboard capture, the mouse menu and the input region editor follow the grant, pages, menus, settings tabs and storage actions render only what the account is allowed to use, and an account without console access lands on a page offering the sections its grants open
* Changed permission handling so an open session picks up the new grants without ending the login: a change that invalidates a cached capability drops the long-lived connection with a dedicated close code so the page reconnects, and only disabling an account ends the login
* Added the choice of regenerating the device-wide MCP API key when an account loses the MCP grant, instead of rotating the key silently and disconnecting every MCP client
* Kept the pre-2.6 image endpoints working as a compatibility layer over the new media API, so existing clients and scripts keep working
* Treated UDF images, not only ISO 9660 ones, as optical media, and accepted uploads by extension (`.iso`/`.img`), leaving an unusable image to fail when it is mounted instead of while it is stored
### Bug Fixes
* Fixed HID input being lost after a medium was mounted or the gadget was otherwise reset, by reopening the HID devices with a retry instead of a single attempt that could fail while the new nodes were still coming up
* Fixed `/data` staying read-only after a failed gadget script or a network switch
* Fixed the settings menu icon sitting a few pixels below the other menu icons, and centered the dialog tab icons in their box
* Fixed Chinese and Japanese punctuation being drawn by a Latin face in tooltips and dialogs, which pushed the ideographic comma and full stop above the baseline
### UI Improvements
* Gave the shared folder, ISO and IMG entries their own glyphs and picked file icons from the extension, so a listing can be read at a glance
* Listed administrators above regular accounts and gave their rows a lighter card
* Moved the PicoClaw chat composer to an antd text area and replaced the Radix scroll area with the native scroll container, so the settings dialog and the shortcut lists scroll like the rest of the app
### Localization
* Translated every string the storage page, the permission editor, the view-only console and the MCP key rotation add for all 24 supported locales
* Removed the keys the retired image menu and download page left behind
### Security
* Mounted images are opened through loop devices that refuse symlinks, and files inside a medium are opened without following links
### Chores
* Removed the desktop image menu, the download page and their web client code
* Dropped the `@radix-ui/react-scroll-area` dependency
* Documented the permission catalog, the split between mounting media and writing the library, and the grants that reach the whole device in `server/README.md` and `server/README_ZH.md`
## 2.5.2 (2026-09-29)
### Features
* Added a one-writer policy for the emulated USB disk and the `/data` partition: `/data` is mounted read-only from boot while the virtual disk serves the raw partition to the target machine, enabling the disk remounts it read-only and verifies the state before the target machine can write it, refusing to expose the disk when the remount fails, and releasing a medium hands the raw partition back to the target machine the same way
* Added confirmation before a mounted medium and the virtual disk take the shared partition from each other, including a warning that a running image transfer is cancelled and that `/data` becomes read-only on this device
* Added cancellation of a running image transfer before the partition handover, showed the transfer state in the image list and disabled the actions that cannot run while a medium is mounted, with a hint explaining why
* Added names for the mounted medium and the emulated USB device taken from the image file, truncated to the SCSI inquiry product field and the USB product string and restored on unmount
* Added streaming validation of uploaded images: ISO 9660 and UDF volume descriptors and raw disk images (GPT, APFS, HFS+, MBR) are accepted and anything else is rejected in seconds instead of after the whole transfer, with a free space check that keeps a 128 MiB reserve before any byte is received
### Bug Fixes
* Fixed mass storage mounts staying writable from the target machine: every mounted image is now served read-only, with the flag set before the LUN is attached, so the target machine can neither write to nor format it
* Fixed the LUN flags surviving a gadget restart, which brought the shared partition back to the target machine read-only or as an optical drive after a medium had been mounted
* Fixed the virtual disk switch staying on but unchangeable while a medium was mounted; the disk now reports itself on only while the LUN really carries the `/data` partition
* Fixed the on-screen keyboard crashing the page with "Minified React error #130" as soon as it was opened, by importing the `react-simple-keyboard` component through its named export, which the CommonJS interop under Vite 8 no longer resolves from a default import
### Localization
* Translated the new virtual disk and image mounting strings for every locale
### Chores
* Added unit tests for the upload header check, the free space preflight and the image name truncation
## 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

79
Makefile
View File

@@ -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 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
# 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)
.PHONY: help check-root builder-image rebuild-image check-image shell app support all clean
# Build commands
GO_BUILD_CMD := cd /home/build/NanoKVM/server && ./build.sh
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 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."

111
README.md
View File

@@ -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: inside the container, run `./build.sh` from `server/`. On the host, `make app` runs the same script in Docker. Both use the prebuilt libraries in `server/dl_lib/`, enable the BoringCrypto build option, and set the `dl_lib` RPATH.
- 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.

29
docker/Dockerfile
View File

@@ -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"]

10
docker/entrypoint Normal file → Executable file
View File

@@ -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 "$@"

45
kvmapp/picoclaw/AGENT.md Normal file
View File

@@ -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.

46
kvmapp/picoclaw/AGENT_KVM.md Normal file
View File

@@ -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.

94
kvmapp/picoclaw/skills/kvm-control/SKILL.md Normal file
View File

@@ -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.

1123
kvmapp/picoclaw/skills/kvm-control/scripts/nanokvm-bridge.sh Executable file
View File

File diff suppressed because it is too large Load Diff

9
kvmapp/system/init.d/S01fs
View File

@@ -35,7 +35,14 @@ then
if [ -e /dev/mmcblk0p3 ]
then
mkdir -p /data
mount /dev/mmcblk0p3 /data
# The partition is the virtual disk. While it is shared as a writable
# disk the host is the only writer, so mount it read-only here.
if [ -e /boot/usb.disk0 ] && [ ! -e /boot/usb.disk0.ro ] && [ ! -s /boot/usb.disk0 ]
then
mount -o ro /dev/mmcblk0p3 /data
else
mount /dev/mmcblk0p3 /data
fi
fi
echo "OK"

43
kvmapp/system/init.d/S03usbdev
View File

@@ -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
@@ -99,11 +134,15 @@ start_usb_dev(){
mkdir functions/mass_storage.disk0
ln -s functions/mass_storage.disk0 configs/c.1/
echo 1 > functions/mass_storage.disk0/lun.0/removable
# The LUN flags survive a restart of this script, so they are always set:
# a mounted image leaves them read-only and in CD-ROM mode.
if [ -e /boot/usb.disk0.ro ]
then
echo 1 > functions/mass_storage.disk0/lun.0/ro
echo 0 > functions/mass_storage.disk0/lun.0/cdrom
else
echo 0 > functions/mass_storage.disk0/lun.0/ro
fi
echo 0 > functions/mass_storage.disk0/lun.0/cdrom
echo "NanoKVM USB Mass Storage0520" > functions/mass_storage.disk0/lun.0/inquiry_string
disk=$(cat /boot/usb.disk0)
if [ -z "${disk}" ]

41
kvmapp/system/init.d/S15kvmhwd
View File

@@ -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

18
kvmapp/system/init.d/S30eth
View File

@@ -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")

110
kvmapp/system/init.d/S95nanokvm
View File

@@ -1,9 +1,84 @@
#!/bin/sh
# nanokvm Rev3.1
exec 9>/run/nanokvm-service.lock || exit 1
flock -n 9 || { echo "NanoKVM service operation already in progress" >&2; exit 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 || {
echo "Failed to stop $process" >&2
return 1
}
}
stop_services() {
# The server owns VI/VPSS. Let it release MMF before stopping kvm_system.
stop_process NanoKVM-Server || return 1
stop_process kvm_system || return 1
}
start_services() {
if pidof NanoKVM-Server >/dev/null 2>&1 && pidof kvm_system >/dev/null 2>&1; then
return 0
fi
if pidof NanoKVM-Server >/dev/null 2>&1 || pidof kvm_system >/dev/null 2>&1; then
echo "NanoKVM is partially running; use restart" >&2
return 1
fi
rm -rf /tmp/kvm_system /tmp/server || return 1
cp -r /kvmapp/kvm_system /tmp/ || return 1
if [ -f /kvmapp/kvm_new_app ]; then
/tmp/kvm_system/kvm_system --migrate 9>&-
case "$?" in
0) ;;
2) sync; reboot; return "$?" ;;
*) echo "NanoKVM migration failed" >&2; return 1 ;;
esac
fi
cp -r /kvmapp/server /tmp/ || return 1
# Daemons must not inherit the service-operation lock.
/tmp/kvm_system/kvm_system 9>&- &
/tmp/server/NanoKVM-Server 9>&- &
}
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 +107,30 @@ 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 || exit 1
;;
stop)
killall kvm_system
killall NanoKVM-Server
rm -r /tmp/kvm_system /tmp/server
stop_services || exit 1
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 &
stop_services || exit 1
start_services || exit 1
sync
echo "OK"
@@ -66,4 +140,4 @@ case "$1" in
echo "Usage: $0 {start|stop|restart}"
exit 1
;;
esac
esac

249
kvmapp/system/init.d/S96picoclaw Executable file
View File

@@ -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

107
scripts/README.md Normal file
View File

@@ -0,0 +1,107 @@
# 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 (input dimensions, 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.
## Video library linking
`make app` and `server/build.sh` compile the server using the prebuilt libraries
in `server/dl_lib/`. They do not rebuild the video libraries. The cgo directive
in `server/common/kvm_vision.go` links against `libkvm.so`, which depends on
`libkvm_mmf.so`.
`make vision` rebuilds the video libraries and stages them in
`kvmapp/server/dl_lib/`; `make release-build` does this as part of the full build.
After changing library interfaces, update both prebuilt files in
`server/dl_lib/` from the same build. The tracked directory also supplies the
SDK runtime libraries used by the video build and backfills libraries that
are absent from the staged directory.
`build-in-container.sh` checks that the staged `libkvm.so` exports every KVM
symbol imported by the server. See the [server instructions](../server/README.md#compile--deploy)
for manual compilation and deployment.

133
scripts/build-in-container.sh Executable file
View File

@@ -0,0 +1,133 @@
#!/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"
# Each support build synchronizes the repository components before compiling.
cd "$NANOKVM_PATH/support/sg2002"
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
# Confirm the shipped video libraries provide every KVM symbol imported by
# the server, including the frame ownership API.
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
}
shipped_lib="$NANOKVM_PATH/kvmapp/server/dl_lib/libkvm.so"
server_bin="$NANOKVM_PATH/server/NanoKVM-Server"
needed=$(imported "$server_bin" | awk '/^(kvmv_|free_kvmv_data$|free_all_kvmv_data$|set_h264_gop$|set_frame_detact$|set_venc_auto_recyc$)/')
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"

103
scripts/compare-release.sh Executable file
View File

@@ -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"

231
scripts/package.sh Executable file
View File

@@ -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"

157
scripts/verify-release-assets.sh Executable file
View File

@@ -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"

43
scripts/verify-release-tag.sh Executable file
View File

@@ -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"

106
server/README.md
View File

@@ -28,6 +28,7 @@ The configuration file path is `/etc/kvm/server.yaml`.
```yaml
# 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 # 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`
@@ -47,7 +48,7 @@ authentication: enable # Whether to enable identity verification fo
jwt:
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 to invalidate all existing tokens upon logout by rotating the SecretKey. Default is `true`
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`
@@ -61,9 +62,110 @@ turn:
turnCred: example_cred # The credential/password required for authorization to the TURN server
```
## Web Users
NanoKVM uses two device-wide roles:
- `admin`: everything below, plus user management.
- `user`: only what the account is granted.
A grant names an action on one party, and the catalog the server serves to the account editor
carries its group, its risk, and the grants it implies:
| Group | Grants |
| --- | --- |
| console (this session) | `console.view`, `console.control` |
| target machine | `power`, `medium.attach` |
| media library (this device) | `library.read`, `library.write` |
| this device | `terminal`, `device`, `network`, `update` |
| services | `mcp`, `tailscale`, `ai` |
Implied grants are declared once, in the catalog, and the server resolves them before answering any
request: `console.control` implies `console.view`, both `medium.attach` and `library.write` imply
`library.read`, and every grant whose controls live in the console menu — `power`, `device`,
`network`, `update`, `mcp`, `tailscale` and `ai` — implies `console.view` too, because no page
outside the console renders them. Consequences worth knowing:
- An account can hold no console access at all. The web app then lands on a page that offers the
sections the account may use (the media library, the terminal) instead of a console it cannot
open. `library.read` is all that media access needs, because the other two media grants imply it,
and only `terminal` and the media grants can stand on their own pages in the first place.
- The media grants split along the trust boundary. `medium.attach` mounts or ejects a medium on the
target machine and writes into the shared partition the target reads; `library.write` changes what
the library keeps (uploads, deletes, the files inside an image); `library.read` lists and downloads.
The file endpoints serve an image and the shared partition through one path, so the route admits
either grant and each request is checked against the medium type it names. Every `.iso` and
`.img` on the partition is a library entry, so uploading one through the shared partition, or
deleting a file or folder that holds one, also needs `library.write`.
- The emulated USB devices are neither media nor network: the virtual disk and the RNDIS adapter
hand the target machine the raw data partition and a network interface, so both follow `device`.
A medium can only be attached while a `device` holder has the virtual disk switched on, and the
storage page says so when it is off.
Four grants reach further than their names suggest and amount to full device control. The catalog
has two risk levels, and `warn` is reserved for them: the account editor marks those four and
names them before the grants are saved:
- `terminal` is a root shell (the same one SSH gives) and can run saved and autostart scripts.
- `mcp` hands out a device-wide API key that drives the keyboard, mouse and screenshots from
outside the web session. The key is shared, so a copy keeps working after an account loses this
grant. Whenever a change takes the grant away (revoked, demoted, disabled or deleted), the account
editor warns and offers to regenerate the key, checked by default; regenerating disconnects every
MCP client until it is given the new key, and an administrator who keeps the key accepts that a
copy stays valid. The API takes the choice as `rotateMcpKey` (a body field on update, a query
parameter on delete) and never rotates without it.
- `ai` drives the device through the local loopback interface, which the other grants do not
restrict.
- `update` installs firmware and application packages. An offline package is checked only against
the checksum its uploader supplies, so installing one is running code as root.
`device` carries no such mark, although it changes what the device does for everyone and cannot be
narrowed per account. `device` turns SSH on or off (root login, with the device
owner's password), reboots the device, hands the raw data partition or a network interface to the
target machine through the emulated USB devices, and edits the OLED, HDMI, mDNS, memory, swap and
HID settings. The editor describes it that way.
Two grants also change settings that affect everyone watching: `console.view` sets the video mode,
resolution, frame rate and quality, and resets the HDMI capture; `power` manages the Wake-on-LAN
device list. Both are described that way in the editor.
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: every request is authorized
against the account file, so a revoked grant stops working immediately without re-issuing a login.
Disabling, deleting, or resetting the password of a user invalidates that user's HTTP and real-time
connections without affecting other users. Changing the role or the grants of an account keeps its
login valid: the account is told to refresh, and only the long-lived connections whose cached
state depends on what changed are dropped (console, video stream, terminal, AI), so those clients
reconnect under the new grants. An account that loses `console.view` is sent to the landing page
instead of a console it can no longer open. Multiple
users may watch and control the KVM concurrently; input uses the existing cooperative HID
coordinator, so simultaneous input can interleave. A user without `console.control` keeps the
video and the menu for its other grants, but the console rejects keyboard and mouse reports and
the web UI marks the session as view only.
Video mode, quality, resolution, MJPEG frame-detection controls, and resetting the HDMI capture
require only `console.view` and stay shared KVM operations; when several users adjust them
concurrently, the latest change applies device-wide. Enabling or disabling the HDMI capture and
its idle timeout are device settings. `console.control` is input only: keyboard, mouse, paste, and
the input region that maps pointer motion onto the target screen.
The account file stores an explicit grant set: a record written before fine-grained permissions
keeps exactly what the user role used to grant, and the split media grants are translated on load,
so the store never holds a missing set that would fall back to different behavior later. Grants
this build does not know are preserved and ignored, so a downgrade cannot lock the device out.
Creating a regular account without naming a grant set keeps that same meaning, so a script that only
knows about roles gets the account the user role used to create; the account editor seeds a new
regular account with `console.view` only, and an explicitly empty set really is empty.
## 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).

3
server/README_JA.md
View File

@@ -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)。

79
server/README_ZH.md
View File

@@ -26,6 +26,7 @@ server
```yaml
# 网络设置
proto: http # 访问协议，默认为 `http`，仅当配置了证书时支持改为 `https`
host: ""
port:
http: 80 # HTTP 服务的监听端口，默认为 `80`
https: 443 # HTTPS 服务的监听端口（启用 https 协议时生效），默认为 `443`
@@ -45,7 +46,7 @@ authentication: enable # 是否开启 HTTP 接口与网页的身份
jwt:
secretKey: "" # 用于签发和验证 JWT Token 的密钥。如果不填，服务启动时将自动随机生成
refreshTokenDuration: 2678400 # 登录超时的刷新周期（单位：秒）。默认为 `2678400`（约31天）
revokeTokensOnLogout: true # 退出登录时是否废除所有现存的 Token。启用此项可以在注销时轮换 SecretKey，强迫所有终端重新登录。默认为 `true`
revokeTokensOnLogout: true # 退出登录时是否废除该用户的全部会话；不会影响其他用户。设为 false 时仅清除浏览器 Cookie，不推荐使用。默认为 `true`
security:
loginLockoutDuration: 0, # 达到失败上限后，禁止该 IP 再次尝试登录的持续时间（单位：秒）。如果设为 `0` 或不填，则代表不开启防暴力破解功能。默认为 `0`
loginMaxFailures: 5, # 允许触发保护前，单个 IP 连续登录失败的最大次数。默认为 `5`
@@ -59,9 +60,83 @@ turn:
turnCred: example_cred # TURN 服务器授权连接时使用的凭据/密码
```
## Web 多用户
NanoKVM 使用两种设备级角色：
- `admin`：拥有以下全部能力，并可管理用户。
- `user`：仅拥有被授予的功能权限。
每项权限都描述“对谁做什么”，服务端下发给账户编辑器的权限目录还带有分组、风险等级和蕴含关系：
| 分组 | 权限 |
| --- | --- |
| 控制台（本会话） | `console.view`、`console.control` |
| 被控机 | `power`、`medium.attach` |
| 介质库（本设备） | `library.read`、`library.write` |
| 本设备 | `terminal`、`device`、`network`、`update` |
| 服务 | `mcp`、`tailscale`、`ai` |
蕴含关系只在权限目录里声明一次，并由服务端在应答任何请求前解析：`console.control` 蕴含
`console.view`，`medium.attach` 与 `library.write` 都蕴含 `library.read`；而控制项位于控制台菜单里的
权限——`power`、`device`、`network`、`update`、`mcp`、`tailscale`、`ai`——同样蕴含 `console.view`，
因为控制台之外没有任何页面渲染它们。由此得到几个行为：
- 账户可以完全没有控制台权限。此时 Web 界面会落到一个提示页，列出该账户可用的页面
（介质库、终端），而不是打开一个它无权访问的控制台。媒体功能只需要 `library.read`，
因为另外两项媒体权限都蕴含它；也只有 `terminal` 与媒体权限能拥有控制台之外的独立页面。
- 媒体权限按信任边界拆分：`medium.attach` 在被控机上挂载/弹出介质，并写入被控机可读的共享分区；
`library.write` 修改库内容（上传、删除、镜像内的文件）；`library.read` 负责列表与下载。
文件相关接口用同一路径同时服务镜像与共享分区，因此路由同时接受这两项权限之一，
再按请求指定的介质类型做校验。分区上的每个 `.iso`、`.img` 都属于介质库，因此经共享分区上传这类文件，
或删除本身是/内含这类文件的文件或文件夹，同样需要 `library.write`。
- 模拟的 USB 设备既不属于媒体也不属于网络：虚拟磁盘与 RNDIS 虚拟网卡分别把设备的原始数据分区
和一块网卡交给被控机，因此都归 `device`。只有拥有 `device` 权限的账户开启虚拟磁盘后，才能挂载
镜像；磁盘未开启时存储页面会给出提示。
以下四项权限的实际范围比名称更大，等同于完整的设备控制权；权限目录只有两个风险等级，`warn`
专用于它们，账户编辑器会做标记并在保存前按名称列出：
- `terminal`：即 root shell（与 SSH 相同），并可运行已保存的脚本和开机自启脚本。
- `mcp`：会下发设备级 API Key，可在 Web 会话之外控制键鼠并获取截图。Key 为共用，账户失去该权限后已复制的
Key 仍然有效。任何会让账户失去该权限的操作（撤销、降级、禁用或删除），账户编辑器都会警告并提供「重新生成
Key」选项（默认勾选）；重新生成会断开所有 MCP 客户端直到换用新 Key，管理员选择保留则自行承担副本仍有效的风险。
API 通过 `rotateMcpKey` 传递该选择（更新时放在请求体，删除时放在查询参数），不带它就不会轮换。
- `ai`：通过本地回环接口操作设备，不受其他权限限制。
- `update`：安装固件与应用更新包。离线包只校验上传者自己提供的校验和，安装它即等于以 root 运行代码。
`device` 不做该标记：它仍在本账户被授予的设置范围内，但会改变设备对所有人生效的行为，
且无法按账户收窄。`device` 可开关 SSH（root，口令为设备所有者口令）、重启设备、通过模拟的 USB 设备把
原始数据分区或网卡交给被控机，并修改 OLED、HDMI、mDNS、内存、交换与 HID 设置。编辑器中对此同样有说明。
另有两项权限会改动影响所有观看者的设置：`console.view` 会设置视频模式、分辨率、帧率与画质，
并复位 HDMI 采集；`power` 会管理网络唤醒设备列表。编辑器中对这两项都有明确说明。
管理员可在**设置 > 账户**中管理用户。账户数据继续保存在 `/etc/kvm/pwd`；服务会原地迁移旧版单账户
JSON，并以 `0600` 权限原子写入多用户格式。沿用同一路径可保持长按 BOOT 键重置密码的现有行为。
用户自助修改密码时必须验证当前密码；管理员可在账户管理中重置非设备所有者的密码。由于设备所有者
密码还会同步至 Linux root 账户，因此只有设备所有者本人可以修改自己的密码。
所有登录会话都会校验当前账户状态：每个请求都按账户文件重新授权，因此被撤销的权限会立即失效，
无需重新登录。禁用、删除或重置密码会立即撤销该用户的 HTTP 与实时连接，且不会影响其他用户。
修改角色或权限不会失效登录：账户会收到刷新通知，只会断开缓存了相关状态的长期连接
（控制台、视频流、终端、AI），这些客户端随后会以新权限重连。失去 `console.view` 的账户会被
转到提示页，而不是一个无法打开的控制台。多个用户可同时观看和协作控制 KVM；输入沿用现有 HID
协调器，因此同时输入可能交错。没有 `console.control` 的用户仍可观看画面并使用其其他权限对应的菜单，
但控制台会丢弃其键鼠报文，Web 界面会将会话标记为只读。
视频模式、画质、分辨率、MJPEG 帧检测以及复位 HDMI 采集只要求 `console.view`，仍属于共享 KVM 操作；
多人同时调整时，以最后一次设备级修改为准。启用/关闭 HDMI 采集及其空闲超时则属于设备设置。
`console.control` 仅限输入：键盘、鼠标、粘贴，以及将指针位移映射到目标机画面的输入区域。
账户文件保存的是显式权限集合：细粒度权限出现之前写入的记录，在读取时会物化为当时 user 角色的
能力，拆分过的媒体权限也会被翻译成新名称，因此存储中不会留下“缺失即回退到另一套行为”的状态。
本版本不认识的权限会被原样保留并忽略，因此回滚版本不会把设备锁在门外。
新建普通账户时若不指定权限集合，含义同上：只认识角色的脚本仍会得到 user 角色过去创建出的账户；
账户编辑器新建普通账户时只预置 `console.view`，而显式传入的空集合就是真的空。
## 编译部署
**注意：请使用 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)；

322
server/authn/permissions.go Normal file
View File

@@ -0,0 +1,322 @@
package authn
import (
"fmt"
)
// Permission identifies a grantable capability. The admin role implicitly holds
// every permission; the user role only holds the permissions stored on the
// account.
//
// A permission names what it lets the account do, not the settings page it
// lives on, and every grant that changes something shared says so in the
// catalog's risk and effect metadata instead of in the label alone.
type Permission string
const (
// Console grants.
PermConsoleView Permission = "console.view"
PermConsoleControl Permission = "console.control"
// Target-machine grants.
PermPower Permission = "power"
PermMediumAttach Permission = "medium.attach"
// Media library grants.
PermLibraryRead Permission = "library.read"
PermLibraryWrite Permission = "library.write"
// Host grants.
PermTerminal Permission = "terminal"
PermDevice Permission = "device"
PermNetwork Permission = "network"
PermUpdate Permission = "update"
// Service grants.
PermMcp Permission = "mcp"
PermTailscale Permission = "tailscale"
PermAi Permission = "ai"
)
// Group names the party a grant reaches. The account editor renders one section
// per group, so the sections stay meaningful as the catalog grows.
type Group string
const (
// GroupConsole is what an account may do with the console it is watching.
GroupConsole Group = "console"
// GroupTarget is what it may do to the machine behind the console.
GroupTarget Group = "target"
// GroupLibrary is what it may do with the media library on this device.
GroupLibrary Group = "library"
// GroupHost is what it may change on this device.
GroupHost Group = "host"
// GroupServices are the add-ons that reach the device on their own.
GroupServices Group = "services"
)
// Risk states how far a grant reaches, and the catalog carries two levels: a
// plain grant, and the grants that amount to full device control, which the
// account editor marks and names before the grants are saved.
type Risk string
const (
// RiskInfo is a grant that stays within the feature it names.
RiskInfo Risk = "info"
// RiskWarn is a grant that amounts to full device control: a root shell,
// the AI loopback, an API key that drives input outside the web session, and
// a package install whose checksum the uploader supplies.
RiskWarn Risk = "warn"
)
// Descriptor is one catalog entry: the grant, the group it belongs to, the risk
// an administrator takes by granting it, and the grants it implies.
type Descriptor struct {
Permission Permission `json:"id"`
Group Group `json:"group"`
Risk Risk `json:"risk"`
Implies []Permission `json:"implies,omitempty"`
}
// Implied grants are declared once here instead of as unions at every call
// site: control without the picture is meaningless, nothing can be attached or
// changed in the library without being allowed to see it first, and the grants
// whose controls live in the console menu imply the console, because no page
// outside it renders them and a grant nothing can use is a promise the app
// cannot keep. Terminal and the media grants stand on their own pages.
var permissionCatalog = []Descriptor{
{Permission: PermConsoleView, Group: GroupConsole, Risk: RiskInfo},
{
Permission: PermConsoleControl,
Group: GroupConsole,
Risk: RiskInfo,
Implies: []Permission{PermConsoleView},
},
{
Permission: PermPower,
Group: GroupTarget,
Risk: RiskInfo,
Implies: []Permission{PermConsoleView},
},
{
Permission: PermMediumAttach,
Group: GroupTarget,
Risk: RiskInfo,
Implies: []Permission{PermLibraryRead},
},
{Permission: PermLibraryRead, Group: GroupLibrary, Risk: RiskInfo},
{
Permission: PermLibraryWrite,
Group: GroupLibrary,
Risk: RiskInfo,
Implies: []Permission{PermLibraryRead},
},
{Permission: PermTerminal, Group: GroupHost, Risk: RiskWarn},
{
Permission: PermDevice,
Group: GroupHost,
Risk: RiskInfo,
Implies: []Permission{PermConsoleView},
},
{
Permission: PermNetwork,
Group: GroupHost,
Risk: RiskInfo,
Implies: []Permission{PermConsoleView},
},
{
Permission: PermUpdate,
Group: GroupHost,
Risk: RiskWarn,
Implies: []Permission{PermConsoleView},
},
{
Permission: PermMcp,
Group: GroupServices,
Risk: RiskWarn,
Implies: []Permission{PermConsoleView},
},
{
Permission: PermTailscale,
Group: GroupServices,
Risk: RiskInfo,
Implies: []Permission{PermConsoleView},
},
{
Permission: PermAi,
Group: GroupServices,
Risk: RiskWarn,
Implies: []Permission{PermConsoleView},
},
}
// Grants of earlier releases, kept so an account file written by one of them
// keeps meaning what it meant. media.mount and media.manage split into the
// attach/read/write grants above.
const (
legacyPermMediaMount Permission = "media.mount"
legacyPermMediaManage Permission = "media.manage"
)
// Catalog returns the catalog in display order.
func Catalog() []Descriptor {
catalog := make([]Descriptor, len(permissionCatalog))
for index, descriptor := range permissionCatalog {
catalog[index] = descriptor
catalog[index].Implies = append([]Permission(nil), descriptor.Implies...)
}
return catalog
}
// PermissionIDs returns every grantable permission in catalog order.
func PermissionIDs() []Permission {
ids := make([]Permission, 0, len(permissionCatalog))
for _, descriptor := range permissionCatalog {
ids = append(ids, descriptor.Permission)
}
return ids
}
func IsValidPermission(permission Permission) bool {
for _, descriptor := range permissionCatalog {
if descriptor.Permission == permission {
return true
}
}
return false
}
// ValidatePermissions rejects unknown or duplicate permissions. It is for grant
// sets arriving in a request; the grant set stored on an account is validated by
// ValidateStoredPermissions, which tolerates ids this build does not know.
func ValidatePermissions(permissions []Permission) error {
seen := make(map[Permission]struct{}, len(permissions))
for _, permission := range permissions {
if !IsValidPermission(permission) {
return fmt.Errorf("unknown permission: %q", permission)
}
if _, exists := seen[permission]; exists {
return fmt.Errorf("duplicate permission: %q", permission)
}
seen[permission] = struct{}{}
}
return nil
}
// ValidateStoredPermissions only rejects duplicates. An account file written by
// a newer release carries grants this build cannot evaluate, and refusing to
// load it would lock the device out instead of ignoring a capability that is
// unavailable here anyway.
func ValidateStoredPermissions(permissions []Permission) error {
seen := make(map[Permission]struct{}, len(permissions))
for _, permission := range permissions {
if _, exists := seen[permission]; exists {
return fmt.Errorf("duplicate permission: %q", permission)
}
seen[permission] = struct{}{}
}
return nil
}
// Has reports whether the set contains the permission. Administrators are not
// special-cased: callers that should honor the role's implicit grants resolve
// EffectivePermissions first.
func Has(permissions []Permission, permission Permission) bool {
for _, granted := range permissions {
if granted == permission {
return true
}
}
return false
}
// Closure resolves the grants an account ends up holding: the set itself plus
// everything it implies, transitively, in catalog order.
func Closure(permissions []Permission) []Permission {
granted := closureSet(permissions)
resolved := make([]Permission, 0, len(granted))
for _, descriptor := range permissionCatalog {
if _, ok := granted[descriptor.Permission]; ok {
resolved = append(resolved, descriptor.Permission)
delete(granted, descriptor.Permission)
}
}
// Keep ids this build does not know in the order they were stored, so they
// still round-trip through the client.
for _, permission := range permissions {
if _, ok := granted[permission]; ok {
resolved = append(resolved, permission)
delete(granted, permission)
}
}
return resolved
}
func closureSet(permissions []Permission) map[Permission]struct{} {
granted := make(map[Permission]struct{}, len(permissions))
var add func(Permission)
add = func(permission Permission) {
if _, exists := granted[permission]; exists {
return
}
granted[permission] = struct{}{}
for _, descriptor := range permissionCatalog {
if descriptor.Permission != permission {
continue
}
for _, implied := range descriptor.Implies {
add(implied)
}
}
}
for _, permission := range permissions {
add(permission)
}
return granted
}
// NormalizeStoredPermissions translates the grants an earlier release wrote and
// removes duplicates, so the store holds one spelling of every capability.
// Unknown ids are preserved: a downgrade must not silently drop a grant.
func NormalizeStoredPermissions(permissions []Permission) []Permission {
normalized := make([]Permission, 0, len(permissions)+2)
appendOnce := func(permission Permission) {
if !Has(normalized, permission) {
normalized = append(normalized, permission)
}
}
for _, permission := range permissions {
switch permission {
case legacyPermMediaMount:
// Attaching a medium is what let a watcher read the library.
appendOnce(PermMediumAttach)
appendOnce(PermLibraryRead)
case legacyPermMediaManage:
appendOnce(PermLibraryRead)
appendOnce(PermLibraryWrite)
default:
appendOnce(permission)
}
}
return normalized
}
// legacyUserPermissions preserves the capabilities the user role had before
// fine-grained permissions existed: full console access and power control.
func legacyUserPermissions() []Permission {
return []Permission{PermConsoleView, PermConsoleControl, PermPower}
}
// EffectivePermissions resolves what a user can actually do: administrators
// hold the whole catalog, regular users hold their stored grants and whatever
// those imply.
func EffectivePermissions(user *User) []Permission {
if user == nil {
return nil
}
if user.Role == RoleAdmin {
return PermissionIDs()
}
return Closure(user.Permissions)
}

86
server/authn/permissions_test.go Normal file
View File

@@ -0,0 +1,86 @@
package authn
import (
"encoding/json"
"os"
"path/filepath"
"slices"
"testing"
)
func TestClosureResolvesImpliedGrants(t *testing.T) {
cases := []struct {
grants []Permission
want []Permission
}{
{[]Permission{PermConsoleControl}, []Permission{PermConsoleView, PermConsoleControl}},
{[]Permission{PermMediumAttach}, []Permission{PermMediumAttach, PermLibraryRead}},
{[]Permission{PermLibraryWrite}, []Permission{PermLibraryRead, PermLibraryWrite}},
{[]Permission{PermTerminal}, []Permission{PermTerminal}},
{[]Permission{"future.grant", PermMcp}, []Permission{PermConsoleView, PermMcp, "future.grant"}},
}
for _, tc := range cases {
if got := Closure(tc.grants); !slices.Equal(got, tc.want) {
t.Errorf("Closure(%v) = %v, want %v", tc.grants, got, tc.want)
}
}
}
func TestNormalizeTranslatesLegacyMediaGrants(t *testing.T) {
got := NormalizeStoredPermissions([]Permission{legacyPermMediaMount, legacyPermMediaManage, PermPower})
want := []Permission{PermMediumAttach, PermLibraryRead, PermLibraryWrite, PermPower}
if !slices.Equal(got, want) {
t.Fatalf("NormalizeStoredPermissions = %v, want %v", got, want)
}
}
func TestUpdateReturnsPreviousAndKeepsUnknownGrants(t *testing.T) {
path := filepath.Join(t.TempDir(), "pwd")
store := NewStore(path)
if err := store.Create("alice", "password", RoleUser, PermConsoleView); err != nil {
t.Fatal(err)
}
// A newer release stored a grant this build does not know.
data, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
var db database
if err = json.Unmarshal(data, &db); err != nil {
t.Fatal(err)
}
index := userIndex(db.Users, "alice")
db.Users[index].Permissions = append(db.Users[index].Permissions, "future.grant")
if data, err = json.Marshal(db); err != nil {
t.Fatal(err)
}
if err = os.WriteFile(path, data, 0o600); err != nil {
t.Fatal(err)
}
grants := []Permission{PermConsoleControl}
previous, updated, err := store.Update("admin", "alice", UserPatch{Permissions: &grants})
if err != nil {
t.Fatal(err)
}
if !slices.Equal(previous.Permissions, []Permission{PermConsoleView, "future.grant"}) {
t.Fatalf("previous permissions = %v", previous.Permissions)
}
if !slices.Equal(updated.Permissions, []Permission{PermConsoleControl, "future.grant"}) {
t.Fatalf("updated permissions = %v", updated.Permissions)
}
}
func TestOnlyFullControlGrantsWarn(t *testing.T) {
var warned []Permission
for _, descriptor := range Catalog() {
if descriptor.Risk == RiskWarn {
warned = append(warned, descriptor.Permission)
}
}
want := []Permission{PermTerminal, PermUpdate, PermMcp, PermAi}
if !slices.Equal(warned, want) {
t.Fatalf("warned grants = %v, want %v", warned, want)
}
}

719
server/authn/store.go Normal file
View File

@@ -0,0 +1,719 @@
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"`
Permissions []Permission `json:"permissions"`
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"`
Permissions []Permission `json:"permissions"`
SystemAccount bool `json:"systemAccount,omitempty"`
}
type UserPatch struct {
Role *Role
Enabled *bool
Permissions *[]Permission
}
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 index := range db.Users {
user := &db.Users[index]
// The stored grants, not the effective ones: the editor shows what an
// administrator set, and what an account implies is derived from the
// catalog instead of being written back on every save.
users = append(users, UserInfo{
Username: user.Username,
Role: user.Role,
Enabled: user.Enabled,
Permissions: clonePermissions(user.Permissions),
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, permissions ...Permission) 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")
}
// A nil set means the caller named none at all, which keeps the meaning it
// had before grants existed: an account created by a script that only knows
// about roles gets what the user role granted then. An explicit empty set is
// a decision and stays empty, so the account really holds nothing.
if permissions == nil && role == RoleUser {
permissions = legacyUserPermissions()
}
if err := ValidatePermissions(permissions); err != nil {
return err
}
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,
Permissions: NormalizeStoredPermissions(permissions),
})
return s.saveLocked(db)
}
// Update applies the patch and returns the account as it was before and after,
// both read under the store lock, so a caller comparing the two sees exactly the
// change it made even while another update runs.
func (s *Store) Update(actor, username string, patch UserPatch) (previous, updated *User, err error) {
s.mutex.Lock()
defer s.mutex.Unlock()
db, err := s.loadLocked(true)
if err != nil {
return nil, nil, err
}
index := userIndex(db.Users, username)
if index < 0 {
return nil, nil, ErrUserNotFound
}
previous = cloneUser(&db.Users[index])
user := db.Users[index]
if patch.Role != nil && !IsValidRole(*patch.Role) {
return nil, nil, errors.New("invalid role")
}
// The patch is normalized before it is compared and stored, so a caller that
// still sends the split media grants does not look like a change once they
// resolve to the grants they now mean.
granted := user.Permissions
if patch.Permissions != nil {
if err := ValidatePermissions(*patch.Permissions); err != nil {
return nil, nil, err
}
granted = NormalizeStoredPermissions(*patch.Permissions)
// A request can only name grants this build knows, so the ones it does
// not (written by a newer release) are carried over instead of being
// dropped by an editor that never showed them.
for _, permission := range user.Permissions {
if !IsValidPermission(permission) && !Has(granted, permission) {
granted = append(granted, permission)
}
}
}
if actor == username && user.Role == RoleAdmin &&
((patch.Role != nil && *patch.Role != RoleAdmin) || (patch.Enabled != nil && !*patch.Enabled)) {
return nil, nil, ErrSelfModification
}
if user.SystemAccount &&
((patch.Role != nil && *patch.Role != RoleAdmin) || (patch.Enabled != nil && !*patch.Enabled)) {
return nil, nil, ErrSystemAccount
}
changed := false
// Only disabling the account invalidates its login. A role change does not:
// the principal is rebuilt from the account file on every request, and the
// caller refreshes the user's long-lived connections so they reconnect under
// the role's new grants. Bumping the token version for a role change would
// log the account out mid-session just because it was promoted or demoted.
loginInvalidated := 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
loginInvalidated = true
}
if patch.Permissions != nil && !permissionsEqual(user.Permissions, granted) {
user.Permissions = granted
changed = true
}
if !changed {
return previous, cloneUser(&user), nil
}
db.Users[index] = user
if enabledAdminCount(db.Users) == 0 {
return nil, nil, ErrLastAdmin
}
// Permission and role updates keep the login valid: the principal is rebuilt
// from the store on every request, so new grants apply immediately and
// revoked ones are enforced by dropping connections from the handler.
if loginInvalidated {
db.Users[index].TokenVersion++
}
if err = s.saveLocked(db); err != nil {
return nil, nil, err
}
return previous, 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
}
materializePermissions(db)
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 {
materializePermissions(&db)
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,
}},
}
materializePermissions(&db)
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 err := ValidateStoredPermissions(user.Permissions); err != nil {
return fmt.Errorf("account file contains invalid permissions for %q: %w", user.Username, err)
}
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
}
// materializePermissions replaces the grant shapes of earlier releases with an
// explicit set: an account that predates fine-grained permissions keeps exactly
// what the user role used to grant, and the split media grants are translated.
// After this the store never holds a nil set, so "no grants" and "never
// configured" can no longer be confused, and no caller has to special-case nil.
func materializePermissions(db *database) {
for index := range db.Users {
if db.Users[index].Permissions == nil {
db.Users[index].Permissions = legacyUserPermissions()
continue
}
db.Users[index].Permissions = NormalizeStoredPermissions(db.Users[index].Permissions)
}
}
func clonePermissions(permissions []Permission) []Permission {
return append([]Permission{}, permissions...)
}
func permissionsEqual(a, b []Permission) bool {
if (a == nil) != (b == nil) {
return false
}
if len(a) != len(b) {
return false
}
// The stored order carries no meaning, so a reordering must not look like
// a change worth writing back.
seen := make(map[Permission]struct{}, len(a))
for _, permission := range a {
seen[permission] = struct{}{}
}
for _, permission := range b {
if _, exists := seen[permission]; !exists {
return false
}
}
return true
}
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
}
}

212
server/authn/store_test.go Normal file
View File

@@ -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)
}
}

119
server/common/kvm_vision.go
View File

@@ -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() {
@@ -32,55 +35,58 @@ func GetKvmVision() *KvmVision {
return kvmVision
}
func (k *KvmVision) ReadMjpeg(width uint16, height uint16, quality uint16) (data []byte, result int) {
var (
kvmData *C.uint8_t
dataSize C.uint32_t
)
result = int(C.kvmv_read_img(
C.uint16_t(width),
C.uint16_t(height),
C.uint8_t(0),
C.uint16_t(quality),
&kvmData,
&dataSize,
))
if result < 0 {
log.Errorf("failed to read kvm image: %v", result)
return
}
defer C.free_kvmv_data(&kvmData)
data = C.GoBytes(unsafe.Pointer(kvmData), C.int(dataSize))
return
func (k *KvmVision) ReadMjpeg(width uint16, height uint16, quality uint16) ([]byte, int) {
frame := k.AcquireMjpeg(width, height, quality, uint16(GetScreen().FPS))
defer frame.Release()
return frame.Data, frame.Result
}
func (k *KvmVision) ReadH264(width uint16, height uint16, bitRate uint16) (data []byte, result int) {
var (
kvmData *C.uint8_t
dataSize C.uint32_t
)
func (k *KvmVision) AcquireMjpeg(width, height, quality, fps uint16) *VideoFrame {
return k.acquireFrame(width, height, quality, fps, 0)
}
result = int(C.kvmv_read_img(
C.uint16_t(width),
C.uint16_t(height),
C.uint8_t(1),
C.uint16_t(bitRate),
&kvmData,
&dataSize,
))
if result < 0 {
log.Errorf("failed to read kvm image: %v", result)
return
func (k *KvmVision) AcquireH264(width, height, bitRate, fps uint16) *VideoFrame {
return k.acquireFrame(width, height, bitRate, fps, 1)
}
func (k *KvmVision) acquireFrame(width, height, quality, fps uint16, codec uint8) *VideoFrame {
k.mutex.RLock()
defer k.mutex.RUnlock()
if k.closed {
return NewVideoFrame(nil, -1, 0, nil)
}
defer C.free_kvmv_data(&kvmData)
var frame C.kvmv_frame_t
result := int(C.kvmv_read_img(C.uint16_t(width), C.uint16_t(height),
C.uint8_t(codec), C.uint16_t(quality), C.uint16_t(fps), &frame))
if frame.data == nil {
return NewVideoFrame(nil, result, int64(frame.timestamp), nil)
}
data := C.GoBytes(unsafe.Pointer(frame.data), C.int(frame.size))
return NewVideoFrame(data, result, int64(frame.timestamp), func() {
k.mutex.RLock()
defer k.mutex.RUnlock()
C.kvmv_release_frame(&frame)
})
}
data = C.GoBytes(unsafe.Pointer(kvmData), C.int(dataSize))
return
func (k *KvmVision) StopH264() { k.stopStream(1) }
func (k *KvmVision) StopMjpeg() { k.stopStream(0) }
func (k *KvmVision) stopStream(codec uint8) {
k.mutex.RLock()
defer k.mutex.RUnlock()
if !k.closed {
C.kvmv_stop_stream(C.uint8_t(codec))
}
}
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 +101,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...")
}

47
server/common/screen.go
View File

@@ -1,10 +1,13 @@
package common
import "sync"
import (
"os"
"strconv"
"strings"
"sync"
)
type Screen struct {
Width uint16
Height uint16
FPS int
Quality uint16
BitRate uint16
@@ -16,15 +19,6 @@ var (
screenOnce sync.Once
)
// ResolutionMap height to width
var ResolutionMap = map[uint16]uint16{
1080: 1920,
720: 1280,
600: 800,
480: 640,
0: 0,
}
var QualityMap = map[uint16]bool{
100: true,
80: true,
@@ -42,8 +36,6 @@ var BitRateMap = map[uint16]bool{
func GetScreen() *Screen {
screenOnce.Do(func() {
screen = &Screen{
Width: 0,
Height: 0,
Quality: 80,
FPS: 30,
BitRate: 3000,
@@ -56,13 +48,6 @@ func GetScreen() *Screen {
func SetScreen(key string, value int) {
switch key {
case "resolution":
height := uint16(value)
if width, ok := ResolutionMap[height]; ok {
screen.Width = width
screen.Height = height
}
case "quality":
if value > 100 {
screen.BitRate = uint16(value)
@@ -79,11 +64,6 @@ func SetScreen(key string, value int) {
}
func CheckScreen() {
if _, ok := ResolutionMap[screen.Height]; !ok {
screen.Width = 1920
screen.Height = 1080
}
if _, ok := QualityMap[screen.Quality]; !ok {
screen.Quality = 80
}
@@ -93,6 +73,21 @@ func CheckScreen() {
}
}
func InputSize() (uint16, uint16) {
read := func(path string) uint16 {
data, err := os.ReadFile(path)
if err != nil {
return 0
}
value, err := strconv.ParseUint(strings.TrimSpace(string(data)), 10, 16)
if err != nil {
return 0
}
return uint16(value)
}
return read("/kvmapp/kvm/width"), read("/kvmapp/kvm/height")
}
func validateFPS(fps int) int {
if fps > 60 {
return 60

26
server/common/video_frame.go Normal file
View File

@@ -0,0 +1,26 @@
package common
import "sync"
type VideoFrame struct {
Data []byte
Result int
Timestamp int64
release func()
once sync.Once
}
func NewVideoFrame(data []byte, result int, timestamp int64, release func()) *VideoFrame {
return &VideoFrame{Data: data, Result: result, Timestamp: timestamp, release: release}
}
func (f *VideoFrame) Release() {
if f == nil {
return
}
f.once.Do(func() {
if f.release != nil {
f.release()
}
})
}

1
server/config/default.go
View File

@@ -2,6 +2,7 @@ package config
var defaultConfig = &Config{
Proto: "http",
Host: "",
Port: Port{
Http: 80,
Https: 443,

7
server/config/jwt.go
View File

@@ -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)

61
server/config/picoclaw_internal.go Normal file
View File

@@ -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
}

1
server/config/types.go
View File

@@ -2,6 +2,7 @@ package config
type Config struct {
Proto string `yaml:"proto"`
Host string `yaml:"host"`
Port Port `yaml:"port"`
Cert Cert `yaml:"cert"`
Logger Logger `yaml:"logger"`

BIN
server/dl_lib/libkvm.so
View File

Binary file not shown.

BIN
server/dl_lib/libkvm_mmf.so
View File

Binary file not shown.

14
server/go.mod
View File

@@ -1,17 +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/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
@@ -19,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
)
@@ -45,7 +49,6 @@ 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.4 // indirect
github.com/pion/mdns/v2 v2.0.7 // indirect
github.com/pion/randutil v0.1.0 // indirect
@@ -60,6 +63,8 @@ require (
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
@@ -68,12 +73,13 @@ require (
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
github.com/ugorji/go/codec v1.2.12 // 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

26
server/go.sum
View File

@@ -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=
@@ -119,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=
@@ -154,6 +162,8 @@ github.com/unrolled/secure v1.15.0 h1:q7x+pdp8jAHnbzxu6UheP8fRlG/rwYTb8TPuQ3rn9O
github.com/unrolled/secure v1.15.0/go.mod h1:BmF5hyM6tXczk3MpQkFf1hpKSRqCyhqcbiQtiAF7+40=
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=
@@ -167,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=

91
server/include/kvm_vision.h
View File

@@ -1,71 +1,44 @@
#ifndef KVM_VISION_H_
#define KVM_VISION_H_
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#include <fcntl.h> /* low-level i/o */
#include <unistd.h>
#include <string.h>
#include <stdio.h>
#include <stdint.h>
#include <stdlib.h>
#include <pthread.h>
#include <time.h>
#define IMG_BUFFER_FULL -3
#define IMG_VENC_ERROR -2
#define IMG_NOT_EXIST -1
#define IMG_MJPEG_TYPE 0
#define IMG_H264_TYPE_SPS 1
#define IMG_H264_TYPE_PPS 2
#define IMG_H264_TYPE_IF 3
#define IMG_H264_TYPE_PF 4
#define IMG_BUFFER_FULL -3
#define IMG_VENC_ERROR -2
#define IMG_NOT_EXIST -1
#define IMG_MJPEG_TYPE 0
#define IMG_H264_TYPE_IF 3
#define IMG_H264_TYPE_PF 4
#define NORMAL_RES 0
#define NEW_RES 1
#define UNSUPPORT_RES 2
#define UNKNOWN_RES 3
#define ERROR_RES 4
typedef struct {
uint8_t *data;
uint32_t size;
uint64_t timestamp;
uint64_t token;
uint8_t codec;
} kvmv_frame_t;
void kvmv_init(uint8_t _debug_info_en);
void set_venc_auto_recyc(uint8_t _enable);
/**********************************************************************************
* @name kvmv_read_img
* @author Sipeed BuGu
* @date 2024/10/25
* @version R1.0
* @brief Acquire the encoded image with auto init
* @param _width @input: Output image width
* @param _height @input: Output image height
* @param _type @input: Encode type
* @param _qlty @input: MJPEG: (50-100) | H264: (500-10000)
* @param _pp_kvm_data @output: Encode data
* @param _p_kvmv_data_size @output: Encode data size
* @return
-7: HDMI INPUT RES ERROR
-6: Unsupported resolution, please modify it in the host settings.
-5: Retrieving image, please wait
-4: Modifying image resolution, please wait
-3: img buffer full
-2: VENC Error
-1: No images were acquired
0: Acquire MJPEG encoded images
1: Acquire H264 encoded images(SPS)[Deprecated]
2: Acquire H264 encoded images(PPS)[Deprecated]
3: Acquire H264 encoded images(I)
4: Acquire H264 encoded images(P)
5: IMG not changed
**********************************************************************************/
int kvmv_read_img(uint16_t _width, uint16_t _height, uint8_t _type, uint16_t _qlty, uint8_t** _pp_kvm_data, uint32_t* _p_kvmv_data_size);
int free_kvmv_data(uint8_t ** _pp_kvm_data);
void free_all_kvmv_data();
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);
void kvmv_init(uint8_t debug_info);
void kvmv_deinit(void);
// type: 0 = MJPEG, 1 = H.264. A zero width/height follows the input size.
// quality: MJPEG 50..100, H.264 500..10000 Kbps. fps: 1..60.
// Returns -7 input error, -6 unsupported size, -5 busy, -4 reconfiguring,
// -3 allocation failure, -2 encoder error, -1 no frame, 0 JPEG, 3 IDR,
// 4 P-frame, or 5 unchanged JPEG. Release every successful frame once.
int kvmv_read_img(uint16_t width, uint16_t height, uint8_t type,
uint16_t quality, uint16_t fps, kvmv_frame_t *frame);
// Frees the copied bytes and releases the encoder lease. Safe after shutdown.
void kvmv_release_frame(kvmv_frame_t *frame);
void kvmv_stop_stream(uint8_t type);
void set_h264_gop(uint8_t gop);
void set_frame_detact(uint8_t interval);
uint8_t kvmv_hdmi_control(uint8_t enable);
uint8_t kvmv_hdmi_signal_active(void);
#ifdef __cplusplus
}

82
server/main.go
View File

@@ -1,12 +1,10 @@
package main
import (
"fmt"
"log"
"net/http"
"os"
"os/signal"
"strings"
"strconv"
"syscall"
"time"
@@ -15,6 +13,8 @@ import (
"NanoKVM-Server/logger"
"NanoKVM-Server/middleware"
"NanoKVM-Server/router"
"NanoKVM-Server/service/storage/diskfs"
"NanoKVM-Server/service/vm"
"NanoKVM-Server/service/vm/jiggler"
"NanoKVM-Server/utils"
@@ -30,22 +30,31 @@ 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()
// A medium left mounted by a crash or a restart keeps its loop device
// busy; nothing can be mounted by this process yet, so whatever is there
// is stale.
diskfs.CleanupStale()
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT)
go func() {
@@ -69,46 +78,57 @@ 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() {
diskfs.CleanupStale()
common.GetKvmVision().Close()
}

262
server/middleware/jwt.go
View File

@@ -1,75 +1,273 @@
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
Permissions []authn.Permission
}
// Has reports whether the principal effectively holds the permission.
// Administrators always do.
func (p Principal) Has(permission authn.Permission) bool {
if p.Role == authn.RoleAdmin {
return true
}
return authn.Has(p.Permissions, permission)
}
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()
requestContext, cancel := context.WithCancel(c.Request.Context())
sessionHandle := newSessionHandle()
requestContext = WithSessionHandle(requestContext, sessionHandle)
c.Request = c.Request.WithContext(requestContext)
channel := SessionChannelForPath(c.Request.URL.Path)
unregister := activeSessions.register(
principal.Username,
cancel,
sessionHandle,
channel,
)
// The principal was resolved before this session could be found by a
// revocation, so a grant edit landing in between would miss it. Now that
// it is registered, any later edit drops it; re-reading the account picks
// up any earlier one. Only the long-lived channels are dropped by a grant
// edit, so a short request keeps the principal it was authorized with.
if channel != "" {
user, err := authn.DefaultStore.ValidateToken(principal.Username, token.TokenVersion)
if err != nil {
unregister()
cancel()
abortUnauthorized(c)
return
}
principal.Role = user.Role
principal.Permissions = authn.EffectivePermissions(user)
c.Set(principalContextKey, principal)
}
c.JSON(http.StatusUnauthorized, "unauthorized")
c.Abort()
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.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 {
abortForbidden(c)
return
}
c.Next()
}
}
// RequirePermission allows the request when the principal holds at least one
// of the listed permissions. Administrators implicitly hold every permission.
func RequirePermission(permissions ...authn.Permission) gin.HandlerFunc {
return func(c *gin.Context) {
principal, ok := CurrentPrincipal(c)
if !ok {
abortUnauthorized(c)
return
}
allowed := false
for _, permission := range permissions {
if principal.Has(permission) {
allowed = true
break
}
}
if !allowed {
abortForbidden(c)
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, Permissions: authn.PermissionIDs()}, 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,
Permissions: authn.EffectivePermissions(user),
}, token, true
}
return t.SignedString([]byte(conf.JWT.SecretKey))
func abortUnauthorized(c *gin.Context) {
c.JSON(http.StatusUnauthorized, "unauthorized")
c.Abort()
}
func abortForbidden(c *gin.Context) {
c.JSON(http.StatusForbidden, "forbidden")
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
}

230
server/middleware/jwt_test.go Normal file
View File

@@ -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, newSessionHandle(), "")
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
}
}

94
server/middleware/loopback_http.go Normal file
View File

@@ -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()
}

233
server/middleware/session.go Normal file
View File

@@ -0,0 +1,233 @@
package middleware
import (
"context"
"net"
"net/http"
"net/url"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/gorilla/websocket"
)
const SessionRevokedCloseCode = 4401
// SessionRefreshedCloseCode closes connections whose permissions changed while
// the underlying login is still valid. Clients are expected to reconnect and
// refresh their account state instead of returning to the login page.
const SessionRefreshedCloseCode = 4403
type sessionHandleKey struct{}
// Long-lived connection channels, used to drop only the connections affected
// by a permission change instead of every session of the user.
const (
SessionChannelConsole = "console" // /api/ws (input events, status pushes)
SessionChannelStream = "stream" // /api/stream/* (video signaling and frames)
SessionChannelTerminal = "terminal" // /api/vm/terminal
SessionChannelAi = "ai" // /api/picoclaw/gateway/ws
)
// SessionChannelForPath classifies long-lived endpoints; everything else
// returns an empty channel and is only affected by hard revocation.
func SessionChannelForPath(path string) string {
switch {
case path == "/api/ws":
return SessionChannelConsole
case strings.HasPrefix(path, "/api/stream/"):
return SessionChannelStream
case path == "/api/vm/terminal":
return SessionChannelTerminal
case path == "/api/picoclaw/gateway/ws":
return SessionChannelAi
default:
return ""
}
}
// sessionHandle lets a revocation pick the WebSocket close code before the
// request context is canceled.
type sessionHandle struct {
closeCode atomic.Int32
}
type sessionEntry struct {
cancel context.CancelFunc
handle *sessionHandle
channel string
}
type sessionRegistry struct {
mutex sync.Mutex
nextID atomic.Uint64
byUserID map[string]map[uint64]*sessionEntry
}
var activeSessions = &sessionRegistry{byUserID: make(map[string]map[uint64]*sessionEntry)}
func newSessionHandle() *sessionHandle {
handle := &sessionHandle{}
handle.closeCode.Store(SessionRevokedCloseCode)
return handle
}
// WithSessionHandle attaches the handle to the request context so
// WatchWebSocket can honor the close code chosen at revocation time.
func WithSessionHandle(ctx context.Context, handle *sessionHandle) context.Context {
return context.WithValue(ctx, sessionHandleKey{}, handle)
}
func (r *sessionRegistry) register(username string, cancel context.CancelFunc, handle *sessionHandle, channel string) func() {
id := r.nextID.Add(1)
r.mutex.Lock()
if r.byUserID[username] == nil {
r.byUserID[username] = make(map[uint64]*sessionEntry)
}
r.byUserID[username][id] = &sessionEntry{cancel: cancel, handle: handle, channel: channel}
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()
}
}
// RevokeUserSessions hard-drops every active session of the user. The login
// is expected to be invalid afterwards; connections close as unauthorized.
func RevokeUserSessions(username string) {
dropUserSessions(username, SessionRevokedCloseCode, nil)
}
// RefreshUserSessions drops the user's long-lived connections on the given
// channels while their login stays valid, so those clients reconnect under
// the updated permissions. Unrelated connections (e.g. the video stream when
// only console control was revoked) stay untouched.
func RefreshUserSessions(username string, channels ...string) {
dropUserSessions(username, SessionRefreshedCloseCode, channels)
}
func dropUserSessions(username string, closeCode int, channels []string) {
activeSessions.mutex.Lock()
sessions := activeSessions.byUserID[username]
if channels == nil {
delete(activeSessions.byUserID, username)
}
dropped := make([]*sessionEntry, 0, len(sessions))
for id, entry := range sessions {
if !channelMatches(entry.channel, channels) {
continue
}
dropped = append(dropped, entry)
if channels != nil {
delete(sessions, id)
}
}
if channels != nil && len(sessions) == 0 {
delete(activeSessions.byUserID, username)
}
activeSessions.mutex.Unlock()
for _, entry := range dropped {
entry.handle.closeCode.Store(int32(closeCode))
entry.cancel()
}
}
// channelMatches reports whether the entry is affected. A nil channel list
// means a hard revocation, which drops everything.
func channelMatches(channel string, channels []string) bool {
if channels == nil {
return true
}
for _, candidate := range channels {
if channel == candidate {
return true
}
}
return false
}
func WatchWebSocket(ctx context.Context, connection *websocket.Conn) func() {
stopped := make(chan struct{})
var stopOnce sync.Once
go func() {
select {
case <-ctx.Done():
closeCode := SessionRevokedCloseCode
reason := "session expired or revoked"
if handle, ok := ctx.Value(sessionHandleKey{}).(*sessionHandle); ok {
if code := int(handle.closeCode.Load()); code == SessionRefreshedCloseCode {
closeCode = code
reason = "permissions changed"
}
}
_ = connection.WriteControl(
websocket.CloseMessage,
websocket.FormatCloseMessage(closeCode, reason),
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"
}
}

10
server/proto/application.go
View File

@@ -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"`
}

60
server/proto/auth.go
View File

@@ -5,19 +5,65 @@ type LoginReq struct {
Password string `validate:"required"`
}
type LoginRsp struct {
Token string `json:"token"`
}
type GetAccountRsp struct {
Username string `json:"username"`
Username string `json:"username"`
Role string `json:"role"`
Permissions []string `json:"permissions"`
}
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"`
Permissions []string `json:"permissions"`
SystemAccount bool `json:"systemAccount,omitempty"`
}
type ListPermissionsRsp struct {
Permissions []PermissionInfo `json:"permissions"`
}
// PermissionInfo describes one grantable permission: the group it belongs to,
// how far it reaches, and the grants it implies. The client renders the editor
// from this catalog instead of keeping its own copy of the model.
type PermissionInfo struct {
ID string `json:"id"`
Group string `json:"group"`
Risk string `json:"risk"`
Implies []string `json:"implies,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"`
Permissions []string `json:"permissions"`
}
type UpdateUserReq struct {
Role *string `json:"role"`
Enabled *bool `json:"enabled"`
Permissions *[]string `json:"permissions"`
// RotateMcpKey asks to regenerate the device-wide MCP API key when this
// change takes the mcp grant away. The administrator decides: rotating
// disconnects every MCP client, keeping it leaves a copied key working.
RotateMcpKey bool `json:"rotateMcpKey"`
}
// UpdateUserRsp says whether the change regenerated the MCP API key.
type UpdateUserRsp struct {
McpKeyRotated bool `json:"mcpKeyRotated"`
}

7
server/proto/download.go
View File

@@ -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"`
}
@@ -8,4 +13,6 @@ type StatusImageRsp struct {
Status string `json:"status"`
File string `json:"file"`
Percentage string `json:"percentage"`
Loaded int64 `json:"loaded"` // bytes transferred so far
Total int64 `json:"total"` // expected bytes, 0 when unknown
}

8
server/proto/hid.go
View File

@@ -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
}

12
server/proto/mcp.go Normal file
View File

@@ -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"`
}

100
server/proto/media.go Normal file
View File

@@ -0,0 +1,100 @@
package proto
import "time"
// Virtual media wire types. A medium is named by a type plus a path relative
// to the media directory: the server resolves the id itself, so a request
// never carries an absolute path it could be talked into deleting.
const (
MediaTypeImage = "image"
MediaTypePartition = "partition"
)
type MediaItem struct {
Type string `json:"type"`
Rel string `json:"rel"`
Name string `json:"name"`
Size uint64 `json:"size"`
FS string `json:"fs"`
Browsable bool `json:"browsable"`
Attached bool `json:"attached"`
Modified time.Time `json:"modifiedAt"`
}
type MediaCaps struct {
Loop bool `json:"loop"`
}
type GetMediaRsp struct {
Media []MediaItem `json:"media"`
Caps MediaCaps `json:"capabilities"`
}
type MediaStateRsp struct {
State string `json:"state"` // none | image | partition | unsupported
Type string `json:"type"` // type of the attached medium
Rel string `json:"rel"` // rel of the attached medium, when it is an image
HidOnly bool `json:"hidOnly"` // the gadget has no mass storage at all
Open []string `json:"open"` // media the file manager currently holds open
Cdrom bool `json:"cdrom"` // the attached medium is served as a CD-ROM
// LocalWritable is false while /data is mounted read-only, which is what
// the target machine owning the partition does. Every write would fail
// with EROFS, so the UI disables them instead of asking.
LocalWritable bool `json:"localWritable"`
}
type MediaRefReq struct {
Type string `json:"type" validate:"omitempty,oneof=image partition"`
Rel string `json:"rel"`
}
type MountMediaReq struct {
Type string `json:"type" validate:"omitempty,oneof=image partition"`
Rel string `json:"rel"`
Cdrom bool `json:"cdrom"`
// Force re-enumerates the gadget to take the medium back from a target
// machine that is holding it. It costs the target machine its unflushed
// writes, so the UI asks before setting it.
Force bool `json:"force"`
}
type EjectMediaReq struct {
Force bool `json:"force"`
}
type MediaStatusRsp struct {
Status string `json:"status"`
Name string `json:"name"`
Percentage string `json:"percentage"`
Loaded int64 `json:"loaded"` // bytes transferred so far
Total int64 `json:"total"` // expected bytes, 0 when unknown
Message string `json:"message"`
}
type MediaFile struct {
Name string `json:"name"`
Size int64 `json:"size"`
IsDir bool `json:"isDir"`
Modified time.Time `json:"modifiedAt"`
}
type GetMediaFilesRsp struct {
Path string `json:"path"`
Entries []MediaFile `json:"entries"`
Free uint64 `json:"free"`
Total uint64 `json:"total"`
// Writing is true while the medium is seeing block level writes: a zero
// length entry in that state is a transfer in progress, not an empty file.
Writing bool `json:"writing"`
}
type MediaPathReq struct {
Type string `json:"type" validate:"omitempty,oneof=image partition"`
Rel string `json:"rel"`
Path string `json:"path" validate:"required"`
// ExistsOK turns "the directory is already there" into success. An upload
// of a whole tree recreates folders that may already exist on the medium,
// and stopping at the first one would leave the tree half copied.
ExistsOK bool `json:"existsOk"`
}

24
server/proto/network.go
View File

@@ -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"`
}

2
server/proto/request.go
View File

@@ -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

67
server/proto/vm.go
View File

@@ -30,8 +30,8 @@ type GetGpioRsp struct {
}
type SetScreenReq struct {
Type string `validate:"required"` // resolution / fps / quality
Value int `validate:"number"` // value
Type string `validate:"required,oneof=type fps quality gop"`
Value int `validate:"number"` // value
}
type GetScriptsRsp struct {
@@ -72,6 +72,10 @@ type GetVirtualDeviceRsp struct {
type UpdateVirtualDeviceReq struct {
Device string `validate:"required"`
// Enable turns the device on or off instead of toggling it. A caller that
// says "enable" must not switch a running device off because it happened to
// be already on.
Enable *bool `json:"enable"`
}
type UpdateVirtualDeviceRsp struct {
@@ -98,7 +102,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 +156,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"`
}

6
server/router/application.go
View File

@@ -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.RequirePermission(authn.PermUpdate))
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
}

12
server/router/auth.go
View File

@@ -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,15 @@ 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/permissions", service.ListPermissions)
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)
}

163
server/router/control.go Normal file
View File

@@ -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.RequirePermission(authn.PermAi),
)
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
}
}

24
server/router/download.go
View File

@@ -1,18 +1,26 @@
package router
import (
"NanoKVM-Server/service/download"
"github.com/gin-gonic/gin"
"NanoKVM-Server/authn"
"NanoKVM-Server/middleware"
"NanoKVM-Server/service/download"
"github.com/gin-gonic/gin"
)
func downloadRouter(r *gin.Engine) {
service := download.NewService()
api := r.Group("/api").Use(middleware.CheckToken())
// A signed URL that ends up on the data partition changes what this device
// keeps, so it follows the library write grant.
write := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermLibraryWrite))
// Progress and availability are reads: a user who may attach a medium can
// take /data away from the downloader, so they need to see whether one is
// running, and reading the library is implied by every media grant.
read := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermLibraryRead))
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
write.POST("/download/image", service.DownloadImage) // download image
write.POST("/download/image/cancel", service.CancelDownloadImage) // cancel image download
read.GET("/download/image/status", service.StatusImage) // download image
read.GET("/download/image/enabled", service.ImageEnabled) // download image
write.POST("/download/file", service.DownloadImageFile) // upload image file
}

6
server/router/extensions.go
View File

@@ -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.RequirePermission(authn.PermTailscale),
)
ts := tailscale.NewService()

33
server/router/hid.go
View File

@@ -3,24 +3,37 @@ 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())
view := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermConsoleView))
control := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermConsoleControl))
system := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermDevice))
localAPI := r.Group("/api/internal").Use(middleware.CheckLoopbackInternalToken())
api.POST("/hid/paste", service.Paste) // paste
control.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
view.GET("/hid/shortcuts", service.GetShortcuts) // get shortcuts
view.GET("/hid/shortcut/leader-key", service.GetLeaderKey) // get shortcut leader key
api.GET("/hid/shortcut/leader-key", service.GetLeaderKey) // set shortcut leader key
api.POST("/hid/shortcut/leader-key", service.SetLeaderKey) // set shortcut leader key
view.GET("/hid/mode", service.GetHidMode) // get hid mode
view.GET("/hid/leds", service.GetKeyboardLedStatus)
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
system.POST("/hid/mode", service.SetHidMode) // set hid mode
system.POST("/hid/reset", service.ResetHid) // reset hid
system.POST("/hid/shortcut", service.AddShortcut)
system.DELETE("/hid/shortcut", service.DeleteShortcut)
system.POST("/hid/shortcut/leader-key", service.SetLeaderKey)
localAPI.POST("/usb/recover", service.RecoverUSB)
}

41
server/router/mcp.go Normal file
View File

@@ -0,0 +1,41 @@
package router
import (
"net/http"
"NanoKVM-Server/authn"
"NanoKVM-Server/middleware"
"NanoKVM-Server/service/auth"
"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")
},
)
auth.APIKeyRotator = mcpservice.RotateAPIKey
management := r.Group("/api/mcp").Use(
middleware.CheckToken(),
middleware.RequirePermission(authn.PermMcp),
)
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))
}

24
server/router/network.go
View File

@@ -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,21 @@ 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())
power := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermPower))
network := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermNetwork))
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
power.POST("/network/wol", service.WakeOnLAN) // wake on lan
power.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
power.DELETE("/network/wol/mac", service.DeleteMac) // delete mac
power.POST("/network/wol/mac/name", service.SetMacName) // set mac name
network.GET("/network/wifi", service.GetWifi) // get Wi-Fi information
network.POST("/network/wifi/connect", service.ConnectWifi) // connect Wi-Fi
network.POST("/network/wifi/disconnect", service.DisconnectWifi) // disconnect Wi-Fi
network.GET("/network/dns", service.GetDNS) // get DNS configuration
network.POST("/network/dns", service.SetDNS) // set DNS configuration
}

67
server/router/picoclaw.go Normal file
View File

@@ -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.RequirePermission(authn.PermAi),
)
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)
}

21
server/router/router.go
View File

@@ -5,6 +5,12 @@ import (
"os"
"path/filepath"
"NanoKVM-Server/service/auth"
"NanoKVM-Server/service/controlmode"
"NanoKVM-Server/service/picoclaw"
"NanoKVM-Server/service/ws"
"NanoKVM-Server/webcache"
"github.com/gin-gonic/contrib/static"
"github.com/gin-gonic/gin"
log "github.com/sirupsen/logrus"
@@ -25,10 +31,16 @@ func web(r *gin.Engine) {
execDir := filepath.Dir(execPath)
webPath := fmt.Sprintf("%s/web", execDir)
r.Use(webcache.Headers(webPath))
r.Use(static.Serve("/", static.LocalFile(webPath, true)))
}
func server(r *gin.Engine) {
control := controlmode.GetManager()
picoclawService := picoclaw.NewService(control)
auth.SessionNotifier = ws.GetManager().NotifyUser
authRouter(r)
applicationRouter(r)
vmRouter(r)
@@ -36,7 +48,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
}

47
server/router/storage.go
View File

@@ -1,19 +1,50 @@
package router
import (
"github.com/gin-gonic/gin"
"NanoKVM-Server/authn"
"NanoKVM-Server/middleware"
"NanoKVM-Server/service/storage"
"github.com/gin-gonic/gin"
)
func storageRouter(r *gin.Engine) {
service := storage.NewService()
api := r.Group("/api").Use(middleware.CheckToken())
// Reading the library is the one grant the other media grants imply, so it
// alone gates every read: it is what makes the storage page reachable.
read := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermLibraryRead))
// Attaching a medium is what hands it to the target machine; changing the
// library is what changes what this device keeps.
attach := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermMediumAttach))
write := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermLibraryWrite))
// The file handlers serve an image and the shared partition through the same
// path: the first is library content, the second is the surface the target
// machine reads. Which grant applies follows the medium in the request, so
// the route admits either and the handler narrows the pair.
files := r.Group("/api").Use(
middleware.CheckToken(),
middleware.RequirePermission(authn.PermLibraryWrite, authn.PermMediumAttach),
)
api.GET("/storage/image", service.GetImages) // get image list
api.GET("/storage/image/mounted", service.GetMountedImage) // get mounted image
api.POST("/storage/image/mount", service.MountImage) // mount image
api.GET("/storage/cdrom", service.GetCdRom) // get CD-ROM flag
api.POST("/storage/image/delete", service.DeleteImage) // delete image
// Virtual media: the disk images the emulated USB disk exposes, the files
// inside them, and the shared partition the target machine sees.
read.GET("/storage/media", service.GetMedia) // list media
read.GET("/storage/media/state", service.GetMediaState) // what the target machine sees
read.GET("/storage/media/status", service.GetMediaStatus) // transfer progress
read.GET("/storage/media/download", service.DownloadMedia) // download a whole image
read.GET("/storage/media/files", service.ListMediaFiles) // list files inside a medium
read.GET("/storage/media/files/download", service.DownloadMediaFile)
attach.POST("/storage/media/mount", service.MountMedia) // attach a medium to the target machine
attach.POST("/storage/media/eject", service.EjectMedia) // release the medium
write.POST("/storage/media/delete", service.DeleteMedia) // delete a medium
files.POST("/storage/media/files/upload", service.UploadMediaFile)
files.POST("/storage/media/files/mkdir", service.MkdirMediaFile)
files.POST("/storage/media/files/delete", service.DeleteMediaFile)
// The pre-2.6 image API, kept for scripts written against it.
read.GET("/storage/image", service.GetImages) // get image list
read.GET("/storage/image/mounted", service.GetMountedImage) // get mounted image
read.GET("/storage/cdrom", service.GetCdRom) // get CD-ROM flag
attach.POST("/storage/image/mount", service.MountImage) // mount image
write.POST("/storage/image/delete", service.DeleteImage) // delete image
}

3
server/router/stream.go
View File

@@ -1,6 +1,7 @@
package router
import (
"NanoKVM-Server/authn"
"NanoKVM-Server/middleware"
"NanoKVM-Server/service/stream/direct"
"NanoKVM-Server/service/stream/mjpeg"
@@ -10,7 +11,7 @@ import (
)
func streamRouter(r *gin.Engine) {
api := r.Group("/api").Use(middleware.CheckToken())
api := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermConsoleView))
api.GET("/stream/mjpeg", mjpeg.Connect) // mjpeg stream
api.POST("/stream/mjpeg/detect", mjpeg.UpdateFrameDetect) // update frame detect

115
server/router/vm.go
View File

@@ -3,6 +3,7 @@ package router
import (
"github.com/gin-gonic/gin"
"NanoKVM-Server/authn"
"NanoKVM-Server/middleware"
"NanoKVM-Server/service/vm"
)
@@ -10,63 +11,95 @@ import (
func vmRouter(r *gin.Engine) {
service := vm.NewService()
api := r.Group("/api").Use(middleware.CheckToken())
use := func(permission authn.Permission) gin.IRoutes {
return r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(permission))
}
// The app shell reads the site title on every page, including the pages an
// account without console access can open, so it asks for no feature grant.
base := r.Group("/api").Use(middleware.CheckToken())
view := use(authn.PermConsoleView)
control := use(authn.PermConsoleControl)
power := use(authn.PermPower)
terminal := use(authn.PermTerminal)
device := use(authn.PermDevice)
network := use(authn.PermNetwork)
api.GET("/vm/info", service.GetInfo) // get device information
api.GET("/vm/hardware", service.GetHardware) // get hardware version
view.GET("/vm/info", service.GetInfo) // get device information
view.GET("/vm/hardware", service.GetHardware) // get hardware version
api.POST("/vm/gpio", service.SetGpio) // update gpio
api.GET("/vm/gpio", service.GetGpio) // get gpio
api.POST("/vm/screen", service.SetScreen) // update screen
power.POST("/vm/gpio", service.SetGpio) // update gpio
power.GET("/vm/gpio", service.GetGpio) // get gpio
api.GET("/vm/terminal", service.Terminal) // web terminal
// Video encoding and capture recovery are view operations: a user who may
// only watch still has to be able to pick a quality their link can carry,
// and every account holds console.view. Mapping pointer motion onto the
// target screen stays console.control.
view.POST("/vm/screen", service.SetScreen) // update screen
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
view.GET("/vm/input-region", service.GetInputRegion)
control.POST("/vm/input-region", service.SetInputRegion)
view.GET("/vm/input-resolution", service.GetInputResolution)
api.GET("/vm/device/virtual", service.GetVirtualDevice) // get virtual device
api.POST("/vm/device/virtual", service.UpdateVirtualDevice) // update virtual device
terminal.GET("/vm/terminal", service.Terminal) // web terminal
api.GET("/vm/memory/limit", service.GetMemoryLimit) // get memory limit
api.POST("/vm/memory/limit", service.SetMemoryLimit) // set memory limit
terminal.GET("/vm/script", service.GetScripts) // get script
terminal.POST("/vm/script/upload", service.UploadScript) // upload script
terminal.POST("/vm/script/run", service.RunScript) // run script
terminal.DELETE("/vm/script", service.DeleteScript) // delete script
api.GET("/vm/oled", service.GetOLED) // get OLED configuration
api.POST("/vm/oled", service.SetOLED) // set OLED configuration
// The emulated USB devices are device settings, not media or network ones:
// the virtual disk hands the raw data partition to the target machine and the
// RNDIS adapter hands it a network interface, so neither belongs to the
// media library the disk serves or to the network settings of this side.
device.GET("/vm/device/virtual", service.GetVirtualDevice) // get virtual device
device.POST("/vm/device/virtual", service.UpdateVirtualDevice) // update virtual device
device.GET("/vm/memory/limit", service.GetMemoryLimit) // get memory limit
device.POST("/vm/memory/limit", service.SetMemoryLimit) // set memory limit
device.GET("/vm/oled", service.GetOLED) // get OLED configuration
device.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
//
// Toggling the HDMI capture engine is a device setting, but resetting it is
// capture recovery: a watcher whose screen went black needs it to see
// anything at all, the same way it needs to pick a video mode and a quality.
// Enabling, disabling and the idle timeout stay with the device grant, since
// they change how the device behaves for everyone rather than recover a
// broken picture.
view.GET("/vm/hdmi", service.GetHdmiState) // get HDMI state
view.POST("/vm/hdmi/reset", service.ResetHdmi) // reset hdmi
device.POST("/vm/hdmi/enable", service.EnableHdmi) // enable hdmi
device.POST("/vm/hdmi/disable", service.DisableHdmi) // disable hdmi
device.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
device.GET("/vm/ssh", service.GetSSHState) // get SSH state
device.POST("/vm/ssh/enable", service.EnableSSH) // enable SSH
device.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
device.GET("/vm/swap", service.GetSwap) // get swap file size
device.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
device.GET("/vm/mouse-jiggler", service.GetMouseJiggler) // get mouse jiggler
device.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
view.GET("/vm/hostname", service.GetHostname) // Get Hostname
device.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
base.GET("/vm/web-title", service.GetWebTitle) // Get web title
device.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
device.GET("/vm/mdns", service.GetMdnsState) // get mDNS state
device.POST("/vm/mdns/enable", service.EnableMdns) // enable mDNS
device.POST("/vm/mdns/disable", service.DisableMdns) // disable mDNS
api.POST("/vm/tls", service.SetTls) // enable/disable TLS
network.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
terminal.GET("/vm/autostart", service.GetAutostart) // get autostart list
terminal.GET("/vm/autostart/:name", service.GetAutostartContent) // get autostart content
terminal.DELETE("/vm/autostart/:name", service.DeleteAutostart) // delete autostart script
terminal.POST("/vm/autostart/:name", service.UploadAutostart) // upload autostart script
api.POST("/vm/system/reboot", service.Reboot) // reboot system
device.POST("/vm/system/reboot", service.Reboot) // reboot system
}

3
server/router/ws.go
View File

@@ -3,13 +3,14 @@ package router
import (
"github.com/gin-gonic/gin"
"NanoKVM-Server/authn"
"NanoKVM-Server/middleware"
"NanoKVM-Server/service/ws"
)
func wsRouter(r *gin.Engine) {
service := ws.NewService()
api := r.Group("/api").Use(middleware.CheckToken())
api := r.Group("/api").Use(middleware.CheckToken(), middleware.RequirePermission(authn.PermConsoleView))
api.GET("/ws", service.Connect)
}

203
server/service/application/archive.go Normal file
View File

@@ -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
}

90
server/service/application/archive_test.go Normal file
View File

@@ -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)
}
}

9
server/service/application/install.go
View File

@@ -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
}

4
server/service/application/progress_writer.go
View File

@@ -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
)

8
server/service/application/service.go
View File

@@ -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{}

103
server/service/application/storage.go Normal file
View File

@@ -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
}

46
server/service/application/storage_test.go Normal file
View File

@@ -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")
}
}

90
server/service/application/update.go
View File

@@ -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 {

169
server/service/application/update_offline.go
View File

@@ -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
}

212
server/service/application/update_server.go Normal file
View File

@@ -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
}

138
server/service/application/version.go
View File

@@ -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
}

46
server/service/application/version_test.go Normal file
View File

@@ -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")
}
}

69
server/service/application/workspace.go Normal file
View File

@@ -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
}

49
server/service/application/workspace_test.go Normal file
View File

@@ -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)
}
}

113
server/service/auth/account.go
View File

@@ -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),
}
}

105
server/service/auth/login.go
View File

@@ -1,11 +1,15 @@
package auth
import (
"net/http"
"strings"
"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"
@@ -15,12 +19,9 @@ 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
}
@@ -30,63 +31,99 @@ func (s *Service) Login(c *gin.Context) {
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)
if locked, code, msg := RecordLoginFailure(clientIP); locked {
rsp.ErrRsp(c, code, msg)
return
}
rsp.ErrRsp(c, -2, "invalid username or password")
rsp.ErrRsp(c, -3, "authentication unavailable")
return
}
if !ok {
s.loginFailed(c, clientIP, &rsp)
return
}
ClearLoginAttempt(clientIP)
token, err := middleware.GenerateJWT(req.Username)
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),
Permissions: permissionStrings(principal.Permissions),
})
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)
}

134
server/service/auth/password.go
View File

@@ -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()
}

307
server/service/auth/service_test.go Normal file
View File

@@ -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
}
}

307
server/service/auth/users.go Normal file
View File

@@ -0,0 +1,307 @@
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")
// SessionNotifier pushes an account event to a user's live connections. It is
// wired to the websocket manager during router setup; kept as a hook so this
// package does not depend on the cgo-based HID stack.
var SessionNotifier func(username, event, data string)
// APIKeyRotator replaces the device-wide MCP API key. It is wired by the MCP
// router for the same reason as SessionNotifier.
var APIKeyRotator func() error
// rotateAPIKeyIfLost regenerates the MCP API key when the account no longer
// reaches it and the administrator asked for it. The key outlives the web
// session, so a key the account copied keeps working until it is replaced;
// replacing it disconnects every MCP client, so the account editor warns and
// leaves the choice to the administrator. A failed rotation is reported so the
// administrator learns that the old key still works.
func rotateAPIKeyIfLost(previous, current []authn.Permission, requested bool) (bool, error) {
if !authn.Has(previous, authn.PermMcp) || authn.Has(current, authn.PermMcp) {
return false, nil
}
if !requested {
log.Warnf("mcp grant revoked; the MCP API key was kept at the administrator's request")
return false, nil
}
if APIKeyRotator == nil {
return false, nil
}
if err := APIKeyRotator(); err != nil {
log.Errorf("rotate MCP API key after revoking the mcp grant: %s", err)
return false, errAPIKeyNotRotated
}
log.Infof("MCP API key rotated after the mcp grant was revoked")
return true, nil
}
var errAPIKeyNotRotated = errors.New("the change was saved, but the MCP API key could not be regenerated; regenerate it from the MCP settings")
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,
Permissions: permissionStrings(user.Permissions),
SystemAccount: user.SystemAccount,
})
}
rsp.OkRspWithData(c, &proto.ListUsersRsp{Users: result})
}
func (s *Service) ListPermissions(c *gin.Context) {
var rsp proto.Response
catalog := authn.Catalog()
permissions := make([]proto.PermissionInfo, 0, len(catalog))
for _, descriptor := range catalog {
permissions = append(permissions, proto.PermissionInfo{
ID: string(descriptor.Permission),
Group: string(descriptor.Group),
Risk: string(descriptor.Risk),
Implies: permissionStrings(descriptor.Implies),
})
}
rsp.OkRspWithData(c, &proto.ListPermissionsRsp{Permissions: permissions})
}
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
}
permissions, err := parsePermissions(req.Permissions)
if err != nil {
rsp.ErrRsp(c, -3, err.Error())
return
}
if err = authn.DefaultStore.Create(req.Username, password, authn.Role(req.Role), permissions...); err != nil {
rsp.ErrRsp(c, -4, 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 && req.Permissions == 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
}
if req.Permissions != nil {
permissions, err := parsePermissions(*req.Permissions)
if err != nil {
rsp.ErrRsp(c, -2, err.Error())
return
}
patch.Permissions = &permissions
}
username := c.Param("username")
// The store hands back the account as it was before and after this patch,
// read under one lock, so a role change is handled exactly like editing the
// permission set: the role resolves to its implicit grants and the
// difference drives the refresh.
previous, updated, err := authn.DefaultStore.Update(principal.Username, username, patch)
if err != nil {
rsp.ErrRsp(c, -2, err.Error())
return
}
// A disabled account reaches nothing, whatever it stores.
previousPermissions := enabledPermissions(previous)
currentPermissions := enabledPermissions(updated)
rotated, rotateErr := rotateAPIKeyIfLost(previousPermissions, currentPermissions, req.RotateMcpKey)
if updated.TokenVersion != previous.TokenVersion {
// Disabling the account is the only change that invalidates the login.
middleware.RevokeUserSessions(username)
} else {
// Every other change keeps the login valid: drop only the long-lived
// connections whose in-memory state depends on what changed, and let the
// frontend refresh its account state in place. Revoked grants have to
// reconnect to stop using the feature, and granted ones have to reconnect
// to pick up capabilities cached at connect time (the console socket
// remembers whether it is read-only). Unrelated connections stay
// untouched. A save that changes nothing stays silent.
changed := permissionsChanged(previousPermissions, currentPermissions)
roleChanged := updated.Role != previous.Role
if (roleChanged || len(changed) > 0) && SessionNotifier != nil {
// The role itself is rendered too (user management, the role label),
// so the frontend refreshes even when the grants happen to match.
// The notifier writes to every socket of the user, each with its own
// write deadline; one stuck connection must not hold this request.
go SessionNotifier(username, "auth", "refresh")
}
if channels := channelsForPermissions(changed); len(channels) > 0 {
middleware.RefreshUserSessions(username, channels...)
}
}
if rotateErr != nil {
rsp.ErrRsp(c, -3, rotateErr.Error())
return
}
rsp.OkRspWithData(c, &proto.UpdateUserRsp{McpKeyRotated: rotated})
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")
previous, _ := authn.DefaultStore.Get(username)
if err := authn.DefaultStore.Delete(principal.Username, username); err != nil {
rsp.ErrRsp(c, -1, err.Error())
return
}
middleware.RevokeUserSessions(username)
// DELETE carries no body, so the choice travels in the query string.
rotated, err := rotateAPIKeyIfLost(enabledPermissions(previous), nil, c.Query("rotateMcpKey") == "true")
if err != nil {
rsp.ErrRsp(c, -2, err.Error())
return
}
rsp.OkRspWithData(c, &proto.UpdateUserRsp{McpKeyRotated: rotated})
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 enabledPermissions(user *authn.User) []authn.Permission {
if user == nil || !user.Enabled {
return nil
}
return authn.EffectivePermissions(user)
}
// permissionsChanged returns the grants that were added or removed. Both
// directions matter: a revoked grant must stop reaching the feature, while a
// granted one must reconnect to pick up state cached per connection.
func permissionsChanged(oldPermissions, newPermissions []authn.Permission) []authn.Permission {
changed := make([]authn.Permission, 0, len(oldPermissions))
for _, old := range oldPermissions {
if !authn.Has(newPermissions, old) {
changed = append(changed, old)
}
}
for _, current := range newPermissions {
if !authn.Has(oldPermissions, current) {
changed = append(changed, current)
}
}
return changed
}
// channelsForPermissions maps permissions that changed to the long-lived
// connection channels that must reconnect to take effect. Permissions without
// connection state (library, network, ...) are enforced per-request and need no
// teardown.
func channelsForPermissions(permissions []authn.Permission) []string {
channels := make([]string, 0, 2)
for _, permission := range permissions {
switch permission {
case authn.PermConsoleView:
// Losing the console grant closes the video stream, and gaining it (an
// account promoted to administrator) keeps every console connection
// from running under the grants it cached at connect time.
channels = append(channels, middleware.SessionChannelConsole, middleware.SessionChannelStream)
case authn.PermConsoleControl:
channels = append(channels, middleware.SessionChannelConsole)
case authn.PermTerminal:
channels = append(channels, middleware.SessionChannelTerminal)
case authn.PermAi:
channels = append(channels, middleware.SessionChannelAi)
}
}
return channels
}
func parsePermissions(raw []string) ([]authn.Permission, error) {
if raw == nil {
return nil, nil
}
permissions := make([]authn.Permission, 0, len(raw))
for _, item := range raw {
permissions = append(permissions, authn.Permission(item))
}
if err := authn.ValidatePermissions(permissions); err != nil {
return nil, err
}
return permissions, nil
}
func permissionStrings(permissions []authn.Permission) []string {
strings := make([]string, 0, len(permissions))
for _, permission := range permissions {
strings = append(strings, string(permission))
}
return strings
}
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
}

53
server/service/auth/users_test.go Normal file
View File

@@ -0,0 +1,53 @@
package auth
import (
"errors"
"testing"
"NanoKVM-Server/authn"
)
func TestRotateAPIKeyOnlyWhenLostAndRequested(t *testing.T) {
calls := 0
failing := false
original := APIKeyRotator
APIKeyRotator = func() error {
calls++
if failing {
return errors.New("disk full")
}
return nil
}
defer func() { APIKeyRotator = original }()
withMcp := []authn.Permission{authn.PermConsoleView, authn.PermMcp}
without := []authn.Permission{authn.PermConsoleView}
cases := []struct {
name string
previous, current []authn.Permission
requested bool
wantRotated bool
}{
{"kept grant", withMcp, withMcp, true, false},
{"never held", without, without, true, false},
{"lost, kept by request", withMcp, without, false, false},
{"lost, rotation requested", withMcp, without, true, true},
{"deleted, rotation requested", withMcp, nil, true, true},
}
for _, tc := range cases {
calls = 0
rotated, err := rotateAPIKeyIfLost(tc.previous, tc.current, tc.requested)
if err != nil {
t.Fatalf("%s: %v", tc.name, err)
}
if rotated != tc.wantRotated || calls != map[bool]int{false: 0, true: 1}[tc.wantRotated] {
t.Fatalf("%s: rotated=%v calls=%d", tc.name, rotated, calls)
}
}
failing = true
if rotated, err := rotateAPIKeyIfLost(withMcp, without, true); rotated || !errors.Is(err, errAPIKeyNotRotated) {
t.Fatalf("failed rotation: rotated=%v err=%v", rotated, err)
}
}

97
server/service/controlmode/activity.go Normal file
View File

@@ -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{})
}

555
server/service/controlmode/manager.go Normal file
View File

@@ -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)
}

202
server/service/controlmode/manager_test.go Normal file
View File

@@ -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)
}
}

795
server/service/download/service.go
View File

@@ -2,286 +2,439 @@ package download
import (
"NanoKVM-Server/proto"
"NanoKVM-Server/service/storage"
"NanoKVM-Server/service/storage/diskfs"
"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"
"sync"
"time"
"regexp"
"github.com/gin-gonic/gin"
log "github.com/sirupsen/logrus"
"golang.org/x/sys/unix"
)
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"
imageDirectory = "/data"
// transferTempPrefix marks the partial files of the uploads and downloads
// this service writes. The file manager hides them and refuses to delete
// them while a transfer runs (diskfs.IsTransferTemp), and a restart sweeps
// whatever a transfer left behind.
transferTempPrefix = diskfs.DownloadTempPrefix
// Keep /data from filling up completely: the exFAT metadata and the USB
// mass-storage export still need room while the image is written.
imageFreeReserve = 128 << 20
)
var (
errDownloadInProgress = errors.New("download in progress")
errSHA256Mismatch = errors.New("sha256 mismatch")
)
// maxUploadBytes caps a single upload even when the client lies about its
// length, so a runaway request cannot fill the card before the free space
// check has had its say.
const maxUploadBytes = 8 << 30
type Service struct {
downloadMutex sync.Mutex
downloadCancel context.CancelFunc
downloadDone chan struct{}
downloadStatus downloadStatus
downloadFile string
downloadLoaded int64
downloadTotal int64
}
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)
go removeStaleTransfers()
return &Service{downloadStatus: downloadStatusIdle}
}
// removeStaleTransfers deletes the temporary files of uploads and downloads
// that a restart interrupted. They are hidden and can be hundreds of
// megabytes, and hidden from the file manager, so leaving them behind would
// quietly fill the card. A file upload into the shared folder
// writes its temporary next to its target, so the whole tree is walked, not
// just the root.
//
// The walk covers the whole data partition, so it runs in the background, and
// a transfer may start while it does: only names one of our transfers would
// generate are collected, and each is removed only while no transfer runs. A
// transfer started after the walk writes a fresh name the walk never saw.
// While the target machine owns the partition it is read-only here, and the
// sweep waits for the next start.
func removeStaleTransfers() {
var stat unix.Statfs_t
if err := unix.Statfs(imageDirectory, &stat); err != nil || stat.Flags&unix.ST_RDONLY != 0 {
return
}
var stale []string
_ = filepath.Walk(imageDirectory, func(path string, info os.FileInfo, err error) error {
if err != nil || info.IsDir() {
return nil
}
if diskfs.IsTransferTemp(info.Name()) {
stale = append(stale, path)
}
return nil
})
for _, path := range stale {
if storage.TransferInProgress() {
log.Infof("leave stale transfer %s: a transfer is running", path)
continue
}
if err := os.Remove(path); err != nil {
log.Errorf("remove stale transfer %s failed: %s", path, err)
} else {
log.Infof("removed stale transfer %s", path)
}
}
}
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.downloadLoaded = 0
s.downloadTotal = 0
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{}, loaded, total int64) {
s.downloadMutex.Lock()
defer s.downloadMutex.Unlock()
if s.downloadDone == done {
s.downloadLoaded = loaded
s.downloadTotal = total
}
}
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.downloadLoaded = 0
s.downloadTotal = 0
_ = 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) {
f, err := os.Open(path)
if err != nil {
return false, err
}
defer f.Close()
// ISO-9660 Magic "CD001" bei Offset 32769
_, err = f.Seek(0x8001, io.SeekStart)
if err != nil {
return false, err
// ensureImageSpace rejects an upload that cannot fit into dir, keeping a small
// reserve for filesystem metadata and for the USB mass-storage export.
func ensureImageSpace(dir string, contentLength int64) error {
if contentLength <= 0 {
return nil
}
buf := make([]byte, 5)
_, err = io.ReadFull(f, buf)
if err != nil {
return false, err
var stat unix.Statfs_t
if err := unix.Statfs(dir, &stat); err != nil {
return fmt.Errorf("cannot read free space of %s: %w", dir, err)
}
return string(buf) == "CD001", nil
available := uint64(stat.Bavail) * uint64(stat.Bsize)
payload := uint64(contentLength)
if payload > available || available-payload < imageFreeReserve {
return fmt.Errorf(
"not enough space in %s: need %d MiB including reserve, %d MiB available",
dir,
(payload+imageFreeReserve)>>20,
available>>20,
)
}
return nil
}
// imageSpaceLimit is how many bytes a download may write into dir: its
// announced length, which ensureImageSpace has already checked, or else what
// fits while keeping the reserve.
func imageSpaceLimit(dir string, contentLength int64) (int64, error) {
if contentLength >= 0 {
return contentLength, nil
}
var stat unix.Statfs_t
if err := unix.Statfs(dir, &stat); err != nil {
return 0, fmt.Errorf("cannot read free space of %s: %w", dir, err)
}
available := uint64(stat.Bavail) * uint64(stat.Bsize)
if available <= imageFreeReserve {
return 0, fmt.Errorf("not enough space in %s: %d MiB available", dir, available>>20)
}
return int64(available - imageFreeReserve), nil
}
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
loaded := s.downloadLoaded
total := s.downloadTotal
s.downloadMutex.Unlock()
return
}
rsp.OkRspWithData(c, &proto.StatusImageRsp{
Status: "idle",
File: "",
Percentage: "",
Status: string(status),
File: file,
Percentage: utils.FormatPercentage(loaded, total),
Loaded: loaded,
Total: total,
})
}
func (s *Service) DownloadImageFile(c *gin.Context) {
var rsp proto.Response
log.Debug("DownloadImage")
log.Debug("DownloadImageFile")
// 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)
// Everything below lands on the data partition, which the target machine
// owns whenever the emulated disk is attached to it. Hold that ownership
// decision for the whole transfer: a mount must wait instead of remounting
// /data underneath an upload that is already streaming.
releaseDataPartitionWrite, err := storage.BeginDataPartitionWrite()
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
}
defer releaseDataPartitionWrite()
expectedSHA256, err := parseSHA256(c.GetHeader("X-SHA256-Sum"))
if err != nil {
rsp.ErrRsp(c, -1, err.Error())
return
}
// Multipart Reader direkt nutzen (keine FormFile!)
reader, err := c.Request.MultipartReader()
if err != nil {
// Reject an upload that cannot fit before any of it is received.
if err := ensureImageSpace(imageDirectory, c.Request.ContentLength); err != nil {
log.Warnf("reject image upload: %s", err)
rsp.ErrRsp(c, -1, err.Error())
return
}
done, err := s.beginDownload("", nil)
if err != nil {
rsp.ErrRsp(c, -1, err.Error())
return
}
finalStatus := downloadStatusFailed
defer func() {
s.finishDownload(done, finalStatus)
}()
// The whole body is written to the data partition, so cap the request even
// when the client lies about its length. This has to happen before the
// multipart reader is created: it keeps reading from the body it was handed.
c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxUploadBytes)
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 := validateImageFilename(filename); err != nil {
_ = part.Close()
log.Warnf("reject uploaded image %q: %s", filename, err)
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)
// The rejection paths below return without draining the request body: the
// client stops uploading as soon as the response arrives.
out, err := os.CreateTemp(imageDirectory, transferTempPrefix+"upload-*")
if err != nil {
log.Error("Read failed")
rsp.ErrRsp(c, -1, "Read failed")
lw.stopTicker()
defer os.Remove(sentinelPath)
log.Errorf("cannot create temporary file in %s: %s", imageDirectory, err)
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 {
log.Error("write failed")
hasher := sha256.New()
lw := utils.NewProgressWriter(io.MultiWriter(out, hasher), c.Request.ContentLength, func(loaded, total int64) {
s.setDownloadProgress(done, loaded, total)
})
// The name already said what this has to be: .iso or .img. The bytes
// are taken as they come; a file that turns out not to be an image
// fails when it is mounted, not while it is stored.
_, copyErr := io.Copy(lw, part)
lw.Stop()
partCloseErr := part.Close()
outCloseErr := out.Close()
if copyErr != nil || partCloseErr != nil || outCloseErr != nil {
log.Errorf("write uploaded image %q failed: %s", filename, errors.Join(copyErr, partCloseErr, outCloseErr))
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
}
outPath := filepath.Join(imageDirectory, filename)
if err := storage.InstallImage(tempPath, outPath); err != nil {
rsp.ErrRsp(c, -1, err.Error())
return
}
finalStatus = downloadStatusIdle
rsp.OkRspWithData(c, &proto.StatusImageRsp{
Status: string(downloadStatusIdle),
File: "",
Percentage: "",
})
return
}
rsp.ErrRsp(c, -1, "file is required")
}
// validateImageFilename accepts what the emulated disk can expose: ISO images
// and raw disk images. The name never reaches the filesystem unchecked, and
// the rules are the ones a FAT volume can hold, so a medium named the same way
// is reachable from the file manager too.
func validateImageFilename(filename string) error {
if !utils.IsMediaFile(filename) {
return errors.New("only .iso and .img files allowed")
}
return utils.ValidateFileName(filename)
}
func (s *Service) DownloadImage(c *gin.Context) {
var req proto.MountImageReq
var req proto.DownloadImageReq
var rsp proto.Response
log.Debug("DownloadImage")
@@ -291,127 +444,165 @@ 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)
// The download runs after this handler returns, and its temporary file is
// on the same partition the raw medium exposes. Keep the partition reserved
// until the goroutine has installed or removed that file.
releaseDataPartitionWrite, err := storage.BeginDataPartitionWrite()
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
}
// 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)
ctx, cancel := context.WithCancel(context.Background())
done, err := s.beginDownload(req.File, cancel)
if err != nil {
releaseDataPartitionWrite()
cancel()
rsp.ErrRsp(c, -1, err.Error())
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 releaseDataPartitionWrite()
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(loaded, total int64) {
s.setDownloadProgress(done, loaded, total)
}); 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: "",
})
}
type loggingWriter struct {
writer io.Writer
total int64
totalSize int64
ticker *time.Ticker
done chan bool
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 (lw *loggingWriter) startTicker() {
lw.ticker = time.NewTicker(2500 * time.Millisecond)
lw.done = make(chan bool)
go func() {
for {
select {
case <-lw.done:
return
case <-lw.ticker.C:
lw.updateSentinel()
}
}
}()
}
func (lw *loggingWriter) stopTicker() {
lw.ticker.Stop()
lw.done <- true
}
func (lw *loggingWriter) updateSentinel() {
percentage := float64(lw.total) / float64(lw.totalSize) * 100
content, err := os.ReadFile(sentinelPath)
func (s *Service) downloadRemoteImage(
ctx context.Context,
rawURL string,
expectedSHA256 []byte,
filename string,
onProgress func(loaded, total int64),
) error {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
if err != nil {
log.Error("Failed to read sentinel file")
return
return fmt.Errorf("create download request failed: %w", err)
}
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")
}
}
func (lw *loggingWriter) Write(p []byte) (int, error) {
n, err := lw.writer.Write(p)
lw.total += int64(n)
return n, 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)
}
// The response headers say how large the image is: refuse it now instead
// of filling the partition and failing at the end. An unknown length
// (chunked responses) skips the check and is caught by the write itself.
if err := ensureImageSpace(imageDirectory, resp.ContentLength); err != nil {
return err
}
// A response without a length is capped by the free space instead, so a
// server that never stops sending cannot fill the partition. One byte more
// than the cap is read to tell "exactly fits" from "does not fit".
limit, err := imageSpaceLimit(imageDirectory, resp.ContentLength)
if err != nil {
return err
}
tempFile, err := os.CreateTemp(imageDirectory, transferTempPrefix+"download-*")
if err != nil {
return fmt.Errorf("create temporary image failed: %w", err)
}
tempPath := tempFile.Name()
defer os.Remove(tempPath)
hasher := sha256.New()
lw := utils.NewProgressWriter(io.MultiWriter(tempFile, hasher), resp.ContentLength, onProgress)
written, copyErr := io.Copy(lw, io.LimitReader(resp.Body, limit+1))
lw.Stop()
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 written > limit {
return fmt.Errorf("not enough space in %s for the downloaded image", imageDirectory)
}
// net/http already fails a body shorter than its Content-Length and cuts
// a longer one off, but an image that is not the size the server
// announced is not one to install either way.
if resp.ContentLength >= 0 && written != resp.ContentLength {
return fmt.Errorf("downloaded image is %d bytes, the server announced %d", written, resp.ContentLength)
}
if expectedSHA256 != nil && !bytes.Equal(hasher.Sum(nil), expectedSHA256) {
return errSHA256Mismatch
}
if ctx.Err() != nil {
return ctx.Err()
}
destPath := filepath.Join(imageDirectory, filename)
if err := storage.InstallImage(tempPath, destPath); err != nil {
return err
}
return nil
}

Some files were not shown because too many files have changed in this diff Show More