Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,8 @@ jobs:
# Managed Secure Access readiness (0.69): the heartbeat block's parser
# (closed keys and values, cli agreeing with the keys, nothing that is
# not the installed exe) and the readiness decision — every rule, and
# 622,080 combinations of facts with no managed state among them.
# 1,244,160 combinations of facts with no managed fact and no managed
# state among them (0.72: the managed states only from a managed fact).
- name: MSA readiness tests
run: node apps/api/scripts/unit-msa-readiness.mjs

Expand All @@ -195,6 +196,13 @@ jobs:
- name: MSA grant tests
run: node apps/api/scripts/unit-msa-grants.mjs

# Managed Secure Access enforcement (0.72): the vocabulary the portal and
# the agent share (keys, outcomes, events, the view-only ceiling), the
# rotation hold, the strict report body, and the grant-key target's one
# name and schema across the portal, the agent and the release host.
- name: MSA managed tests
run: node apps/api/scripts/unit-msa-managed.mjs

# Diagnostics catalog (0.31): the closed catalog, result sanitising,
# redaction and the size cap against the compiled module, the agent's
# dispatch switch against the catalog — and, with the runner's pwsh, both
Expand Down
18 changes: 18 additions & 0 deletions .github/workflows/lab-windows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,24 @@ jobs:
$env:REM0TE_LAB_AGENT_EXE = "$env:RUNNER_TEMP\rem0te-agent.exe"
go test -tags labwindows -count=1 -v -timeout 15m -run '^TestLabRustdeskPreflight$' .
exit $LASTEXITCODE
# Managed Secure Access enforcement (0.72): the agent's enforcement exec
# site against the real RustDesk — save, apply a view-only grant and
# read every setting back, the one-time password ("Done"), end the
# session (random password, stop-service Y then N), restore — as the
# administrator and as SYSTEM in session 0. It changes RustDesk's
# settings on this throwaway runner and puts them back.
- name: Agent MSA enforcement ${{ matrix.version }} (apply, readback, end, restore)
if: matrix.version != '1.3.9'
working-directory: tools/windows-installer
shell: powershell
env:
REM0TE_LAB: '1'
REM0TE_LAB_RUSTDESK: ${{ matrix.version }}
REM0TE_LAB_EVIDENCE: ${{ runner.temp }}\lab-part\enforce-evidence-${{ matrix.version }}.jsonl
run: |
New-Item -ItemType Directory -Force -Path "$env:RUNNER_TEMP\lab-part" | Out-Null
go test -tags labwindows -count=1 -v -timeout 20m -run '^TestLabRustdeskEnforce$' .
exit $LASTEXITCODE
- name: Keep the part
if: always()
uses: actions/upload-artifact@v7
Expand Down
136 changes: 136 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,142 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

---

## [0.72.0] — 2026-11-20 · *Helm*

**Managed Secure Access build step 4: agent enforcement, the managed test session, cutover and rollback —
behind `MSA_GRANTS`, which is off.** (docs/managed-secure-access.md §3.11; check-security-invariants §82, with
§56, §62, §80 and §81 amended.)

> **This is a new signed agent build.** When it is published the fleet's signed agents update to 0.72 the way
> they always do. **On a Legacy computer — which is every computer until a Platform Admin moves one — the 0.72
> agent behaves exactly as 0.71's**: the heartbeat never says `msaPoll`, the new `msa-poller` never starts, and
> no RustDesk setting or password is touched. With `MSA_GRANTS` off (production) nothing new happens anywhere:
> every new route answers `404 MSA_NOT_ENABLED` and the heartbeat never tells an agent to poll.

Even with the switch on, **nothing on a computer changes until a Platform Admin moves that one computer into
Managed (pending)** with a fresh confirmation. There is no group, business or fleet cutover and nothing moves a
computer by itself. Managed Secure Access has run only in the Windows lab (GitHub's Windows Server runners,
RustDesk 1.4.1–1.5.3), never on a Windows 10/11 desktop or on the fleet.

### Grant keys reach agents only through the signed release

- New on the release host: `rem0te-signed-grant-key add | list | retire` (installed by
`rem0te-signed-setup.sh`). It records grant **public** keys in `$STATE_DIR/msa-grant-keys.json` (at most 8)
and refuses key material (`PRIVATE`, `-----BEGIN`), anything that is not 32 bytes of standard base64, and a
key id that is not the first 16 hex of the key's SHA-256.
- `rem0te-signed-publish` signs the list in on every publish as the target `msa/grant-keys.json` (schema
`rem0te-msa-grant-keys/1`); `rem0te-signed-status` shows its digest. `retire` + `--republish` publishes the
shorter list, so agents refuse grants under the retired key.
- The agent reads keys only from that verified target (`agent.MsaTrust`, with the signed pause). No target, an
empty list or an unknown key id is a refusal (`no_keys`, `unknown_key`) — the portal never sends a key.
- The console's Managed Secure Access card shows a Platform Admin the exact two commands
(`sudo rem0te-signed-grant-key add --key-id … --public-key …`, `sudo rem0te-signed-publish --republish`) until
the published release lists the active key; `POST /msa/grants/keys` (`msa.grant`) creates the key if none
exists. The two strings are constants in `apps/api/src/msa/grant-key-commands.ts`, which §56 matches exactly.

### Per-computer mode, cutover, verification and rollback (migration 0089)

- `MsaManagedComputer`: no row is Legacy; `pending`, `verified`, `enforcement_failure`, `rollback_pending`.
Written only by `MsaManagedService`. A trigger refuses a row for an unassigned computer.
- `POST /msa/managed/:endpointId/cutover` — Platform Admin, `assertFresh` naming the new catalog key
`msa.cutover` (default off, as every key since 0.64). Refused: unassigned (`ENDPOINT_UNASSIGNED`), not the
signed Windows agent (`MSA_SIGNED_AGENT_REQUIRED`), readiness not *Compatible* (`MSA_NOT_COMPATIBLE`), an
agent older than 0.72 (`MSA_AGENT_TOO_OLD`), a `remote` pause (`CONTAINED`), already managed
(`MSA_ALREADY_MANAGED`), or the grant key not in the published release (`MSA_GRANT_KEY_NOT_PUBLISHED`).
`MSA_CUTOVER` is written with `logOrFail` before the row.
- `POST …/confirm` (`msa.cutover`) moves `pending` → `verified` only after a test session since cutover that read
back and connected (`MSA_NO_TEST_SESSION` otherwise). The agent then sets a permanent password nobody is
told (`MSA_LEGACY_SECURED`).
- `POST …/rollback` — Platform Admin, **never** asks for a fresh confirmation, audited. Cancels issued grants,
stages a fresh sealed permanent password through the existing rotation path (`stageRotationForMsa`, which
shares `stagePendingPassword` with Rotate), and wakes the agent, which ends any session, restores the saved
settings and reads them back (`restored` deletes the row; `restore_failed` keeps it, with the keys).
`force: true` finishes a rollback only for a computer already rolling back whose agent is gone.
- Readiness gains *Managed (pending)*, *Managed and verified* and *Enforcement failure*, produced only from the
row and the agent's reports. `verified: true` only for *Managed and verified*, and only while the agent's last
full readback is inside the report window; older, it reads *Unknown*.
- A **verified** computer's legacy password is refused everywhere: Reveal, Connect (`msa_managed`), Rotate and
Set password (`409 MSA_MANAGED`). A staged legacy rotation waits while the computer is verified, failing,
rolling back, or has a grant in flight (`managed.ts` `rotationHeld`, bounded by the grant's window / 9 h).
**Technician Connect through grants is step 5**, so a verified computer is reachable only through Platform
Admin test grants until then: roll it back to connect the ordinary way. Turning `MSA_GRANTS` off with a verified
computer stops its poller but keeps refusing its legacy password (fail closed) — roll back first.

### The heartbeat and the poller

- The heartbeat answers `msaPoll: true` only to an authenticated signed heartbeat that may act (§64), after the
not-may-act and pooled returns, with the switch on and a managed row. The signed heartbeat script then starts
`rem0te-agent.exe msa-poller` (no arguments; one instance under `msa\poller.lock`; it exits after an idle hour,
or as soon as the portal says Legacy / 404 / 403).
- `internal/msa/enforce` (portable, fakes under test) + `msa_poller_windows.go`. For each grant: verify under the
published keys, this computer's own endpoint id (pinned on first answer) and RustDesk ID, the persisted replay
set, the signed pause, and the **compiled ceiling: view only, nothing beyond** — no keyboard, clipboard, files,
audio, tunnel or remote restart. The portal refuses a managed grant above it first (`MSA_ABOVE_CEILING`).
- The replay set is written before anything changes; before the first change ever, every current setting is
saved to `StateDir\msa\enforce\saved.json` (SYSTEM-only DACL). A save that fails refuses the grant
(`save_failed`).
- Apply: `verification-method=use-permanent-password` first, then the §3.3 settings, each read back (an empty
readback is RustDesk's default, per the 0.68.3 lab), then the one-time password last, which must print `Done`.
Any disagreement ends the session at once and reports `failed` with closed key names (`readback_mismatch`,
`password_not_applied`); nothing weaker is applied.
- Session end (connection closed, `maxMinutes`, nobody connected by `notAfter`, rollback): a random 24-character
password nobody is told, `stop-service Y`, 3 s, `N`, and `stop-service` read back `N`. While pending, the saved
settings are restored after each test session and the portal stages a legacy rotation, so Legacy Connect keeps
working between test sessions. At rest a verified computer is read back hourly; drift is *Enforcement failure*.
- `POST /msa/agent/report` (public, rate-limited): a strict zod body with closed events, outcomes and keys and no
password field, then the device secret, before anything is read.
- One exec site (`enforceRunner.Run`): only what `enforce.Valid` accepts, only the installed `rustdesk.exe` that
the RustDesk service runs, argument array, no shell, no window, output capped, arguments never logged. §80's
"only the preflight names `--option`" is now an exact list: the preflight's two files and `enforce/args.go`;
only `enforce/args.go` names `--password`. The password is in no log, report or audit row.

### The managed test session

`POST /msa/grants/test/:endpointId` on a pending computer sends a view-only grant (consent required). Once the
agent reports it applied, **Reveal one-time password** (`POST /msa/managed/grants/:grantId/reveal`, Platform
Admin, new catalog key `msa.reveal`) shows it once: scope, applied and not yet revealed, then
`MSA_PASSWORD_REVEALED` (ids only) with `logOrFail`, then a conditional claim, then the password is opened. The
admin connects with RustDesk; the agent reports `connected` (`rustdesk.exe --cm`) and `ended`.

### Console (Platform Admins only, nothing visible with the switch off)

The readiness card gains *Move to Managed (pending)*, *Send test grant*, *Reveal one-time password*, *Confirm
verified*, *Roll back to Legacy* and *Finish rollback without the agent*, with the evidence behind each state and
the grant-key commands. Labels say what was observed, never what was merely saved.

With the switch off the console makes **no request to a gated route**: the readiness answers carry
`managedControls` (the switch), and the card mounts the managed controls only when it is true (an earlier build
of this branch asked `GET /msa/managed/:id` on every device page and got a 404 each time; `e2e-ui.mjs` now asserts
no `/msa/managed` or `/msa/grants` request is made). *Remote access readiness* shows the four readiness tiles while
the switch is off — a managed tile appears only for a state some computer is really in — and all seven, with a
testing note, when it is on.

### Not in this release (step 5)

Connect issuing grants for technicians; `control` mode or any permission above view-only; group or business
cutover; revocation and the session-evidence timeline; a console switch for `MSA_GRANTS`.

### Tests

- `apps/api/scripts/e2e-msa-managed.mjs` (new, port 3961, in `run-e2e.sh`): 106 checks — the switch off, every
cutover refusal, the published-key gate against a stand-in signed repository, msaPoll only for the managed
computer, reports, reveal once, confirm, rollback and force, legacy refusals, the CHECKs.
- `unit-msa-managed.mjs` (new, in CI, 42), `unit-msa-readiness.mjs` (102), `e2e-msa-grants.mjs` (69),
`e2e-msa-readiness.mjs` (52), `unit-signed-release.mjs` and `e2e-signed-release.mjs` (grant-key add, refusals,
publish, status, retire).
- Go: `internal/msa/enforce` (20 tests, a fake RustDesk: apply order, fail-closed readback, `Done`, replay,
bad keys, ceiling, pause, endpoint pin, save failure, no connection / max minutes, rollback, drift).
- Windows lab: `TestLabRustdeskEnforce` in every RustDesk job (1.4.1–1.5.3) — save, apply, readback, password,
end session, restore, as the administrator and as SYSTEM. The WSUS `127.0.0.1:8530` trick is unchanged.

### Deploying (only with the owner's approval)

Migration 0089 (and the Prisma client at the target, per CLAUDE.md). Leave `MSA_GRANTS` unset. Publish the signed
agent as usual. To try one computer later: set `MSA_GRANTS=on`, create the key in the console, run the two
commands it shows on the release host, then move one computer.

---

## [0.71.0] — 2026-11-20 · *Tether*

**Managed Secure Access build step 3: the portal can sign a session grant and hold it for a computer's signed
Expand Down
66 changes: 61 additions & 5 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -1567,8 +1567,9 @@ computer and nothing can be Managed.
- **The agent only reads.** `rem0te-agent.exe rustdesk-preflight` builds its
argv only through `msa.ReadArgs` — exactly `{"--option", key}` for the
eleven keys of `msa.Keys`, the same list as the portal's `PREFLIGHT_KEYS` —
and nothing in the preflight names `--password`. Only the preflight names
`--option`.
and nothing in the preflight names `--password`. From 0.72 `--option` is
named only by the preflight and `internal/msa/enforce/args.go`, and
`--password` only by `args.go` (§82).
- **One exec site** (`preflightRunner.Read`): the installed
`%ProgramFiles%\RustDesk\rustdesk.exe` (`installedRustdeskExe()`) by
absolute path, an argument array, no shell, no window, output capped. It
Expand Down Expand Up @@ -1620,9 +1621,10 @@ agent binary is unchanged.
poll hands nothing over.
- **The document.** `msa/grant.ts` imports only `node:crypto` and zod. Its
`GRANT_PREFIX` (`rem0te-msa-grant-v1\n`) and `REASONS` order are the Go
verifier's (`internal/msa/grant`). That package is pure and imported by
nothing: it lives outside `internal/msa` because the agent imports that
package for the preflight.
verifier's (`internal/msa/grant`). That package is pure (no clock, file,
network or process). It lives outside `internal/msa` because the agent
imports that package for the preflight; from 0.72 only
`internal/msa/enforce` and `internal/agent` import it (§82).
- **0088** CHECKs the four states, the five-minute window, the limits and
the sealed columns, and holds one active key (partial unique index).

Expand All @@ -1633,6 +1635,60 @@ test-only keys) and asserts every case, and the Go `internal/msa/grant`
tests, which assert the same file. **No agent polls, and none of it has run
on Windows.**

§82 (0.72) is Managed Secure Access enforcement, the managed test session,
cutover and rollback: build step 4, **behind `MSA_GRANTS`, off**. This is a
new signed agent build, but a computer changes only when a Platform Admin
moves that **one** computer; a Legacy computer behaves exactly as 0.71.

- **The heartbeat** says `msaPoll: true` only to an authenticated signed
agent that may act, only with the switch on and a `MsaManagedComputer`
row. The signed heartbeat starts `rem0te-agent.exe msa-poller` (no
argument) only on that answer. One poller at a time (`poller.lock`); it
exits when idle or told the computer is Legacy.
- **Writers.** Only `MsaManagedService` writes `MsaManagedComputer` (0089),
and every public method asserts the switch first. `MsaManagedService`
moves grants only by conditional `updateMany`; only `MsaGrantService`
creates them.
- **Who.** Cutover and confirming verified are a Platform Admin's with
`assertFresh` naming `msa.cutover`; revealing a test session's one-time
password (once) names `msa.reveal`; rollback never asks. No route takes a
group or a business.
- **Cutover**, in order: scope, the pool, not already managed, every blocker
(Compatible readiness, an agent that can enforce, no `remote` pause, a
grant key in the published release), the audit row, then the row.
- **The ceiling** is view-only with no permissions, on both sides
(`enforce.Ceiling` compiled into the agent, the portal's
`MANAGED_CEILING`), never taken from the portal.
- **The agent.** One enforcement exec site (`enforceRunner.Run`) runs only
what `enforce.Valid` accepts, the installed `rustdesk.exe` by absolute
path, an argument array, no shell, and only when the RustDesk service runs
that file. Grant keys come only from the signed `msa/grant-keys.json`
target of the verified update chain. The replay set is written before
anything changes. Settings are saved (SYSTEM-only DACL) before the first
apply, every value is read back, and a mismatch ends the session with a
password nobody is told. No password reaches a log, journal or report.
- **A device report** is parsed strictly, then the device secret is checked,
before any read.
- **Passwords.** A verified computer's legacy password is never revealed,
launched, rotated or set, and a staged rotation waits (`rotationHeld`).
After a pending test session ends, the portal re-establishes a password it
knows through the existing rotation; rollback stages one too.
- **The release host** publishes grant keys (`rem0te-signed-grant-key
add|list|retire`, then `rem0te-signed-publish`); the portal only shows the
two commands, matched exactly in §56's allowlist
(`msa/grant-key-commands.ts`).
- **Not built (step 5):** Connect through grants, control mode, group or
business cutover, revocation and the session-evidence timeline. Turning
the switch off with a verified computer still refuses its legacy
password: roll back first.

Behavioural proof: `e2e-msa-managed.mjs` (port 3961, in `run-e2e.sh`). Unit:
`unit-msa-managed.mjs` (in CI) and the Go `internal/msa/enforce` tests (a
fake RustDesk runner). Lab: `TestLabRustdeskEnforce` in the Windows lab's
RustDesk jobs (save, apply, read back, password, end session, restore, as the
administrator and as SYSTEM). **It has run only on Windows Server in the
lab**, never on a desktop, with a real remote connection, or on the fleet.

CI runs it on every push and pull request, alongside `check-versions.mjs`.

## Docs
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ people and its own history. Rem0te is the portal around a self-hosted RustDesk
server that keeps them organised and separate.

[![CI](https://github.com/agit8or1/rem0te/actions/workflows/ci.yml/badge.svg)](https://github.com/agit8or1/rem0te/actions/workflows/ci.yml)
[![Version](https://img.shields.io/badge/version-0.71.0-blue)](https://github.com/agit8or1/rem0te/releases)
[![Version](https://img.shields.io/badge/version-0.72.0-blue)](https://github.com/agit8or1/rem0te/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Stars](https://img.shields.io/github/stars/agit8or1/rem0te?style=flat)](https://github.com/agit8or1/rem0te)

Expand Down
2 changes: 1 addition & 1 deletion apps/api/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@reboot-remote/api",
"version": "0.71.0",
"version": "0.72.0",
"private": true,
"scripts": {
"dev": "nest start --watch",
Expand Down
Loading
Loading