Install an agent on a one-off PC from a single command
Some checks failed
CI / backend (push) Has been cancelled
CI / naming (push) Has been cancelled
CI / gates (push) Has been cancelled
CI / frontend (push) Has been cancelled
CI / lean-build (push) Has been cancelled

An admin generates a short-lived token in Settings > Endpoints > Endpoints and
copies the command it produces. A tech runs that one line in an elevated
PowerShell on a PC with no agent:

    powershell -ExecutionPolicy Bypass -c "irm https://<server>/shopdb/api/
    endpoints/siteagent/bootstrap.ps1?t=<token> | iex"

The script refuses to run unelevated, refuses a PC that already has the agent
(a managed bay gets it from GE-Enforce), downloads the package the existing
builder produces, checks both binaries against the hashes the server baked in,
installs with NO shared key, and reports what happened. The PC then asks to
enroll and waits for an admin to approve it, which the script watches for
locally for two minutes before exiting.

- New endpointbootstraptokens table and migration
  endpoints0024bootstraptokens: hash only, expiry, use count, revoke.
- Admin routes to generate, list and revoke tokens; the secret is shown once.
- Two token-only routes: the script, and the package (which spends a use).
  Anything wrong with the token answers 404 rather than confirming it exists,
  both are rate limited per address and both are audited with the caller.
- The package builder is now shared rather than duplicated, and a bootstrap
  package can never carry a collector key.
This commit is contained in:
cproudlock
2026-09-15 19:33:00 -04:00
parent 408cf08628
commit ca57b7f728
14 changed files with 1718 additions and 31 deletions

View File

@@ -272,6 +272,42 @@ Repeat until **Ready** is 0.
turned off (phase 6) that is the only path, and the steady-state path for new
PCs.
## Installing a one-off PC
A PC nobody is going to author a GE-Enforce manifest entry for - a loaner, a
one-off office machine, a bay being rebuilt out of band - can be installed with
a single command instead of a downloaded package. **Managed bays keep using
GE-Enforce**; this does not replace the share channel, and the script itself
says so when it finds an agent already installed.
1. Settings -> Endpoints -> Build site agent -> **One-line install**. Set how
long the token lives (hours, 1 to 168) and how many installs it may serve
(1 to 500), then **Generate install command**.
2. Copy the command. The token is shown ONCE and cannot be recovered; generate
a new one if it is lost.
3. On the target PC, open PowerShell **as administrator** and paste it:
```
powershell -ExecutionPolicy Bypass -c "irm https://<server>/api/endpoints/siteagent/bootstrap.ps1?t=<token> | iex"
```
The token is short-lived and only fetches the installer. It carries no shared
key and provisions nothing by itself: the package it downloads is built with
"Include shared key" off, whatever the shared-key setting is, so the PC asks to
enroll and **waits for approval**. Approve it in Enrollment -> Credentials ->
Requests, the same as any other pending PC (phase 5).
The script checks the downloaded binaries against the SHA-256 values the server
stamped into it, refuses to run unelevated, and refuses to run on a PC that
already has the agent service (set `SHOPDB_BOOTSTRAP_FORCE=1` in the same
window to override). After a successful install it waits up to two minutes for
the credential to land and prints `approved and enrolled` if an admin approves
it in that window; still pending is a normal outcome, not a failure.
Revoke a token from the same block when the install round is done. Tokens list
with their prefix, expiry and uses; they are also spent automatically
(`usecount` reaching `maxuses`) and expire on their own.
## Phase 6: cutover
**Gate:** Credentials tab **Not enrolled** is 0, or every remaining PC is one