CyberSim-OS/README.md

# CyberSim OS

**Phase 2.5: Localization, Corporate Branding, and Immersive Login**

CyberSim OS is an offline-first, browser-native cybersecurity simulation platform designed for enterprise organizations and end-user learners. Learners enter a convincing fictional enterprise workstation, perform routine workplace activities, investigate ambiguous communications, encounter realistic threats (credential harvesting, malicious attachments) alongside legitimate false flags, receive a multi-axis behavioral after-action assessment, and earn cryptographically verifiable completion certificates (`*.cybercert`).

**Phase 2.5** adds **organizational readiness** through runtime multilingual localization, configuration-driven corporate branding, an immersive workstation login experience, learner first-name personalization, and cross-locale cryptographic verification.

---

## Key Features

- **Immersive CyberSim OS Login**: Fictional enterprise workstation login and dynamic network/workplace selection without requesting passwords or sensitive employee credentials.
- **Runtime Multilingual & Localization (I18n)**:
  - CyberSim OS user interface localization with deterministic fallback chain (Selected Locale $\to$ Deployment Default Locale $\to$ English $\to$ `[missing: key]`).
  - Working demonstration locales: English (`en`) and Spanish (`es`).
  - Independent scenario content localization (`scenarios/<id>/locales/<lang>.json`).
- **Configuration-Driven Corporate Branding**:
  - Customize organization name, short name, logo, desktop wallpaper, accent color, and service desk name via `src/config/deployment.json`.
  - Automatic fallback to CyberSim default enterprise theme when branding fields are omitted.
  - Preserves simulation safety boundaries (CyberSim identity remains visible).
- **Learner Personalization**:
  - First-name input is passed into scenario state (`learner.firstName`).
  - Safe template interpolation (`{{learner.firstName}}`, `{{learner.name}}`) in emails, notifications, alerts, web pages, documents, and certificates with strict HTML entity escaping.
- **Scenario-Driven Architecture**: Complete simulations are defined through declarative JSON scenario packages without application source code modification.
- **Verifiable Cryptographic Certificates**:
  - Canonical Web Crypto SHA-256 scenario fingerprinting unaffected by display translations.
  - Portable, structured `*.cybercert` JSON credential export.
  - Standalone offline certificate validator (`verify.html`) supporting localized verification.
- **100% Offline-First & Zero Dependencies**: Runs directly from any static web server, GitHub Pages, or the bundled `launcher.py` with zero npm/node/external CDN requirements.

---

## Quick Start

### Option 1: Standalone Local Launcher (Python 3)
Run the lightweight local launcher to start the server at `http://127.0.0.1:8080`:

```bash
python launcher.py
```

Your default web browser will open automatically with the CyberSim OS Login interface.

### Option 2: Static Web Server
Serve the `src/` directory with any static HTTP server:

```bash
cd src
python -m http.server 8000
```
Open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser.

---

## Deployment Configuration

Deployments are customized via `src/config/deployment.json`:

```json
{
  "organization": {
    "name": "NexaCore Technologies",
    "shortName": "NexaCore",
    "logo": "",
    "wallpaper": "",
    "accentColor": "#2563eb",
    "supportName": "NexaCore Service Desk"
  },
  "localization": {
    "defaultLocale": "en",
    "enabledLocales": ["en", "es"]
  },
  "scenarios": [
    {
      "id": "nexacore-orientation",
      "path": "scenarios/nexacore-orientation/scenario.json",
      "networkName": "NexaCore Corporate",
      "networkDescription": "Corporate Workplace Network",
      "networkIcon": "corporate",
      "supportedLocales": ["en", "es"]
    },
    {
      "id": "quickstart-example",
      "path": "scenarios/quickstart-example/scenario.json",
      "networkName": "Meridian Health Partners",
      "networkDescription": "Clinical & Administrative Network",
      "networkIcon": "health",
      "supportedLocales": ["en", "es"]
    }
  ]
}
```

---

## Included Scenarios

| Scenario | Description | Supported Languages |
|----------|-------------|---------------------|
| **NexaCore Orientation** (`nexacore-orientation`) | Full-featured scenario: 5 emails, 3 web pages, 3 documents, 6 scoring categories, credential phishing + malicious attachment threats, 2 false flags. | English (`en`), Español (`es`) |
| **Meridian Health Quickstart** (`quickstart-example`) | Minimal scenario: 3 emails, 1 web page, 2 documents, 3 scoring categories, 1 credential phishing threat. | English (`en`), Español (`es`) |

---

## Scenario Localization & Personalization

Scenarios declare supported languages in `scenario.json`:

```json
{
  "formatVersion": "1.0",
  "id": "my-scenario",
  "supportedLocales": ["en", "es"],
  "login": {
    "networkName": "My Enterprise",
    "networkDescription": "Corporate Network",
    "networkIcon": "corporate"
  }
}
```

Scenario translations are placed in `locales/<lang>.json` (e.g. `locales/es.json`):

```json
{
  "title": "Título en español",
  "description": "Descripción en español",
  "messages": {
    "email_welcome": {
      "sender": "Nombre del Remitente",
      "subject": "Asunto traducido",
      "body": "Hola {{learner.firstName}},\n\n¡Bienvenido a su turno!"
    }
  }
}
```

---

## Automated Tests

Run the headless automated test suite with Node.js:

```bash
node tests/run_tests.js
```

---

## Devlog Validation

Run the validation suite to ensure `.labyricorn/` records and devlog entries adhere to the schema:

```bash
python devlog_editor.py --validate
```

---

## License

MIT License. See `LICENSE` for details.