Module-Core Communication Protocol

Version: 1.0 | Status: Normative document — implement strictly by it

Overview

Module and core communicate only via HTTP on localhost. No other channels. Direct module access to SQLite, /secure/, or other modules is prohibited and blocked at Docker network level.

1. Module Lifecycle & Token Issuance

Full installation cycle:

Unpack ZIP → /var/lib/selena/modules/<name>/
Validate manifest.json (name, version, port, permissions)
Sandbox test (docker run --rm, timeout 60s)
Generate module_token (secrets.token_urlsafe(48)) — store only sha256 hash
Generate webhook_secret (secrets.token_hex(32))
Write .env.module file (deleted after docker run)
Launch container via DockerSandbox
Wait for GET /health → 200 (timeout 30s)
SDK auto-subscribes to events from manifest

2. Bearer Token Authentication

Authorization: Bearer <module_token>
# Core verifies: sha256(token) → lookup in modules table
# Permission check: require_permission("device.read")

Rate limiting: 100 req/sec per token. Token invalidated only on module uninstallation.

3. Event Bus Delivery

Subscriptions stored in memory only. On core restart, all always_on modules restart and re-subscribe automatically.

Webhook delivery includes X-Selena-Signature: sha256=<hmac>, X-Event-Id, X-Event-Type headers. SDK verifies HMAC automatically via hmac.compare_digest.

4. UI Widgets

UI Core loads widgets via iframe with sandbox. Each module must serve: GET /health, GET /widget.html, GET /settings.html, GET /icon.svg.

UI token (read-only, TTL 1hr) passed via query parameter for Core API access from widget.

5. Secrets Vault & OAuth Proxy

OAuth Device Flow (RFC 8628) with QR code. Token stored encrypted (AES-256-GCM) in /secure/tokens/<module>/. SSRF protection: only https://, private IP blocking.

6. Cloud Sync

Heartbeat every 60s with HMAC-SHA256. Long-poll commands: INSTALL_MODULE, STOP_MODULE, REBOOT, SYNC_STATE, FACTORY_RESET. Exponential backoff on failure.

7. Integrity Agent Interaction

Independent systemd process. Never imports core. Communicates via filesystem, Docker CLI, and HTTP. Reports violations via POST /api/v1/integrity/violation with X-Agent-Secret.