Files
rust-discovery/web/README.md
2026-11-13 19:11:45 +01:00

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.