feat: integrate FiberLab application and Guardian system

.github/workflows/ci.yml

@@ -1,3 +1,4 @@
+
 name: FiberLab CI
 
 on:
@@ -30,8 +31,10 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install Ruff
-        run: python -m pip install --upgrade ruff
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt ruff
 
       - name: Run Ruff lint
         run: ruff check .
@@ -55,7 +58,7 @@ jobs:
       - name: Install project dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          python -m pip install -r requirements.txt
 
       - name: Run test suite
         run: python -m pytest -v

SECURITY.md

@@ -0,0 +1,64 @@
+# FiberLab Guardian — Security Notes
+
+## 1. Purpose
+
+FiberLab Guardian inspects candidate code changes, validates module contracts, prepares an isolated integration workspace, and runs permitted quality checks.
+
+It is designed as a project-level code inspection and integration assistant. It is not a hardened security sandbox.
+
+## 2. Implemented Protections
+
+The integration engine currently implements the following protections:
+
+- Rejects absolute candidate paths.
+- Rejects candidate paths containing `..` traversal components.
+- Checks candidate path components for symbolic links.
+- Resolves candidate paths and verifies that they remain within the candidate root.
+- Checks the destination path for an existing symbolic link before path resolution.
+- Creates integration workspaces separately from the original project.
+- Excludes Git metadata, virtual environments, caches, and other configured directories from workspace copies.
+
+## 3. Known Limitations
+
+### 3.1 Time-of-Check to Time-of-Use (TOCTOU)
+
+Candidate path validation, containment checks, and file copying are separate filesystem operations.
+
+A concurrent local process could modify a validated candidate or destination path between these operations. This may allow filesystem access outside the intended roots.
+
+**Status:** Known and accepted limitation for the current project scope.
+
+**Severity:** Medium.
+
+**Mitigation:** Guardian should only operate on trusted local workspaces. Stronger descriptor-relative filesystem operations and race-resistant copying may be considered in a future security-hardening phase.
+
+### 3.2 No OS-Level Execution Sandbox
+
+The integration workspace is a separate project copy, not an operating-system security boundary.
+
+Subprocess timeouts limit execution duration but do not prevent filesystem access, network access, or other potentially unsafe operations.
+
+Guardian must not execute untrusted pull-request code in the normal inspection workflow.
+
+## 4. Pull Request Inspection Policy
+
+- Download candidate files from the exact pull-request commit.
+- Perform static inspection before integration.
+- Do not execute untrusted pull-request code.
+- Disable quality-check execution for untrusted PR candidates.
+- Require human review before accepting or merging changes.
+
+## 5. Future Security Improvements
+
+Potential future improvements include:
+
+- Race-resistant filesystem operations.
+- OS-level sandboxing for untrusted code execution.
+- More comprehensive filesystem permission checks.
+- Additional security-focused automated tests.
+
+## 6. Security Review Disclaimer
+
+Guardian reports are automated engineering assessments. A passing report does not guarantee that code is free from vulnerabilities, constitute security certification, or approve a pull request for merging.
+
+Human review remains mandatory.

app.py

@@ -0,0 +1,74 @@
+"""FiberLab Streamlit application entry point."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from pages.attenuation_laboratory import render as render_attenuation_laboratory
+from pages.fiber_explorer import render as render_fiber_explorer
+from pages.guardian_dashboard import render as render_guardian
+from pages.home import render as render_home
+from pages.signal_propagation import render as render_signal_propagation
+
+PAGE_DEFINITIONS = (
+    {
+        "render": render_home,
+        "title": "FiberLab",
+        "icon": ":material/home:",
+        "url_path": "home",
+        "default": True,
+    },
+    {
+        "render": render_fiber_explorer,
+        "title": "Fiber Explorer",
+        "icon": ":material/explore:",
+        "url_path": "fiber-explorer",
+    },
+    {
+        "render": render_attenuation_laboratory,
+        "title": "Attenuation Laboratory",
+        "icon": ":material/science:",
+        "url_path": "attenuation-laboratory",
+    },
+    {
+        "render": render_signal_propagation,
+        "title": "Signal Propagation",
+        "icon": ":material/graphic_eq:",
+        "url_path": "signal-propagation",
+    },
+    {
+        "render": render_guardian,
+        "title": "Guardian",
+        "icon": ":material/shield:",
+        "url_path": "guardian",
+    },
+)
+
+
+def build_navigation():
+    """Build the native Streamlit navigation entries."""
+    return st.navigation(
+        [
+            st.Page(
+                definition["render"],
+                title=definition["title"],
+                icon=definition["icon"],
+                url_path=definition["url_path"],
+                default=definition.get("default", False),
+            )
+            for definition in PAGE_DEFINITIONS
+        ],
+        position="sidebar",
+    )
+
+
+def main() -> None:
+    """Configure and render the Streamlit application."""
+    st.set_page_config(page_title="FiberLab", page_icon="🔬", layout="wide")
+
+    navigation = build_navigation()
+    navigation.run()
+
+
+if __name__ == "__main__":
+    main()

components/page_layout.py

@@ -0,0 +1,17 @@
+"""Reusable page layout components for FiberLab."""
+
+import streamlit as st
+
+
+def render_page_header(title: str, caption: str, description: str) -> None:
+    """Render a consistent header across laboratory pages."""
+    st.title(title)
+    st.caption(caption)
+    st.write(description)
+    st.divider()
+
+
+def render_workspace(message: str) -> None:
+    """Render a standard laboratory workspace section."""
+    st.subheader("Laboratory workspace")
+    st.info(message)

components/result_display.py

@@ -0,0 +1,16 @@
+"""Reusable result display components for FiberLab."""
+
+import streamlit as st
+
+
+def render_result_metrics(results: dict[str, str]) -> None:
+    """Display simulation results as a row of metrics."""
+    if not results:
+        st.info("No simulation results available yet.")
+        return
+
+    columns = st.columns(len(results))
+
+    for column, (label, value) in zip(columns, results.items()):
+        with column:
+            st.metric(label=label, value=value)

components/validation.py

@@ -0,0 +1,39 @@
+"""Input validation utilities for FiberLab."""
+
+import math
+
+
+def validate_positive(value: float, name: str) -> None:
+    """Ensure a value is finite and greater than zero."""
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+        or value <= 0
+    ):
+        raise ValueError(f"{name} must be a finite positive number.")
+
+
+def validate_non_negative(value: float, name: str) -> None:
+    """Ensure a value is finite and non-negative."""
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+        or value < 0
+    ):
+        raise ValueError(f"{name} must be a finite non-negative number.")
+
+
+def validate_refractive_indices(
+    n_core: float,
+    n_cladding: float,
+) -> None:
+    """Validate core and cladding refractive indices."""
+    validate_positive(n_core, "Core refractive index")
+    validate_positive(n_cladding, "Cladding refractive index")
+
+    if n_core <= n_cladding:
+        raise ValueError(
+            "Core refractive index must be greater than cladding refractive index."
+        )