SURON — Secrets Manager

Telegram-approved, real-time, self-hosted secrets management for Node.js. Built for vibe coders, AI-assisted development, and solo founders who don't want to deal with Vault.

---

What is SURON?

Instead of storing secrets in .env files scattered across servers and laptops, SURON:

1. Keeps all secrets in a central Convex database
2. Sends a Telegram message to you every time an app wants a secret
3. You tap Approve or Deny — the secret is returned (or blocked)
4. Full audit log of every access, approval, and denial
5. Dashboard + CLI for complete control

Perfect for: AI-assisted coding sessions (vibe coding), solo projects, small teams, API key management — any situation where you want full visibility into which running process is accessing which secrets.

---

Architecture

suron/
├── convex/          # Backend — Convex DB, real-time API, mutations, queries
├── SDK/             # @suronai/sdk — Node.js client library  (not yet on npm)
├── SDK/CLI/         # @suronai/cli — CLI: push .env, manage secrets, scaffold  (not yet on npm)
├── Bot/             # Telegram bot — approval notifications + /commands
├── Web/             # React dashboard — Vite, Convex, Vercel
├── llm.md           # AI integration guide (read this if you're an AI assistant)
└── README.md        # This file

Note: The @suronai/sdk and @suronai/cli packages are not yet published to npm. Install from the local path (see Quick Start below).

---

Stack

Layer	Tech
Database & real-time	Convex
Approval flow	Telegram Bot API
Dashboard	React 18 + Vite + Convex React
SDK	Pure Node.js ESM
CLI	Node.js with interactive prompts
Hosting	Vercel (dashboard) + any Node host (bot)

---

Quick Start

1. Clone and install

git clone https://github.com/your-org/suron
cd suron
npm install

2. Deploy the Convex backend

npx convex dev        # development (live reload)
# or
npx convex deploy     # production
# Copy the CONVEX_URL from output — you'll need it everywhere

3. Configure the Telegram bot

# 1. Message @BotFather on Telegram → /newbot → copy token
# 2. Message @userinfobot → copy your chat ID

# Edit Bot/.env:
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_ADMIN_CHAT_ID=your_chat_id
SURON_URL=https://your-deployment.convex.cloud

node Bot/index.js

4. Deploy the dashboard

# Edit Web/.env:
VITE_CONVEX_URL=https://your-deployment.convex.cloud

cd Web
npm install && npm run build
# Deploy Web/dist to Vercel, Netlify, or any static host
# Or: vercel deploy (uses vercel.json in repo root)

Visit the dashboard → first visit creates your admin account (one-time, signup is then permanently disabled).

5. Install the CLI (from local path, npm not yet published)

npm install -g ./SDK/CLI

suron init            # saves ~/.suron/config with SURON_URL + dashboard URL
suron login           # browser-based auth → opens dashboard → approve → CLI gets token
suron whoami          # verify authentication

6. Create your first app

suron apps create --name my-api
# → Outputs SURON_TOKEN=sk_...  — copy it

7. Scaffold a new Node.js project

suron new my-project
# Creates a complete Node.js project with SURON pre-wired:
#   package.json, src/index.js, .env, .env.secrets, .env.example,
#   .gitignore, README.md, llm.md
cd my-project
npm install
# Set SURON_TOKEN in .env, then:
npm run secrets:push   # uploads secrets from .env.secrets
rm .env.secrets        # never commit this file
npm start

8. Add the SDK to an existing app

# SDK not yet on npm — install from local path:
npm install ../suron/SDK   # adjust path as needed

# In your entry file:
import 'dotenv/config'        # .env has SURON_URL + SURON_TOKEN only
import { SURON } from '@suronai/sdk'

const env = await SURON.connect()
const DB  = await env.get('DATABASE_URL')   # → Telegram approval → secret

---

CLI Reference

suron help                              Full command reference
suron version                           Show CLI version
suron --version                         Show CLI version (flag form)

Setup
  suron init                            Interactive wizard — saves ~/.suron/config
  suron login                           Browser auth — opens dashboard to approve CLI
  suron logout                          Remove saved credentials
  suron whoami                          Show auth status

Scaffold
  suron new <directory>                 Create a new Node.js project with SURON

Apps
  suron apps                            List all registered apps
  suron apps create --name <n>          Register new app, get token

Secrets
  suron secrets --app <n>               List secrets (masked values — safe to show)
  suron secrets reveal --app <n>        Show key=value table in terminal (cleartext)
  suron secrets set --app <n> --key K   Set a secret (prompted securely)
  suron secrets delete --app <n> -k K   Delete a secret
  suron push --app <n> [--env .env]     Bulk-push entire .env file

Requests
  suron requests                        List pending Telegram approval requests
  suron approve --id <requestId>        Approve from CLI
  suron deny --id <requestId>           Deny from CLI

secrets reveal output format

  ┌─ ENV TABLE ──────────────────────────────────────────────────────────────┐
    DATABASE_URL             = postgres://user:pass@host/db
    OPENAI_API_KEY           = sk-proj-...
    REDIS_URL                = redis://localhost:6379
  └──────────────────────────────────────────────────────────────────────────┘

This structured table is machine-readable — AI assistants use it to debug misconfigured secrets.

---

SDK Reference

import 'dotenv/config'
import { SURON } from '@suronai/sdk'

const env = await SURON.connect()

// Single secret (blocks until approved via Telegram)
const key = await env.get('API_KEY')

// Multiple secrets at startup (one approval per key, in order)
const { DB, REDIS, API } = await env.getAll(['DB', 'REDIS', 'API'])

Environment variables your app needs:

Variable	Description
SURON_URL	Convex deployment URL
SURON_TOKEN	App token from suron apps create

---

Dashboard Features

• Overview — live stats, recent activity log
• Apps — list apps, stop/restart running processes
• Secrets — manage secrets per-app, inline editing, reveal values
• Requests — approve/deny pending secret access requests
• Logs — real-time log stream, filterable by app
• CLI Auth — approve browser-based CLI logins

Sidebar collapses to icon-only mode on desktop. On mobile (≤640px), the sidebar is hidden and a bottom tab bar appears instead.

---

Security Notes

• Secrets stored in Convex (plaintext — encrypt at the action layer for production)
• suron secrets set always prompts for value — never accepts --value to avoid shell history leaks
• suron push skips SURON_URL / SURON_TOKEN automatically (no circular storage)
• Dashboard requires password auth — one admin account, signup permanently disabled after first use
• Sessions expire after 30 days
• CLI auth uses a short-lived code + browser approval flow — no passwords in terminal

---

Contributing

SURON is open source (MIT). Contributions welcome.

git clone https://github.com/your-org/suron
cd suron
npm install
npx convex dev       # starts backend in dev mode
cd Web && npm run dev  # starts dashboard dev server
node Bot/index.js    # starts Telegram bot

Issues and PRs: https://github.com/your-org/suron

---

Roadmap

• Publish @suronai/sdk and @suronai/cli to npm
• Encrypt secrets at rest in Convex actions
• Team support (multiple admin accounts)
• Webhook approval (Slack, Discord)
• Secret expiry and rotation
• Audit log export (CSV / JSON)

---

License

MIT — see LICENSE