Document SSH host identity and canonical NG preview

.gitignore

@@ -1,5 +1,6 @@
 site/
 site-test/
+site-preview/
 __pycache__/
 *.pyc
 .course-progress.json

README.md

@@ -43,6 +43,21 @@ This is a publication candidate, not a claim that every local command has alread
 
 The statistical and DNA examples are educational. They are not validated clinical pipelines and do not replace study-design, statistical, bioinformatics, data-protection, or clinical review.
 
+## Local website preview
+
+The custom RCC-styled site produced by `tools/build_site.py` is the canonical
+ClusterDocs NG website. The `mkdocs.yml` file remains useful for content and
+navigation checks, but `mkdocs serve` does not reproduce the published design.
+
+Build and browse the same site used by the validation and deployment workflow:
+
+```bash
+python tools/build_site.py --output site-preview
+python -m http.server 8765 --bind 127.0.0.1 --directory site-preview
+```
+
+Then open <http://127.0.0.1:8765/>.
+
 ## Repository integration
 
 `meta/PULL_REQUEST_PLAN.md` recommends an umbrella issue and four reviewable documentation pull requests. Markdown should remain the authoritative repository content. Large MP4 files should normally be hosted as approved institutional media or release assets rather than added to ordinary Git history.

config/public.yml

@@ -5,7 +5,7 @@ production_url: https://CLUSTERDOCS-URL.invalid/
 rollout_date: TO_BE_CONFIRMED
 support_contact: TO_BE_CONFIRMED
 ssh_alias: rcc-login
-ssh_host_key_fingerprint: TO_BE_PUBLISHED_THROUGH_TRUSTED_CHANNEL
+ssh_host_ca_fingerprint: TO_BE_PUBLISHED_THROUGH_TRUSTED_CHANNEL
 transfer_service_name: RCC web transfer
 transfer_service_url: https://TRANSFER-URL.invalid/
 media_base_url: https://MEDIA-URL.invalid/rcc-onboarding

docs/course/class-01-safe-access.md

@@ -14,14 +14,16 @@ By the end of this class you can:
 
 ## Security model in plain language
 
-Your **private key stays on your computer**. RCC receives only the public key. The **server host key** lets your computer verify that it reached the expected RCC service. A changed host key is not fixed by disabling checking; follow the published transition instructions.
+Your **private key stays on your computer**. RCC receives only the public key. The server's **digital identity** lets your computer verify that it reached an approved RCC service. RCC is moving to certificates signed by one RCC host certification authority, so clients can verify the cluster without accepting every machine individually. A changed identity is not fixed by disabling checking; follow the published transition instructions.
 
 Do not email private keys, copy a colleague's key, register one key for several human accounts, or share a browser session. When a colleague needs access, add their own account to the project.
 
 ## First-time client setup
 
 Create a dedicated Ed25519 key protected by a strong passphrase.
 
+If you have a compatible FIDO2 hardware authenticator, prefer `ssh-keygen -t ed25519-sk -f ~/.ssh/id_rcc`. The private material remains on the authenticator and normally requires your physical presence.
+
 On macOS or Linux:
 
 ```bash
@@ -37,8 +39,7 @@ ssh-keygen -t ed25519 -f "$HOME\.ssh\id_rcc"
 Register only `id_rcc.pub` through the approved RCC account workflow. The file
 without `.pub` is the private key and stays on your computer.
 
-Use the SSH configuration supplied through the RCC rollout page. Its safe shape
-is:
+Use the SSH configuration supplied through the RCC rollout page. During migration, RCC Connect provides a separate configuration and trust file that do not replace your ordinary SSH files. Until the rollout notice activates RCC Connect, use the current approved configuration. Its safe shape is:
 
 ```sshconfig
 Host {{ ssh_alias }}
@@ -73,7 +74,7 @@ The gate checks software and configuration. It does not contact RCC unless you e
 
 ## Gate 1B: one bounded SSH test
 
-First verify the current host fingerprint on the rollout page or another trusted institutional channel. Then run exactly one attempt:
+First verify the RCC host-CA fingerprint on the rollout page or another independent institutional channel. Then run exactly one attempt:
 
 ```bash
 bash exercises/readiness/rcc-readiness.sh --live
@@ -83,7 +84,7 @@ The test uses strict host-key checking, disables password prompts, permits one c
 
 ## Gate 1C: VS Code
 
-The same readiness script checks whether VS Code and the Microsoft Remote - SSH extension are present. Terminal SSH must work before VS Code is tested.
+The same readiness script checks whether VS Code and the Microsoft Remote - SSH extension are present. Terminal SSH must work before VS Code is tested. When RCC Connect becomes active, its repair action selects the dedicated RCC SSH configuration for VS Code.
 
 ## Web data transfer
 
@@ -103,6 +104,11 @@ The transfer portal exposes project data, not arbitrary server filesystems. Conf
 It removes the check that distinguishes the intended server from an unexpected system. Verify a planned transition through an independent institutional channel.
 </details>
 
+<details><summary>What should I do when RCC reports an identity change?</summary>
+
+Do not approve the warning or delete `known_hosts` entries. Close VS Code, run RCC Connect's connection test and repair action, and report its support code if the repair fails.
+</details>
+
 <details><summary>Can two researchers use the same SSH key?</summary>
 
 No. Each human account should have individually attributable credentials. Project access is granted through membership, not credential sharing.

docs/policies/ssh-host-identity.md

@@ -0,0 +1,139 @@
+# RCC SSH host-identity policy
+
+> **Status:** This page documents the planned SSH host-identity architecture and migration. Until the rollout page says RCC Connect is active, use the currently published RCC SSH configuration. Do not build a CA entry from examples on this page.
+
+## Decision
+
+RCC will use:
+
+- a unique Ed25519 private host key on every server;
+- one RCC SSH host certification authority (CA);
+- an RCC host certificate on every server; and
+- certificate principals for all approved short names, fully qualified domain names and service aliases.
+
+The single RCC identity presented to users is the **public host CA**, not a private key copied to every machine. A shared fleet-wide private host key is prohibited: compromise of one node would otherwise permit impersonation of every other node and make individual revocation and incident containment impossible.
+
+Host authentication and user authentication are separate. The host certificate proves that a client reached an approved RCC service. A user's SSH key proves which RCC account is connecting.
+
+## Dedicated RCC trust
+
+RCC trust must not depend on the user's ordinary `known_hosts` file. That file can contain stale RCC keys, hashed names, unrelated systems and records written by several SSH clients.
+
+RCC Connect keeps its configuration under a user-owned directory:
+
+- macOS and Linux: `$HOME/.rcc-ssh/`
+- Windows: `%USERPROFILE%\.rcc-ssh\`
+
+The dedicated `rcc_known_hosts` file contains the public RCC host-CA entry and approved hostname patterns. The generated configuration selects that file only for RCC hosts and requires strict verification:
+
+```sshconfig
+Host rcc-shell shellhost shellhost.ikim.uk-essen.de c??? d?? g?-??
+  UserKnownHostsFile ~/.rcc-ssh/rcc_known_hosts
+  StrictHostKeyChecking yes
+  IdentitiesOnly yes
+  ForwardAgent no
+```
+
+This leaves GitHub, other clusters and unrelated trust records untouched. The stable `rcc-shell` entry resolves to the RCC submission service. Generated compute-node entries use it as their jump host, keeping worker nodes from direct external exposure.
+
+## RCC Connect
+
+The primary client distribution is a portable ZIP that needs no installation, administrator access or PowerShell execution. A release is expected to include:
+
+```text
+RCC-Connect/
+|-- README-FIRST.txt
+|-- RCC-Connect.cmd
+|-- RCC-Test.cmd
+|-- RCC-Repair.cmd
+|-- ssh_config
+|-- rcc_known_hosts
+|-- rcc-host-ca.pub
+|-- fingerprints.txt
+`-- vscode-settings.json
+```
+
+A Windows kit may include a maintained OpenSSH client to avoid conflicts among Windows OpenSSH, Git for Windows, PuTTY-derived clients and SSH programs inserted into `PATH`. RCC must promptly update any client it distributes.
+
+Launchers explicitly select the kit configuration. They must not depend on the user's existing SSH configuration, system-wide configuration, administrator privileges or machine-wide environment variables. A user-scoped installed mode may add shortcuts and automated repair, but the portable mode remains supported when endpoint policy removes or rewrites installed files.
+
+## VS Code integration
+
+RCC Connect supplies VS Code Remote SSH with its dedicated configuration file. A Windows kit that bundles SSH also selects that executable. Equivalent settings are:
+
+```json
+{
+  "remote.SSH.configFile": "C:\\Users\\USERNAME\\.rcc-ssh\\ssh_config",
+  "remote.SSH.path": "C:\\Users\\USERNAME\\.rcc-ssh\\bin\\ssh.exe"
+}
+```
+
+On macOS:
+
+```json
+{
+  "remote.SSH.configFile": "/Users/USERNAME/.rcc-ssh/ssh_config",
+  "remote.SSH.path": "/usr/bin/ssh"
+}
+```
+
+The connection test checks these values because endpoint policy may reset them. Recovery is exposed as **Repair VS Code connection**, not as a requirement for users to edit JSON manually.
+
+## Independent trust bootstrap
+
+A checksum inside a downloaded ZIP cannot authenticate that ZIP. RCC publishes the host-CA fingerprint and package-signing information through several independent RCC-controlled channels, including:
+
+- RCC Admin over HTTPS;
+- the public RCC documentation site;
+- account-enrolment material;
+- an enrolment card or QR code;
+- the RCC helpdesk verification procedure; and
+- a notice at the RCC support office.
+
+The kit displays the same fingerprint during installation and testing. No fingerprint may be added to this site until it has been independently verified and formally published by RCC.
+
+Signed packages improve distribution integrity, but they cannot make a compromised endpoint trustworthy. A local administrator may still replace its trust store, SSH executable or downloaded program.
+
+## User credentials and endpoint trust
+
+Where possible, users should prefer FIDO-backed SSH keys such as `ed25519-sk`. Private material remains in the hardware authenticator and normally requires explicit user presence. RCC client configuration uses `IdentitiesOnly yes` and `ForwardAgent no`. Users must not copy long-lived private keys between machines.
+
+| Endpoint class | Appropriate RCC access |
+|---|---|
+| Personally controlled endpoint | Normal SSH, VS Code and file transfer; RCC Connect and a FIDO-backed key are recommended |
+| Institutionally managed endpoint with restrictive policy | Portable RCC Connect, user-scoped files and rerunning repair after policy changes |
+| Endpoint administered by an untrusted or actively hostile party | Not suitable for sensitive RCC work; use an RCC-controlled workstation, virtual desktop, thin client, terminal or another trusted endpoint |
+
+SSH encryption does not protect an active session from an endpoint administrator who can replace the SSH client, record input, alter commands or capture displayed and downloaded data.
+
+## Migration sequence
+
+### 1. Prepare servers
+
+RCC retains each existing identity during transition, generates or retains a unique Ed25519 host key, signs it with the RCC host CA, includes every supported hostname as a certificate principal and validates every alias. Old and certified identities coexist initially.
+
+### 2. Publish RCC Connect
+
+RCC publishes portable Windows and macOS kits, optional user-scoped installers, the independently verifiable CA fingerprint, the repair utility, support documentation and a connection-test service.
+
+### 3. Run a coexistence period
+
+Coexistence lasts at least eight weeks and longer if significant active users have not migrated. Testing covers Windows, macOS, VS Code, command-line SSH and users returning after a long absence.
+
+### 4. Retire old identities
+
+After adoption is sufficient, RCC removes old server identities, retains unique certified host keys, keeps the portable repair kit permanently available and maintains a staffed support path. Users with the CA configuration see no warning. Others receive a hard failure and are directed to RCC Connect; they are never instructed to accept a changed identity manually.
+
+## Repair and support behavior
+
+The repair utility:
+
+1. verifies its package version;
+2. displays the RCC host-CA fingerprint;
+3. tests the selected SSH client;
+4. installs or refreshes the CA file and dedicated configuration;
+5. tests `rcc-shell` and VS Code;
+6. leaves the ordinary `known_hosts` file untouched; and
+7. produces a support report without private keys or passwords.
+
+Failures provide a short support code so users can ask for help without interpreting low-level SSH diagnostics.

docs/reference/access-ssh-vscode.md

@@ -21,6 +21,14 @@ shared accounts and shared credentials.
 
 ## Create an SSH key
 
+Where a compatible FIDO2 authenticator is available, prefer a hardware-backed key. Its private material remains on the authenticator and normally requires user presence:
+
+```bash
+ssh-keygen -t ed25519-sk -f ~/.ssh/id_rcc
+```
+
+Otherwise, create the dedicated software-backed Ed25519 key described below. Do not copy either type of private credential between computers.
+
 ### macOS and Linux
 
 Create a dedicated Ed25519 key and protect it with a strong passphrase:
@@ -57,9 +65,9 @@ normally stored under `C:\Users\<username>\.ssh\`.
 
 ## Configure the approved RCC target
 
-Use the host block supplied through the RCC rollout page or another trusted
-institutional channel. The public alias used in this course is
-`{{ ssh_alias }}`. A safe client block has this shape:
+Use the host block supplied through the RCC rollout page or another trusted institutional channel. During the host-identity migration, RCC will distribute **RCC Connect**: a portable kit with a dedicated RCC configuration, host-CA trust file and connection test. It does not modify or delete entries for unrelated services in the ordinary `known_hosts` file.
+
+Until the rollout page says RCC Connect is active, continue using the currently approved configuration. The public alias used in this course is `{{ ssh_alias }}`. A safe client block has this shape:
 
 ```sshconfig
 Host {{ ssh_alias }}
@@ -70,9 +78,7 @@ Host {{ ssh_alias }}
   ForwardAgent no
 ```
 
-Do not copy an old hostname from a colleague, disable host-key checking, or
-enable agent forwarding merely to make a connection work. Verify the published
-host-key fingerprint before the first connection.
+Do not copy an old hostname from a colleague, disable host-key checking or enable agent forwarding merely to make a connection work. Verify the published RCC host-CA fingerprint through an independent institutional channel before migration.
 
 Inspect the effective configuration without connecting:
 
@@ -90,15 +96,20 @@ ssh -v {{ ssh_alias }}
 Remove key material, usernames, local paths, and tokens before sharing a debug
 log with support.
 
+During or after migration, do not approve an unexpected SSH identity warning and do not delete host records merely to make the warning disappear. Close the client, run the RCC connection test and use its repair action. Report the generated support code if repair fails.
+
 ## Use VS Code Remote SSH
 
 1. Install Visual Studio Code and Microsoft's **Remote - SSH** extension.
 2. Confirm terminal SSH works first.
-3. Open **Remote Explorer** and select `{{ ssh_alias }}` from the SSH targets.
-4. Open only the project or source directory you need.
-5. Keep data, environment, cache, and generated-result directories out of
+3. If RCC Connect is active, run its test and repair action before opening VS Code. The kit selects its dedicated SSH configuration and, where necessary, its maintained SSH executable.
+4. Open **Remote Explorer** and select the approved RCC alias from the SSH targets.
+5. Open only the project or source directory you need.
+6. Keep data, environment, cache, and generated-result directories out of
    workspace-wide search.
 
+Do not manually accept an unexpected identity warning in VS Code. Close it and run the RCC connection test instead. See the [SSH host-identity policy](../policies/ssh-host-identity.md) for the architecture and rollout controls.
+
 VS Code uses `rg` for full-text search. A recursive search over large shared
 storage or an environment containing thousands of files can create substantial
 metadata load. Add generated trees to `.gitignore` or `.ignore`, for example:

docs/rollout/index.md

@@ -1,23 +1,30 @@
 # Upcoming RCC changes
 
-The rollout improves login routing, browser-based project data transfer, central service reliability and protected project websites.
+The rollout improves login routing, SSH server-identity verification, browser-based project data transfer, central service reliability and protected project websites.
 
 ## What most users need to do
 
 1. Read the final rollout date on this page.
 2. Complete the Class 1 readiness check.
-3. Update the SSH configuration only when the rollout notice says the new setting is active.
-4. Verify the published host fingerprint through the trusted institutional channel.
-5. Use the web transfer service with your own RCC account.
+3. Close VS Code and download RCC Connect only when this page says the new connection kit is active.
+4. Run `RCC-Test` and use the repair action if it finds stale or overwritten settings.
+5. Verify the RCC host-CA fingerprint through an independent trusted institutional channel.
+6. Reopen VS Code only after the test reports that the RCC connection is ready.
+7. Use the web transfer service with your own RCC account.
+
+Your RCC account, files, user SSH key and password do not change as part of the host-identity migration. RCC Connect keeps RCC trust in its own file and leaves ordinary `known_hosts` entries for GitHub, other clusters and unrelated services untouched.
+
+> **Do not approve an unexpected SSH identity warning.** Do not delete host records merely to make a connection work. Run RCC Connect or contact RCC support.
 
 Access from inside the hospital remains intentionally simple. Informational sites can open without login. Data transfer and active project applications identify the user with a password or passkey. External access uses additional authentication.
 
 ## For technical users
 
-The site provides bounded terminal checks, VS Code guidance, Slurm acceptance examples, Apptainer guidance and a protected web-application pattern. It intentionally does not expose infrastructure topology or administrative endpoints.
+The site provides bounded terminal checks, VS Code guidance, Slurm acceptance examples, Apptainer guidance and a protected web-application pattern. The [SSH host-identity policy](../policies/ssh-host-identity.md) documents the host-CA architecture, dedicated trust file, endpoint policy and phased migration without publishing private infrastructure credentials.
 
 ## Current staging values
 
 - Rollout date: **{{ rollout_date }}**
 - Documentation URL: **{{ production_url }}**
 - Support contact: **{{ support_contact }}**
+- RCC host-CA fingerprint: **{{ ssh_host_ca_fingerprint }}**