160 lines
11 KiB
Markdown
160 lines
11 KiB
Markdown
# Linux-MVP WebUI
|
|
|
|
React/TypeScript, no runtime demo data, no desktop/terminal/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 authoritative runtime is the backend serving `web/dist` at
|
|
`https://rmm-dev.internal:18443`. No certificate-verification bypass is supported.
|
|
|
|
## 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.
|
|
`job_id`/`attempt_id` are **not prerequisites** for planning, submission or approval:
|
|
if present they are optional fixed plan references, not proof of executable jobs
|
|
or persisted attempts. Actual jobs/attempts 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.
|