fix(ci): restore green main (workflow callers, type errors, coverage, hardening)

.github/workflows/ci.yml

@@ -35,23 +35,21 @@ jobs:
       coverage-threshold: 80
       source-directory: 'src'
       test-directory: 'tests'
-      enable-sonarcloud: true
-      sonarcloud-organization: 'ByronWilliamsCPA'
-      sonarcloud-project-key: 'ByronWilliamsCPA_foundry_unify'
-      enable-codecov: true
       run-integration-tests: true
       run-security-tests: true
       fail-on-llm-tags: false
-    secrets:
-      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   ci-gate:
     name: CI Gate
     runs-on: ubuntu-latest
     needs: [ci]
     if: always()
     steps:
+      - name: Harden the runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
       - name: Check CI results
         run: |
           if [ "${{ needs.ci.result }}" != "success" ]; then

.github/workflows/codecov.yml

@@ -38,6 +38,11 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ github.event.workflow_run.conclusion == 'failure' }}
     steps:
+      - name: Harden the runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
       - name: Report status
         run: |
           echo "## Coverage Upload Skipped" >> $GITHUB_STEP_SUMMARY

.github/workflows/dependency-review.yml

@@ -24,11 +24,16 @@ jobs:
     name: Dependency Review
     runs-on: ubuntu-latest
     steps:
+      - name: Harden the runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Dependency Review
-        uses: actions/dependency-review-action@v4
+        uses: actions/dependency-review-action@3b139cfc5fae8b618d3eae3675e383bb1769c019 # v4.5.0
         with:
           fail-on-severity: high
           # Deny copyleft and restrictive licenses (deny-list approach)

.github/workflows/fips-compatibility.yml

@@ -54,11 +54,16 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      - name: Harden the runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
         with:
           enable-cache: true
 
@@ -200,11 +205,16 @@ jobs:
     needs: fips-check
 
     steps:
+      - name: Harden the runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
         with:
           enable-cache: true
 

.github/workflows/pr-validation.yml

@@ -60,7 +60,7 @@ jobs:
           python-version: "3.12"
 
       - name: Install UV
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"
@@ -123,6 +123,11 @@ jobs:
     needs: [core-validation, dead-code, link-check]
     if: always()
     steps:
+      - name: Harden the runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
       - name: Check validation results
         run: |
           echo "## Dependency & Standards Validation" >> $GITHUB_STEP_SUMMARY

.github/workflows/reuse.yml

@@ -25,6 +25,11 @@ jobs:
     name: Check REUSE Compliance
     runs-on: ubuntu-latest
     steps:
+      - name: Harden the runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
@@ -48,6 +53,11 @@ jobs:
     name: Validate License Files
     runs-on: ubuntu-latest
     steps:
+      - name: Harden the runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 

.github/workflows/security-analysis.yml

@@ -41,7 +41,6 @@ jobs:
       run-codeql: true
       run-dependency-review: true
       run-bandit: true
-      run-safety: true
       run-osv: true
 
   security-gate-success:

.github/workflows/slsa-provenance.yml

@@ -56,7 +56,7 @@ jobs:
           python-version: "3.12"
 
       - name: Install UV
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
         with:
           enable-cache: true
 

.github/workflows/sonarcloud.yml

@@ -40,6 +40,11 @@ jobs:
     outputs:
       has-token: ${{ steps.check.outputs.has-token }}
     steps:
+      - name: Harden the runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
       - name: Check for SONAR_TOKEN
         id: check
         run: |
@@ -63,6 +68,11 @@ jobs:
     timeout-minutes: 15
 
     steps:
+      - name: Harden the runner
+        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        with:
+          egress-policy: audit
+
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
@@ -83,7 +93,6 @@ jobs:
         uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
         with:
           python-version: '3.12'
-          cache: 'pip'
 
       - name: Install UV
         if: steps.check-code.outputs.has-code == 'true'
@@ -133,7 +142,7 @@ jobs:
             -Dsonar.python.version=3.12
 
       - name: Check Quality Gate
-        uses: sonarsource/sonarqube-quality-gate-action@master
+        uses: sonarsource/sonarqube-quality-gate-action@cf038b0e0cdecfa9e56c198bbb7d21d751d62c3b # v1.2.0
         timeout-minutes: 5
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

README.md

@@ -34,13 +34,30 @@
 
 ## Overview
 
-OCR orchestration and layout analysis service for the Foundry RAG pipeline
-
-This project provides:
-- Core functionality for ocr orchestration and layout analysis service for the foundry rag pipeline
-- Production-ready code with comprehensive testing
-- Well-documented API and architecture
-- Security-first development practices
+Foundry Unify is the foundation library for an OCR orchestration and layout
+analysis service that will sit in front of the Foundry RAG pipeline. The OCR
+orchestration logic is still on the roadmap; what currently ships in
+`src/foundry_unify/` is the production scaffolding the orchestrator will be
+built on top of:
+
+- **FastAPI security middleware** (`foundry_unify.middleware.security`) —
+  OWASP-aligned security headers, in-memory rate limiting with burst control,
+  CORS, trusted-host, and an SSRF prevention middleware that blocks private
+  IPs, cloud metadata endpoints, and dangerous URL schemes.
+- **Request correlation middleware** (`foundry_unify.middleware.correlation`) —
+  propagates `X-Correlation-ID` / `X-Request-ID` / `X-Trace-ID` / `X-Span-ID`
+  via `contextvars`, with a structlog processor to add the IDs to every log
+  record.
+- **Structured logging** (`foundry_unify.utils.logging`) — structlog setup with
+  rich console output for development and JSON output for production, plus a
+  `log_performance` helper.
+- **Pydantic Settings** (`foundry_unify.core.config`) — environment-driven
+  configuration loaded from `FOUNDRY_UNIFY_*` variables.
+- **Centralised exception hierarchy** (`foundry_unify.core.exceptions`) —
+  typed errors (`ValidationError`, `AuthenticationError`, `APIError`, etc.)
+  with `to_dict()` for safe JSON responses.
+- **Kubernetes health endpoints** (`foundry_unify.api.health`) — `/health/live`,
+  `/health/ready`, `/health/startup` FastAPI router ready to mount.
 
 ## Features
 
@@ -75,32 +92,111 @@ pipx install uv
 
 ### Installation
 
+Foundry Unify is not yet published to PyPI. Install from source:
+
+```bash
+# Using uv (recommended)
+uv add git+https://github.com/ByronWilliamsCPA/Unify.git
+# or, for the FastAPI middleware stack:
+uv add "foundry-unify[api] @ git+https://github.com/ByronWilliamsCPA/Unify.git"
+
+# Using pip
+pip install git+https://github.com/ByronWilliamsCPA/Unify.git
+pip install "foundry-unify[api] @ git+https://github.com/ByronWilliamsCPA/Unify.git"
+```
+
+For local development, clone the repository and install all extras:
+
 ```bash
-# Clone repository
 git clone https://github.com/ByronWilliamsCPA/Unify.git
-cd foundry_unify
+cd Unify
 
 # Install dependencies (includes dev tools - REQUIRED for development)
 uv sync --all-extras
-# Install with ML dependencies
-uv sync --all-extras,ml
 
 # Setup pre-commit hooks (required)
 uv run pre-commit install
 ```
 
 ### Basic Usage
 
+Wire the middleware, logging, and health endpoints into a FastAPI app
+(requires the `[api]` extra):
+
 ```python
-# Import and use the package
-from foundry_unify import YourModule
+from fastapi import FastAPI
+
+from foundry_unify.api.health import router as health_router
+from foundry_unify.core.config import settings
+from foundry_unify.middleware import (
+    CorrelationMiddleware,
+    add_security_middleware,
+)
+from foundry_unify.utils.logging import get_logger, setup_logging
+
+# Configure structured logging (JSON in production, rich console in dev).
+setup_logging(
+    level=settings.log_level,
+    json_logs=settings.json_logs,
+    include_timestamp=settings.include_timestamp,
+    include_correlation=True,
+)
+logger = get_logger(__name__)
+
+app = FastAPI(title="foundry-unify")
+
+# Correlation must be added first so subsequent middleware can log with IDs.
+app.add_middleware(CorrelationMiddleware)
+
+# Security headers, CORS, rate limiting, SSRF prevention.
+add_security_middleware(
+    app,
+    enable_https_redirect=False,         # Set True behind TLS-terminating proxies.
+    enable_rate_limiting=True,
+    enable_ssrf_prevention=True,
+    allowed_origins=["https://example.com"],
+    allowed_hosts=["api.example.com"],
+    rate_limit_rpm=100,
+)
+
+# Kubernetes probes at /health/live, /health/ready, /health/startup.
+app.include_router(health_router)
+
+
+@app.get("/")
+async def root() -> dict[str, str]:
+    logger.info("root_called")
+    return {"status": "ok"}
+```
+
+Raise typed exceptions from the centralised hierarchy:
 
-# Example: Create an instance and use it
-module = YourModule()
-result = module.process()
-print(result)
+```python
+from foundry_unify.core.exceptions import ValidationError
+
+raise ValidationError(
+    "Invalid email format",
+    field="email",
+    value="not-an-email",
+)
+# ValidationError.to_dict() -> JSON-serialisable error payload.
 ```
 
+### Configuration
+
+Settings load from environment variables with the `FOUNDRY_UNIFY_` prefix
+(see `src/foundry_unify/core/config.py`). All variables are optional.
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `FOUNDRY_UNIFY_LOG_LEVEL` | `DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` | `INFO` | Application log level. |
+| `FOUNDRY_UNIFY_JSON_LOGS` | bool | `false` | Emit JSON logs (production) instead of rich console output. |
+| `FOUNDRY_UNIFY_INCLUDE_TIMESTAMP` | bool | `true` | Include ISO-8601 timestamps in log records. |
+
+`Settings` is a `pydantic_settings.BaseSettings` subclass and also reads from
+a `.env` file when one is present. Extra unrecognised variables are ignored
+(`extra="ignore"`).
+
 ## Supply Chain Security
 
 This project implements enterprise-grade supply chain security with a multi-tier package index strategy and centralized secrets management.