217 lines
14 KiB
Markdown
217 lines
14 KiB
Markdown
# Linux-MVP WebUI
|
||
|
||
React/TypeScript, no runtime demo data, no desktop/PTY/hypervisor integration.
|
||
Build assets: **`web/dist/`**; serve `index.html` and `/assets/*` from the TLS backend
|
||
on the same origin. Do not proxy authentication to a different origin. All API URLs
|
||
are relative; cookies use `credentials: same-origin`, mutations use `X-CSRF-Token`.
|
||
No token or password persistence, raw HTML rendering, automatic approval or retry.
|
||
|
||
## Commands
|
||
|
||
From `web/`: `npm ci`, `npm run typecheck`, `npm test`, `npm run build`.
|
||
`npm run dev` binds loopback, but is not the authenticated TLS acceptance setup.
|
||
The current server is `discovery.ease-technologies.de`; management access uses the
|
||
configured SSH tunnel and verified TLS. Earlier local `rmm-dev.internal:18443`
|
||
examples below are historical. The notebook is development only, without an RMM
|
||
server or enrolled agent. No certificate-verification bypass is supported.
|
||
|
||
## Script console (specification 1.20, source implementation)
|
||
|
||
`run_script` remains a durable plan/request, not a PTY or interactive terminal.
|
||
The planner accepts complete fixed POSIX/Bash or Windows PowerShell5.1 scripts.
|
||
The optional action-wide `parameters.privileged_script_profile` is exactly
|
||
`full_maintenance_v1`; missing preserves the existing bounded mode, while present
|
||
null/unknown values fail. Full maintenance requires root on Linux or SYSTEM on
|
||
Windows, plus `scripts:execute` and the separate root/system scope. SYSTEM scripts
|
||
require the explicit profile. The UI selection grants no permission: central/local
|
||
opt-in, target capabilities, independent helper checks and actual WebUI approval
|
||
remain necessary. Full authority includes filesystem, network and services, and
|
||
can alter the agent/PKI or cause a reboot. It has no sandbox/no-reboot promise.
|
||
The profile budgets are Linux 1–300s, Windows 1–120s, at most 32768 script bytes
|
||
and 65536 output bytes. RemoteSigned, when explicitly bound, remains limited to
|
||
the approved Windows job process.
|
||
|
||
Before submit/approval, `src/script-console.ts` projects every script from the
|
||
SHA256-verified stored plan bytes. It checks full payload structure, fixed
|
||
target/job/attempt IDs, script SHA256 and the job SHA256 reconstructed in Rust
|
||
declaration order. Every supplied payload/target alias must agree. It snapshots
|
||
the checked views, rejects later mutation and rechecks immediately before each
|
||
submit/approval action. The displayed script, arguments, identity, profiles,
|
||
budgets, deadlines and hashes come from that projection, never the draft editor.
|
||
Control characters, CR, BOM and bidi controls are made visible in the text view;
|
||
the full original JSON and stored bytes remain available. Existing pending-only
|
||
submission and interactivity/CSRF checks remain in force.
|
||
|
||
`src/console-output.tsx` displays the actual stored job status and final stdout/
|
||
stderr. Status polling is every four seconds; output arrives with the durable
|
||
result. There is no incremental output stream. Null result, empty output,
|
||
unknown exit code, unknown outcome, requested cancellation and truncation are
|
||
distinct. UTF-8 is a display attempt, not a claimed source encoding; invalid
|
||
UTF-8 is marked and original bytes can be downloaded as inert `.bin` files.
|
||
Terminal escapes and bidi controls are visible, never interpreted. Agent output
|
||
is React text and cannot create HTML, approval controls or follow-up jobs.
|
||
|
||
MCP already dispatches plan/submit/read-results to the same server application
|
||
functions. Shared PlanRequest/Action schemas expose the profile; MCP has no
|
||
approval tool and its bearer context cannot become an interactive approval
|
||
session. No independent MCP execution or approval path was added.
|
||
|
||
Local typechecking and renderer tests are source evidence only. Native Linux/
|
||
Windows runs, deployment and actual UI/MCP acceptance remain separate gates.
|
||
Actually executed on 2026-11-14 for this source slice: `npm ci --ignore-scripts
|
||
--no-audit --no-fund`, `npm run typecheck`, `npm test` (49 passed across seven
|
||
files), `npm run build` (TypeScript and Vite passed). Five script-console tests
|
||
read `../tests/script_console/codec-golden.json` directly: the same three actual
|
||
Rust codec families cover legacy Linux agent, Linux root/full and Windows
|
||
SYSTEM/full with RemoteSigned. Checks cover full displayed script/target/attempt/
|
||
profile/budgets/hashes, all aliases, mutation during/after verification and
|
||
independent scopes. Two output tests cover hostile HTML/terminal/bidi bytes,
|
||
unknown/cancellation/truncation, invalid encodings and absent/invalid results.
|
||
No browser, server, VM job, approval or deployment was executed in these checks.
|
||
|
||
## JSON adapter contract
|
||
|
||
`src/api.ts` is the sole transport/contract boundary. Responses missing required
|
||
fields fail explicitly. Unknown backend fields are displayed without interpretation.
|
||
Pages: `{items,next_cursor,completeness,truncated,as_of}`. Tenant items:
|
||
`{tenant_id,name}` (`id` accepted as ID alias). Session:
|
||
`{principal:{id,display_name,simulated:boolean},tenants:[{tenant_id,name}],csrf_token}`.
|
||
`simulated` is explicit server evidence, never inferred from a username.
|
||
The backend session form `{principal:string,tenant_id,testsimulation:boolean,
|
||
csrf_token,roles,permissions}` is also accepted, retaining the exact principal and
|
||
tenant ID as labels until the tenant list supplies its authoritative name. Explicit
|
||
`testsimulation:false` is a nonsimulated OIDC session, not a dev identity. Missing
|
||
simulation metadata fails closed; neither principal names nor roles imply simulation.
|
||
Dev login `POST /auth/dev/login {username,password}`, GET `/auth/session`, POST
|
||
`/auth/logout {}`. Session and CSRF stay in memory only. Backend must disable dev
|
||
login outside dev/test and audit simulation origin/testprincipal/plan binding.
|
||
|
||
Before offering login, the UI reads `GET /auth/config` using same-origin cookies,
|
||
no-store and verified browser TLS. Exact DTO:
|
||
`{oidc_configured:boolean,oidc_login_url:'/auth/oidc/login'|null,dev_login_enabled:boolean}`.
|
||
The only allowed OIDC link is the canonical relative `/auth/oidc/login`, and only
|
||
when configured. Issuer/external/absolute/return/query/fragment URLs are not used by
|
||
the frontend. OIDC callback codes/tokens stay with the backend; the normal reload
|
||
reads `/auth/session`. No local/session storage or auth query logging is used.
|
||
The password form requires explicit dev enablement and prominently identifies a
|
||
simulated dev/test principal. Production SSO-only configuration has no password
|
||
form or simulated-principal label. Configuration loading/error/absent modes never
|
||
fall back to dev login; errors and `not_configured` remain visible.
|
||
|
||
Executed UI auth integration: typecheck/build, 23 unit tests including SSO-only,
|
||
config failure, redirect rejection and explicit nonsimulated session parsing;
|
||
real TLS management/login-config checks plus all three pending/TLS checks passed.
|
||
The current deployment announces OIDC not configured, dev login enabled. Its real
|
||
SSO redirect/callback is therefore not exercised by these UI tests; the positive
|
||
SSO presentation is unit-tested, not external-IdP or production acceptance.
|
||
|
||
All business endpoints are under `/api/v1/tenants/{tenant}`:
|
||
|
||
- GET `/devices[?cursor=]`, `/devices/{asset}`: `asset_id`, presence, health,
|
||
last_contact_at, source_id, observed_at, received_at, quality, completeness,
|
||
inventory/capabilities/other sections. Missing evidence stays `unknown`.
|
||
- POST `/operation-plans`: Spec 23.4 shape `{tenant_id,action,targets:{asset_ids},
|
||
parameters,schedule:{not_before,start_before,offline_policy},rollout:{max_parallel,
|
||
halt_after_failures},reason}`. Times RFC3339 UTC; common parameters:
|
||
execution_identity, timeout_seconds, max_output_bytes. Script parameters: variants
|
||
with `{os_family:'linux',interpreter,encoding:'utf-8',script_utf8}`, arguments,
|
||
expected_stdout. Other action fields are explicit JSON, never shell commands.
|
||
- GET `/operation-plans/{id}`: `{plan_id,plan_hash,expires_at,resolved_targets:[],
|
||
excluded_targets:[],plan_payload_bytes|plan_payload,approval_state?}`. Preferred
|
||
`resolved_targets` entries are immutable previews `{asset_id,job_payload_hash,
|
||
payload,plan_target_id?}`. Alternatively `resolved_targets` lists asset IDs or
|
||
`{asset_id}` records and `payloads` supplies the previews. Legacy `jobs` is accepted
|
||
as the preview list only when neither preferred form is supplied. An incomplete
|
||
preferred form is not silently replaced by legacy data. In legacy previews only,
|
||
asset_id can also come from the exact payload. Every target requires a nonempty
|
||
exact payload and payload hash; preview coverage must equal the fixed target set,
|
||
duplicate asset IDs and contradictory payload asset IDs are rejected.
|
||
Script plans require the reserved `job_id`/`attempt_id` from the exact stored
|
||
payload, as well as matching script/job hashes. These are fixed definitions,
|
||
not proof of executable jobs or persisted attempts. Actual execution rows are
|
||
created only after approval.
|
||
Exact payload metadata and script/package hashes must be included. UI does not
|
||
recompute the plan hash from JSON. Missing fixed targets/previews/payload/hash or
|
||
excluded targets block submission and approval. All fields are shown, not just
|
||
target count. `approval_state` enables opening an existing pending request after
|
||
reload.
|
||
- POST `/operation-plans/{id}/submit {idempotency_key}` → `{operation_id,
|
||
approval_state:'pending_approval'}` (`state` also accepted for submit status).
|
||
No execution jobs before approval. The button then enables explicit review.
|
||
- POST `/operation-plans/{id}/authorizations {plan_hash}` → `{operation_id}`;
|
||
only click handler after explicit checkbox. Backend enforces interactive session,
|
||
pending state, exact immutable binding, permission, tenant, policy, expiry and
|
||
deduplicates repeated clicks. No MCP/bearer fallback.
|
||
- GET `/operations[?cursor=]`, `/operations/{id}` → approval_state,
|
||
execution_state, plan_id, planned_job_count/job_count, jobs (with job_id), counts.
|
||
- GET `/jobs/{id}` → state, attempt, cancel_requested, pending_reason, output,
|
||
results, verification, truncation/reboot flags; raw response shown completely.
|
||
POST `/jobs/{id}/cancel {reason}` only requests cancellation.
|
||
|
||
Errors: `{code,message,retryable,correlation_id,details}`. Non-JSON errors also remain
|
||
visible; failed polling retains the old response alongside an error, never a green
|
||
success message. Tenant changes unmount all selection/plans/jobs and abort requests.
|
||
List pagination uses server cursors, without pretending a truncated page is complete.
|
||
|
||
## Browser checks and separate acceptance gates
|
||
|
||
`tests/browser/approval.spec.ts` uses actual UI interactions only. It never uses an
|
||
API client to authorize, never writes storageState, and disables traces/screenshots/
|
||
video. Its restricted reporter suppresses raw step logs/errors/stdout/stderr because
|
||
Playwright failure call logs can contain password-fill arguments. Do not override
|
||
the reporter or enable Playwright DEBUG/PWDEBUG/trace logging for secret-bearing
|
||
tests. Failure artifacts remain in gitignored `web/node_modules/.cache/browser-results`;
|
||
inspect them only locally as potentially confidential and never publish them.
|
||
It is opt-in via `RMM_E2E_PROFILE=dev/test` and `RMM_E2E_MODE=execute`; without
|
||
both values no positive authorization/execution test runs. A separate
|
||
`pending.spec.ts` uses `RMM_E2E_MODE=pending-only`, never sends authorization
|
||
requests and verifies login/cookie, device selection, exact preview, pending with
|
||
zero executable jobs, session/plan reload, CSRF denial on logout and normal logout.
|
||
Set `RMM_E2E_ASSET_ID` to the explicitly selected Linux test asset and
|
||
`RMM_E2E_LOGIN_FILE` to an owned mode-0600 JSON file `{username,password}` in the
|
||
gitignored credentials directory. Never pass secret values in CLI arguments, log
|
||
them, bundle them or use production accounts. The test only submits Hello World;
|
||
it never reboots or updates the VM.
|
||
|
||
The checked configuration isolates browser HOME to
|
||
`web/node_modules/.cache/browser-home`, with a private NSS trust database there;
|
||
only the public project dev CA is imported, never CA/server private keys. Browser
|
||
launch resolves the two fixed dev test DNS names to PC loopback via Chromium's
|
||
host-resolver rules; it does not change hosts files or global trust/configuration.
|
||
TLS name/chain verification stays enabled. Node's CA setting alone does not
|
||
establish browser trust. No ignore-HTTPS option, insecure flag, direct API
|
||
authorization or production simulation is allowed.
|
||
|
||
Reproduce the pending-only checks with `python3 deploy/browser/run_pending.py`
|
||
from repository root after installing the browser/local NSS tool as documented in
|
||
`deploy/browser/README.md`. The runner imports the public CA, enrolls an explicitly
|
||
synthetic local mTLS test device, advertises only the capability required for plan
|
||
validation, runs real same-origin browser UI checks, and revokes that fixture in
|
||
cleanup. No executor, simulated result, VM access or approval is involved. Pending
|
||
requests remain durable and the synthetic device is visibly revoked afterwards.
|
||
|
||
Actually executed on 2026-11-12: real TLS Chromium login, secure HttpOnly SameSite
|
||
cookie, tenant/device list, plan preview, pending submission with zero jobs/null
|
||
execution, reload/review, CSRF-denied logout, valid logout, rejection of the
|
||
wrong certificate DNS name and rejection of the server chain without the isolated
|
||
CA. All three real browser tests passed. A server-side count guard confirmed no new
|
||
jobs/outbox/grants. Sanitized local evidence:
|
||
`web/node_modules/.cache/browser-evidence/pending.json`. No positive browser
|
||
authorization, Hello-World result or VM feature acceptance is claimed here.
|
||
Verified-TLS fetches also confirmed the served same-origin index and both built
|
||
asset hashes match the current `web/dist` build.
|
||
|
||
Build/unit checks are local development evidence only. Real backend/agent execution,
|
||
VM feature evidence, browser acceptance and production approval remain separate gates.
|
||
|
||
### Gebundene Configure-only-Wiederherstellung (Schema4)
|
||
|
||
Frontend prüft native_recovery mit ursprünglichem Grant/Versuch/Partial-Proof,
|
||
Transaktionsschema2 und ausschließlich configure_only/Fixture1.0→1.0. Normale
|
||
Schemas2/3 erlauben keine Operationserweiterung; Nichtnative-, Altversions-,
|
||
Hash- und Bindungsmanipulationen bleiben verweigert. Elf gezielte Safetytests,
|
||
Typecheck und Produktionsbuild bestanden. Tatsächliche separate Browser-
|
||
Vorbereitung/0-Jobgate/Genehmigung mit exakten Bytes ist belegt; der erste Plan
|
||
lief ohne Offer/Grant an der alten Journalgrenze ab. Paketabnahme bleibt separat:
|
||
`../docs/implementation-status.md`. Keine API-/DB-Freigabeabkürzung.
|