🛰️ Starlight Protocol

What is the Starlight Protocol?

The Starlight Protocol decouples intent from environment. Your test scripts describe goals; autonomous Sentinels handle the chaos.

// Traditional: Handle EVERYTHING yourself
if (await page.$('.cookie-banner')) await page.click('.dismiss');
if (await page.$('.popup')) await page.click('.close');
await page.click('#submit');

// Starlight: Express INTENT only
await hub.send({ goal: 'Submit Form' });
// Sentinels automatically clear obstacles

🏗️ Architecture

| Component | Role | |-----------|------| | Hub | Central orchestrator, manages Playwright browser | | JWT Handler | Authentication & authorization system | | Schema Validator | Input validation & message verification | | PII Redactor | Data protection & privacy compliance | | Pulse Sentinel | Monitors DOM/Network stability | | Janitor Sentinel | Clears popups, modals, banners | | Vision Sentinel | AI-powered obstacle detection (Moondream) | | Data Sentinel | Context extraction & injection |

🚀 Quick Start

Prerequisites

• Node.js 18+ & Python 3.9+
• Ollama (optional, for Vision)

Install

git clone https://github.com/starlight-protocol/starlight.git
cd cba
npm install
pip install -r requirements.txt
npx playwright install chromium

Run

# One command launches everything
node bin/starlight.js test/intent_portfolio_v2.js --headless

Mission Control (GUI)

node launcher/server.js
# Open http://localhost:3000

Multi-Browser Support (Phase 14.1)

# Run with Firefox
HUB_BROWSER_ENGINE=firefox node bin/starlight.js test/intent_portfolio_v2.js

# Run with WebKit (Safari engine)
HUB_BROWSER_ENGINE=webkit node bin/starlight.js test/intent_portfolio_v2.js

# Or configure in config.json:
{
  "hub": {
    "browser": { "engine": "firefox" }
  }
}

Supported Browsers:

• Chromium (default) - Full CDP access, shadow DOM piercing
• Firefox - Mozilla engine, standard DOM APIs
• WebKit - Safari engine, iOS compatibility testing

Install all browsers:

npx playwright install chromium firefox webkit

Mobile Emulation (Phase 14.2)

# Run on iPhone 14 Pro Max
HUB_DEVICE="iPhone 14 Pro Max" node bin/starlight.js test/intent_saucedemo.js

# Run on Pixel 7
HUB_DEVICE="Pixel 7" node bin/starlight.js test/intent_saucedemo.js

# Or configure in config.json:
{
  "hub": {
    "device": "iPhone 14 Pro Max"
  }
}

Verified: Full 12-step SauceDemo checkout flow passes autonomously. See test/intent_saucedemo.js.

🛰️ The Protocol

All communication uses JSON-RPC 2.0:

| Method | Purpose | |--------|---------| | starlight.intent | Issue a goal or command | | starlight.pre_check | Hub → Sentinels handshake | | starlight.clear | Sentinel approves action | | starlight.wait | Sentinel vetoes (retry later) | | starlight.hijack | Sentinel takes browser control | | starlight.resume | Sentinel releases control |

📄 Full Specification

✨ Key Features

| Feature | Description | |---------|-------------| | JWT Authentication | Secure token-based authentication with timing-safe verification | | Input Validation | Comprehensive JSON schema validation for all protocol messages | | PII Protection | Automatic detection and redaction of sensitive data (emails, passwords, credit cards) | | Self-Healing Selectors | Learns alternatives when selectors fail | | Animation Tolerance | Handles CSS animations without blocking | | No-Code Recorder | Record tests by clicking through your site | | Visual Sentinel Editor | Create custom Sentinels without code | | Shadow DOM Support | Pierces web component boundaries | | Webhook Alerts | Slack/Teams notifications | | Upload Automation | Native file upload support (selector & semantic) | | ROI Dashboard | Quantifies time saved |

🛠️ SDKs & Language Support

The Starlight Protocol is language-agnostic. The Hub (Node.js) communicates with Sentinels via WebSocket, regardless of what language they're written in.

Pre-Built Sentinels (Python)

The following production-ready Sentinels are included and used by Mission Control:

| Sentinel | Location | Description | |----------|----------|-------------| | Pulse Sentinel | sentinels/pulse_sentinel.py | Waits for page stability | | Janitor Sentinel | sentinels/janitor.py | Clears popups, modals, banners | | Vision Sentinel | sentinels/vision_sentinel.py | AI-powered obstacle detection | | Data Sentinel | sentinels/data_sentinel.py | Context extraction | | A11y Sentinel | sentinels/a11y_sentinel.py | Accessibility monitoring | | PII Sentinel | sentinels/pii_sentinel.py | Sensitive data protection | | Responsive Sentinel | sentinels/responsive_sentinel.py | Viewport monitoring |

# These are what Mission Control launches
python sentinels/janitor.py

SDKs for Custom Sentinel Development

Build your own Sentinels in your preferred language:

Python SDK (Mature)

from sdk.starlight_sdk import SentinelBase

class MySentinel(SentinelBase):
    def __init__(self):
        super().__init__("MySentinel", priority=5)
        self.selectors = [".my-obstacle"]
    
    async def on_pre_check(self, params, msg_id):
        await self.send_clear(msg_id)

if __name__ == "__main__":
    import asyncio
    asyncio.run(MySentinel().start())

Go SDK (New - v4.0.0)

⚠️ Note: This SDK provides building blocks. Pre-built Sentinels (Janitor, Pulse, etc.) are NOT included - use Python versions or build your own.

// go-sdk/examples/simple_sentinel/main.go
sentinel := starlight.NewSentinel("MySentinel", 5)
sentinel.OnPreCheck = func(params starlight.PreCheckParams, msgID string) error {
    return sentinel.SendClear(msgID)
}
sentinel.Start(ctx, "ws://localhost:8080")

📦 Location: go-sdk/ | 📄 Go SDK README

Java SDK (New - v4.0.0)

⚠️ Note: This SDK provides building blocks. Pre-built Sentinels (Janitor, Pulse, etc.) are NOT included - use Python versions or build your own.

// java-sdk/src/.../examples/SimpleSentinel.java
Sentinel sentinel = new Sentinel("MySentinel", 5)
    .withSelectors(List.of(".popup"))
    .onPreCheck((params, ctx) -> ctx.clear());

sentinel.start("ws://localhost:8080");

📦 Location: java-sdk/ | 📄 Java SDK README

JavaScript SDK (Built-in)

const { IntentRunner } = require('./sdk/intent_runner');

const runner = new IntentRunner('ws://localhost:8080');
await runner.clickGoal('Submit');

SDK Comparison

| Feature | Python | Go | Java | JavaScript | |---------|--------|-----|------|------------| | Pre-built Sentinels | ✅ Yes | ❌ No | ❌ No | ❌ No | | Mission Control Support | ✅ Yes | ❌ Manual | ❌ Manual | ✅ Intents | | JWT Authentication | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | | Auto-Reconnect | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | | Production Ready | ✅ Yes | 🔶 Alpha | 🔶 Alpha | ✅ Yes |

🛒 Available Sentinels

The following Sentinels are included and ready to use:

| Sentinel | File | Description | |----------|------|-------------| | Pulse | sentinels/pulse_sentinel.py | Monitors DOM mutations and network activity for stability | | Janitor | sentinels/janitor.py | Clears popups, modals, overlays, cookie banners | | Vision | sentinels/vision_sentinel.py | AI-powered visual obstacle detection (Moondream/Ollama) | | Data | sentinels/data_sentinel.py | Context extraction and injection | | A11y | sentinels/a11y_sentinel.py | Accessibility monitoring and WCAG compliance | | PII | sentinels/pii_sentinel.py | Sensitive data detection and redaction | | Responsive | sentinels/responsive_sentinel.py | Viewport and responsive layout monitoring |

Create Your Own Sentinel

# Use CLI to scaffold a new Sentinel
python cli/main.py create "My Custom Sentinel"

# Or use the Visual Editor (no-code)
# Open Mission Control → Click "Create Sentinel"

Coming Soon: Sentinel Marketplace

🚧 Planned for Phase 3: A community marketplace for sharing and installing Sentinels.

✅ Test Coverage

# Run all unit tests (100% coverage)
node test/run_all_tests.js

| Component | Test File | Status | |-----------|-----------|--------| | IntentRunner | test_intent_runner.js | ✅ | | SentinelSDK | test_sentinel_sdk.js | ✅ | | HubCore | test_hub_core.js | ✅ | | BrowserAdapter | test_browser_adapter.js | ✅ | | ShadowUtils | test_shadow_utils.js | ✅ | | Warp | test_warp.js | ✅ | | Telemetry | test_telemetry.js | ✅ | | CLI | test_cli.js | ✅ | | + 4 more | ... | ✅ |

📚 Documentation

| Document | Description | |----------|-------------| | 🔒 Security Guide | Security architecture & best practices | | 📖 Book | Comprehensive guide | | 📄 Specification | Formal protocol standard | | 📋 User Guide | Getting started | | ⚙️ Technical Guide | SDK & configuration | | 🛡️ Security Configuration | Security settings reference | | 📊 Compliance Guide | GDPR/HIPAA compliance | | 🧪 Security Testing | Security testing procedures | | 🗺️ Roadmap | Future plans | | 📝 Changelog | Version history |

🔒 Security Features

Starlight Protocol includes enterprise-grade security features:

Authentication & Authorization

• ✅ JWT-based authentication with HS256 signing
• ✅ Configurable token expiration (default: 3600s)
• ✅ Timing-safe signature verification
• ✅ Token refresh mechanism

Input Validation & Protection

• ✅ Comprehensive JSON schema validation for all protocol messages
• ✅ Field type checking, pattern matching, and length limits
• ✅ CSS selector injection prevention
• ✅ XSS protection with HTML escaping

Data Protection & Privacy

• ✅ Automatic PII detection and redaction
• ✅ AES-256-GCM encryption for sensitive data
• ✅ Secure logging with automatic PII redaction
• ✅ Compliance modes: alert, block, or redact

Security Configuration

{
    "security": {
        "jwtSecret": "your-secret-key",
        "tokenExpiry": 3600,
        "piiRedaction": true,
        "ssl": {
            "enabled": false,
            "keyPath": null,
            "certPath": null
        }
    }
}

📄 Security Guide - Complete security documentation

🐳 Docker

docker-compose up --build

📖 Blog Series

• Part 1: The Inner Workings
• Part 2: Mission Control & ROI
• Part 3: The Autonomous Era

📄 License

MIT License - LICENSE