SunLionet

SunLionet is an offline-first, bundle-based privacy and resilient communication system designed for high-risk, restricted networks.

It ships as:

• SunLionet Inside: runs on end-user devices and keeps connectivity alive by detecting interference and rotating local sing-box configurations.
• SunLionet Outside: runs by supporters to generate, validate, and distribute signed/encrypted seed bundles to Inside users (via trusted channels such as Signal).
• SunLionet App: the Android wrapper for SunLionet Inside (VPN integration + configuration import UI).
• SunLionet Dashboard: the web UI for local operator visibility (including localhost-only runtime status).

Migration note: this repository is still named SUNLIONET-agent during the transition. Some paths, package imports, release artifacts, and protocol identifiers may still use legacy SUNLIONET-* naming until the release pipeline is fully renamed.

Documentation site (GitHub Pages): https://kaveh8866.github.io/Sunlionet/

Persian: see README.fa.md.

---

Getting Started (MVP)

Start here: docs/getting-started.md.

It covers the three first-time paths:

• Linux: Download → Verify → Install → Import bundle → Connect
• Android: Install APK → Import bundle → Connect → Monitor
• Web: Open SunLionet Dashboard → Detect local runtime → Show status

Quick Start (Development)

Prerequisites:

• Go 1.25+
• Windows: PowerShell 7+

Run tests:

• Windows:

  .\scripts\run_tests.ps1

• Linux/macOS:

  ./scripts/run_tests.sh

Linux MVP (Inside)

Prerequisites:

• Go 1.25+
• Optional: sing-box installed, or pass --sing-box-bin

Run the Linux MVP path (import -> select -> render -> execute):

go run ./cmd/inside \
  --state-dir ./.tmp/state \
  --import ./testdata/sample.bundle \
  --master-key 0123456789abcdef0123456789abcdef \
  --trusted-signer-pub-b64url "$(cat ./testdata/sample_signer_pub.b64url)" \
  --age-identity "$(cat ./testdata/sample_age_identity.txt)"

Render only (no process launch):

go run ./cmd/inside \
  --state-dir ./.tmp/state \
  --import ./testdata/sample.bundle \
  --master-key 0123456789abcdef0123456789abcdef \
  --trusted-signer-pub-b64url "$(cat ./testdata/sample_signer_pub.b64url)" \
  --age-identity "$(cat ./testdata/sample_age_identity.txt)" \
  --render-only

---

Project Stewardship

SunLionet is designed for long-term resilience and community-driven maintenance.

• Governance Model: How decisions are made and who manages the project.
• Contribution Guide: How to get involved safely and effectively.
• Security Policy: How we handle vulnerabilities and security updates.
• Sustainability Plan: Our model for long-term maintenance.
• Version 1.0 Readiness: Our current assessment of the project's maturity.

---

Build

This repository produces two binaries using Go build tags.

SunLionet Inside

go build -tags inside -ldflags="-s -w" -o bin/sunlionet-inside ./cmd/inside/

./bin/sunlionet-inside

SunLionet Outside

go build -tags outside -ldflags="-s -w" -o bin/sunlionet-outside ./cmd/outside/

./bin/sunlionet-outside

---

Config Distribution (Outside → Inside)

SunLionet intentionally avoids a central fetch API. Seed configs arrive via:

1. Signal disappearing messages: signed/encrypted snb://v2: bundles.
2. QR codes (in-person bootstrap).
3. Local Bluetooth mesh (Inside ↔ Inside) for blackout scenarios.

Bundle parsing/validation lives in pkg/importctl and pkg/bundle.

---

Security Model (Summary)

Inside devices can be seized. Design goals:

• Seed profiles stored encrypted at rest via store.go.
• Config bundles authenticated with Ed25519 signatures via import.go.
• Default is receive-only from Inside (no outbound telemetry).

For the detailed threat model and dual-agent design, see /docs.

Documentation

• Core Modules Architecture (Detector, Policy Engine, Secure Store)
• Production Map (What Ships)
• Website & Docs Specification
• Architecture Details
• Security Boundaries
• Security Audit Checklist
• Release Blockers
• Bundle Format
• Signal Integration
• Installation Guide (English)
• Linux MVP Install + Run
• Linux Smoke Test
• راهنمای نصب (Persian)
• Pi Orchestrator Integration (Local)

SunLionet Outside (MVP usage)

Generate keys:

go run -tags outside ./cmd/outside keygen \
  --ed25519-priv ./keys/outside.ed25519 \
  --ed25519-pub ./keys/outside.ed25519.pub \
  --age-identity ./keys/inside.agekey \
  --age-recipient ./keys/inside.agepub

Generate a bundle:

go run -tags outside ./cmd/outside \
  --profiles ./profiles.json \
  --templates-dir ./templates \
  --signing-key ./keys/outside.ed25519 \
  --recipient-pub ./keys/inside.agepub \
  --out ./dist

Verify a bundle:

go run -tags outside ./cmd/outside verify \
  --bundle ./dist/bundle.snb.json \
  --signer-pub ./keys/outside.ed25519.pub \
  --age-identity ./keys/inside.agekey \
  --require-decrypt

Verify directly from URI text:

go run -tags outside ./cmd/outside verify \
  --uri-file ./dist/bundle.uri.txt \
  --signer-pub ./keys/outside.ed25519.pub \
  --age-identity ./keys/inside.agekey \
  --require-decrypt

Distribution helpers:

• ./dist/manifest.json is machine-readable (includes bundle SHA-256 and URI size hints)
• ./dist/qr_payload.txt is written only if the URI is small enough (--qr-threshold-chars)
• ./dist/bundle.chunks.txt is written only if the URI exceeds --chunk-threshold-chars (SNBCHUNK/1 lines)

See:

• Bundle Generation
• Trust Model
• Verification

problems_and_diagnostics

• “missing --signing-key”: provide --signing-key (Ed25519 seed base64url) or run keygen.
• “refusing to generate unencrypted bundle…”: pass --allow-plaintext or set --recipient-pub for encryption.
• “missing outbound template…”: ensure --templates-dir points at ./templates and your profiles’ template_ref matches an existing *.json template.
• “SECURITY ALERT: signature verification…” (Inside import): you’re using the wrong trusted signer pub key, or the bundle/URI was corrupted.
• “note: header verified; payload not decrypted…” (Outside verify): provide --age-identity, and use --require-decrypt in CI to fail closed.

Contributing

See CONTRIBUTING.md.