scswp 0.1.0

A production-grade, continuously authenticated, multi-client secure file workspace protocol.
_{Built by Sripad Hebbar & Sharan Hiremani}

Table of Contents

• Overview
• Why SCSWP?
• Features
• Architecture
• Cryptographic Design
• Protocol Lifecycle
• Installation
• Quick Start
• Project Structure
• OpCode Reference
• Error Codes
• Configuration
• IETF Internet Draft
• Contributing
• Authors
• License

Overview

SCSWP (Secure Collaborative State Workspace Protocol) is a stateful, continuously authenticated protocol that enables multiple clients — operating from geographically separated, heterogeneous networks — to securely access and collaboratively manage a shared file workspace hosted on a central authoritative server.

Unlike traditional approaches that address security and collaboration as separate concerns, SCSWP unifies them into a single, coherent protocol with continuous trust evaluation as a first-class requirement.

Why SCSWP?

Features

Security

• Mutual X.509 Authentication — Server CA (ECDSA P-384) issues and validates client certificates.
• ECDH Ephemeral Key Exchange — Fresh P-384 key pair per session; no long-term symmetric keys.
• Three-Level Key Hierarchy — K1 (identity) → K2 (authorization) → K3 (active session subkeys).
• AES-256-GCM Envelopes — File payloads and control messages encrypted with per-purpose subkeys.
• HMAC-SHA-256 Signed Trust Signals — Every D/N/P/S update is authenticated.
• Key-Dissolving Bootstrap — Single-use, time-limited tokens; irrevocably consumed on first use.
• Epoch-Based Key Rotation — K3 rotated on trust threshold breach, explicit rekey, or DNAC recovery.

Collaboration

• Mandatory Server-Side Locking — Exclusive write locks prevent undefined concurrent writes.
• Optimistic Version Control — Five conflict resolution policies: REJECT, RETRY, MERGE, REBASE, CONFLICT VERSION.
• Operation Idempotency — UUID-keyed deduplication prevents duplicate writes on reconnection.
• DNAC Session Recovery — Cryptographic hash-chain recovery; no full re-authentication on transient disconnects.

Operations

• Hash-Chained Audit Ledger — Tamper-evident, exportable (CSV) audit log of every operation.
• Priority Worker Pool — Min-heap scheduler with anti-starvation wait-boost and resource-debt fairness.
• SQLite Persistence — Full session, version history, and idempotency records via SQLAlchemy.
• Health Monitoring — CPU, memory, and connection metrics via psutil.
• Server-Sent Events (SSE) — Real-time workspace update notifications to dashboard.

Architecture

Client Request
      │
      ▼
┌─────────────────────┐
│   IDENTITY PLANE    │  X.509 certificate validation
│                     │  Key-Dissolving bootstrap
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│    TRUST PLANE      │  D/N/P/S context evaluation (every 5s)
│                     │  Trust Score [0–100] with HMAC-signed signals
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   SECURITY PLANE    │  K1 / K2 / K3 key hierarchy
│                     │  AES-256-GCM envelope + HMAC-SHA-256
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ AUTHORIZATION PLANE │  Capability bitmask ACL
│                     │  Per-client, per-workspace
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   RESOURCE PLANE    │  Min-heap worker pool (N=8)
│                     │  Backpressure + resource-debt fairness
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  WORKSPACE PLANE    │  Exclusive write locks
│                     │  Optimistic version control
│                     │  UUID idempotency
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   STORAGE PLANE     │  SQLite file I/O + version history
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ AUDIT / STATE PLANE │  Hash-chained audit ledger
│                     │  DNAC chain advancement
└─────────────────────┘
           │
           ▼
     Client Response

Cryptographic Design

                 ECDH (P-384)
                      │
                      ▼
              IKM (shared secret)
                      │
                      ▼
         HKDF-SHA256 ("SCSWP_K1:" ‖ session_id)
                      │
                      ▼
              ┌───────┴───────┐
              K1 (Session Root Key)
              └───────┬───────┘
                      │
         HKDF-SHA256 ("SCSWP_K2:" ‖ workspace ‖ session_id)
                      │
                      ▼
              ┌───────┴───────┐
              K2 (Workspace Auth Key)
              └───────┬───────┘
                      │
         HKDF-SHA256 ("SCSWP_K3:epoch:" ‖ epoch, salt=epoch_nonce)  [96 bytes]
                      │
          ┌───────────┼───────────┐
          │           │           │
          ▼           ▼           ▼
    K3.auth_key  K3.ctrl_key  K3.payload_key
    (HMAC-SHA256) (AES-256-GCM) (AES-256-GCM)
    D/N/P/S sigs  control msgs  file payloads

Protocol Lifecycle

UNREGISTERED ──[OP_PROVISION]──► BOOTSTRAP
                                      │
                              [OP_AUTH / ECDH]
                                      │
                                      ▼
                               AUTHENTICATING
                                      │
                               [K1 derived]
                                      │
                                      ▼
                               [K2, K3 derived]
                                      │
                      ┌───────────────▼──────────────────┐
                      │            ACTIVE                 │◄──────────┐
                      └──┬──────────────┬────────────┬───┘           │
                         │              │             │               │
                  trust<REKEY    trust<=SUSPEND   disconnect          │
                         │              │             │               │
                         ▼              ▼             ▼               │
                      REKEYING     SUSPENDED    DISCONNECTED          │
                      (new K3)                       │                │
                         │                     DNAC valid?            │
                         │                    ┌────┴────┐             │
                         │                   YES        NO            │
                         │                    │          │            │
                         │                    ▼          ▼            │
                         │               RECOVERED  [re-auth]         │
                         └──────────────────►┴────────────────────────┘

Installation

From PyPI

pip install scswp

From Source

git clone https://github.com/sripadkarthik/scswp.git
cd scswp
pip install -e ".[dev]"

Windows (Batch Installer)

install_deps.bat

Requirements

• Python 3.10+
• See requirements.txt for full dependency list.

Quick Start

1. Start the Server

scswp-server

The server will:

1. Generate a CA key pair and self-signed X.509 certificate.
2. Bind to a dynamic port and print the WebSocket URL.
3. Open the admin dashboard in your browser.

2. Register a Client (via Admin Dashboard)

In the dashboard:

1. Click "Add Client".
2. Enter a client name and workspace folder.
3. Copy the generated bootstrap token (valid for 24 hours, single-use).

3. Start a Client

scswp-client

Enter the server URL and the bootstrap token when prompted. The client will:

1. Complete the Key-Dissolving bootstrap.
2. Perform mutual X.509 authentication.
3. Execute ECDH key exchange and derive K1 → K2 → K3.
4. Begin sending D/N/P/S trust signals.
5. Open the workspace UI.

Project Structure

scswp/
├── src/
│   └── scswp/
│       ├── server/
│       │   ├── __init__.py
│       │   ├── server_main.py       # FastAPI hub, WebSocket handler, trust engine
│       │   ├── worker_pool.py       # Min-heap priority scheduler
│       │   ├── database.py          # SQLAlchemy / SQLite persistence layer
│       │   ├── acl.py               # Capability-based access control
│       │   ├── state_manager.py     # Session + DNAC state management
│       │   ├── builder.py           # X.509 certificate builder
│       │   └── static/
│       │       ├── index.html       # Server admin dashboard
│       │       └── style.css        # Glassmorphism UI
│       ├── client/
│       │   ├── __init__.py
│       │   ├── client_main.py       # Client entry point + UI
│       │   ├── protocol_worker.py   # SCSWP protocol state machine
│       │   └── static/              # Client workspace UI
│       └── shared/
│           ├── __init__.py
│           ├── opcodes.py           # OpCode and error code registry
│           └── crypto_utils.py      # ECDH, AES-GCM, HKDF, HMAC utilities
├── tests/
│   ├── test_crypto.py
│   ├── test_worker_pool.py
│   └── test_protocol.py
├── draft-hebbar-hiremani-scswp-secure-collaborative-workspace-00.txt
├── draft-hebbar-hiremani-scswp-secure-collaborative-workspace-00.xml
├── pyproject.toml
├── README.md
├── LICENSE
├── CHANGELOG.md
├── requirements.txt
└── install_deps.bat

OpCode Reference

Error Codes

Configuration

Key protocol parameters (configurable in server_main.py):

Trust Score Penalties

IETF Internet Draft

This repository includes the formal protocol specification as an IETF Internet Draft:

• Plain Text: draft-hebbar-hiremani-scswp-secure-collaborative-workspace-00.txt
• RFC XML (v3): draft-hebbar-hiremani-scswp-secure-collaborative-workspace-00.xml

The draft covers:

• Normative protocol message format and OpCode space.
• Cryptographic procedures for K1, K2, and K3 derivation.
• DNAC construction and validation procedure.
• File-state record and concurrency control rules.
• Audit record format and hash-chain construction.
• Security considerations and threat analysis.
• IANA registrations.

Contributing

Contributions are welcome! Please:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/your-feature.
3. Commit your changes: git commit -m "feat: add your feature".
4. Push to the branch: git push origin feature/your-feature.
5. Open a Pull Request.

Development Setup

git clone https://github.com/sripadkarthik/scswp.git
cd scswp
pip install -e ".[dev]"
pytest

Code Style

black src/ tests/
isort src/ tests/
mypy src/

Authors

License

This project is licensed under the MIT License — see the LICENSE file for details.