tiger-agent 0.2.0

package/.env.example

@@ -0,0 +1,22 @@
+# ============================================
+# Tiger Bot Environment Configuration
+# Copy this file to .env and fill in real values
+# NEVER commit .env to git!
+# ============================================
+
+# Google Gemini (for image generation)
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# Telegram Bot
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
+TELEGRAM_CHAT_ID=8172556270
+
+# X/Twitter (optional - paid API)
+X_BEARER_TOKEN=your_x_bearer_token_here
+
+# Pinecone (optional - if using cloud vector DB)
+PINECONE_API_KEY=your_pinecone_key_here
+PINECONE_ENVIRONMENT=your_pinecone_env
+
+# SQLite Configuration
+TIGER_DB_PATH=/root/.tiger/memory/tiger_memory.db

package/.env.secrets.example

@@ -0,0 +1,14 @@
+# Secrets only. Keep this file local as .env.secrets (gitignored),
+# or encrypt it to .env.secrets.enc and delete the plaintext.
+
+# Moonshot/Open Platform key (used when KIMI_PROVIDER=moonshot)
+MOONSHOT_API_KEY=
+
+# Kimi Code API key (used when KIMI_PROVIDER=code)
+KIMI_CODE_API_KEY=
+
+# Backward-compatible alias (optional)
+KIMI_API_KEY=
+
+# Telegram bot token
+TELEGRAM_BOT_TOKEN=

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 AI Research Group, Department of Civil Engineering,
+King Mongkut's University of Technology Thonburi (KMUTT)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,284 @@
+# 🐯 Tiger Agent
+
+**Made by AI Research Group, Department of Civil Engineering, King Mongkut's University of Technology Thonburi (KMUTT)**
+
+Tiger is a **Cognitive AI Agent** with persistent long-term memory, multi-provider LLM support, self-learning, and Telegram bot integration — designed for 24/7 autonomous operation on Linux.
+
+---
+
+## 🎯 Why Tiger?
+
+| Feature | Tiger Bot | Generic AI Assistants |
+|---------|-----------|----------------------|
+| **Memory** | Persistent lifetime memory (Vector DB) | Forgets when session ends |
+| **Learning** | Self-training every 12 hours | Static, never improves |
+| **Security** | Audit logs + Encryption + Hardened perms | No audit trail |
+| **Channels** | CLI + Telegram simultaneously | Single channel only |
+| **Execution** | Chains multiple skills autonomously | Single command only |
+
+---
+
+## 📦 Installation
+
+```bash
+npm install -g tiger-agent
+```
+
+No git clone needed.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+tiger onboard     # First-time setup wizard
+tiger start       # Start CLI chat
+```
+
+CLI exit: `/exit` or `/quit`
+
+For Telegram:
+
+```bash
+tiger telegram              # Foreground
+tiger telegram --background # Background daemon
+tiger stop                  # Stop daemon
+tiger status                # Check daemon status
+```
+
+---
+
+## 📋 Requirements
+
+- Node.js 18+ (20+ recommended)
+- npm
+- Python 3 (for SQLite memory helper)
+
+---
+
+## 🎮 Run Modes
+
+| Mode | Global install | From source | Use Case |
+|------|---------------|-------------|----------|
+| **CLI** | `tiger start` | `npm run cli` | Interactive terminal |
+| **Telegram** | `tiger telegram` | `npm run telegram` | Bot foreground |
+| **Background** | `tiger telegram --background` | `npm run telegram:bg` | 24/7 daemon |
+| **Stop** | `tiger stop` | `npm run telegram:stop` | Kill daemon |
+| **Status** | `tiger status` | — | Check daemon |
+
+Background logs: `~/.tiger/logs/telegram-supervisor.log`
+
+---
+
+## 🔧 Setup Wizard
+
+`tiger onboard` (global) or `npm run setup` (from source) configures:
+
+- `~/.tiger/.env` — non-secret settings
+- `~/.tiger/.env.secrets` — API keys and tokens (mode 600)
+
+Options during setup:
+- Persistent vs temporary vector DB
+- Optional `sqlite-vec` acceleration
+- Optional encrypted secrets file
+
+---
+
+## 🔑 Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ACTIVE_PROVIDER` | — | Active LLM provider (`kimi`, `zai`, `minimax`, `claude`, `moonshot`) |
+| `PROVIDER_ORDER` | — | Fallback order, comma-separated |
+| `TELEGRAM_BOT_TOKEN` | — | Telegram bot token |
+| `ALLOW_SHELL` | `false` | Enable shell tool |
+| `ALLOW_SKILL_INSTALL` | `false` | Enable ClawHub skill install |
+| `VECTOR_DB_PATH` | `~/.tiger/db/memory.sqlite` | SQLite vector DB path |
+| `DATA_DIR` | `~/.tiger/data` | Context files directory |
+
+---
+
+## 🌐 Multi-Provider LLM
+
+Tiger supports **5 providers** with automatic fallback and daily token limits.
+
+### Supported Providers
+
+| Provider | ID | Default Model | API Key |
+|----------|----|--------------|---------|
+| Kimi Code | `kimi` | `k2p5` | `KIMI_CODE_API_KEY` |
+| Kimi Moonshot | `moonshot` | `kimi-k1` | `MOONSHOT_API_KEY` |
+| Z.ai (Zhipu) | `zai` | `glm-5` | `ZAI_API_KEY` (format: `id.secret`) |
+| MiniMax | `minimax` | `abab6.5s-chat` | `MINIMAX_API_KEY` |
+| Claude (Anthropic) | `claude` | `claude-sonnet-4-6` | `CLAUDE_API_KEY` |
+
+### `.env` Configuration
+
+```env
+ACTIVE_PROVIDER=zai
+PROVIDER_ORDER=zai,claude,kimi,minimax,moonshot
+
+KIMI_CODE_API_KEY=<key>
+ZAI_API_KEY=<key>
+MINIMAX_API_KEY=<key>
+CLAUDE_API_KEY=<key>
+MOONSHOT_API_KEY=<key>
+
+# Daily token limits per provider (0 = unlimited)
+KIMI_TOKEN_LIMIT=100000
+ZAI_TOKEN_LIMIT=100000
+MINIMAX_TOKEN_LIMIT=100000
+CLAUDE_TOKEN_LIMIT=500000
+MOONSHOT_TOKEN_LIMIT=100000
+```
+
+### Auto-Switch Behaviour
+
+1. Uses `ACTIVE_PROVIDER` for all requests
+2. On **429** (rate limit) or **403** (quota exceeded) — switches to next in `PROVIDER_ORDER`
+3. When a provider's daily token limit is reached — skipped for the rest of the day
+4. Providers with no API key are silently skipped
+5. Token usage tracked in `~/.tiger/db/token_usage.json`, resets at UTC midnight
+
+---
+
+## 💬 Telegram Commands
+
+| Command | Description |
+|---------|-------------|
+| `/api` | Show all providers with token usage |
+| `/api <id>` | Switch provider (e.g. `/api claude`) |
+| `/tokens` | Show today's token usage per provider |
+| `/help` | Show all commands |
+
+---
+
+## 🧠 Memory & Context
+
+Context files loaded every turn (from `~/.tiger/data/`):
+
+- `soul.md` — Agent personality
+- `human.md` / `human2.md` — User profile
+- `ownskill.md` — Known skills (auto-refreshed every 24h)
+
+Auto-refresh cycles (configurable via `.env`):
+
+| Cycle | Variable | Default |
+|-------|----------|---------|
+| Skill summary | `OWN_SKILL_UPDATE_HOURS` | 24h |
+| Soul refresh | `SOUL_UPDATE_HOURS` | 24h |
+| Reflection | `REFLECTION_UPDATE_HOURS` | 12h |
+| Memory ingest | `MEMORY_INGEST_EVERY_TURNS` | every N turns |
+
+Vector memory DB: `~/.tiger/db/memory.sqlite`
+
+Optional `sqlite-vec` acceleration:
+```env
+SQLITE_VEC_EXTENSION=/path/to/sqlite_vec
+```
+
+Memory commands (from source):
+```bash
+npm run memory:init      # Initialize DB
+npm run memory:stats     # Show stats
+npm run memory:migrate   # Migrate from /tmp/
+npm run memory:vec:check # Check sqlite-vec
+```
+
+---
+
+## 🛠️ Built-in Tools
+
+| Category | Tools |
+|----------|-------|
+| **Files** | `list_files`, `read_file`, `write_file` |
+| **Shell** | `run_shell` (requires `ALLOW_SHELL=true`) |
+| **Skills** | `list_skills`, `load_skill`, `clawhub_search`, `clawhub_install` |
+| **Orchestration** | `run_sub_agents` |
+
+---
+
+## 🔒 Security
+
+| Feature | Detail |
+|---------|--------|
+| **Credential Storage** | Externalized to `~/.tiger/.env.secrets` (mode 600) |
+| **Database Security** | `~/.tiger/db/` with hardened permissions |
+| **Audit Logging** | Sanitized skill logs at `~/.tiger/logs/audit.log` |
+| **Auto Backup** | Daily SQLite backups, 30-day retention |
+| **Secret Rotation** | Built-in 90-day rotation reminders |
+
+### Encrypted Secrets (optional)
+
+```bash
+export SECRETS_PASSPHRASE='your-long-passphrase'
+node scripts/encrypt-env.js --in .env.secrets --out .env.secrets.enc
+rm .env.secrets
+```
+
+---
+
+## 🆚 Tiger vs OpenClaw
+
+| Feature | **Tiger** 🐯 | **OpenClaw** 🔧 |
+|---------|-------------|-----------------|
+| **Identity** | Persistent AI persona | Skill marketplace |
+| **Memory** | Text files + SQLite vector | Skill-based only |
+| **Self-Training** | ✅ 12h auto-reflection | ❌ Manual only |
+| **Skill Orchestration** | Multi-skill pipelines | Single execution |
+| **Context Retention** | ✅ Cross-session | Session-only |
+| **Security** | ✅ Encryption + audit logs | Basic |
+| **Installation** | `npm install -g tiger-agent` | `clawhub install` |
+
+---
+
+## 🐛 Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Bot stuck on one provider | `/api <name>` in Telegram to switch manually |
+| Provider silently skipped | No API key set, or daily limit reached — check `/tokens` |
+| `401` auth error | Wrong or missing API key |
+| `403` quota error | Daily quota exhausted — auto-switches; top up billing or raise `*_TOKEN_LIMIT` |
+| `429` rate limit | Auto-switches to next provider in `PROVIDER_ORDER` |
+| Z.ai auth fails | Key must be `id.secret` format (from Zhipu/BigModel console) |
+| Shell tool disabled | Set `ALLOW_SHELL=true` in `.env` |
+| Stuck processes | `pkill -f "node src/cli.js"` then restart |
+| Reset token counters | Delete `~/.tiger/db/token_usage.json` and restart |
+
+---
+
+## 📁 Data Directory
+
+After global install, all runtime data lives in `~/.tiger/`:
+
+```
+~/.tiger/
+├── .env                  # Settings
+├── .env.secrets          # API keys (mode 600)
+├── data/                 # Context files (soul.md, human.md, ...)
+├── db/
+│   ├── agent.json        # Conversation state
+│   ├── memory.sqlite     # Vector memory
+│   └── token_usage.json  # Daily token counters
+└── logs/
+    ├── audit.log
+    └── telegram-supervisor.log
+```
+
+---
+
+## 👥 Authors
+
+**AI Research Group**
+Department of Civil Engineering
+King Mongkut's University of Technology Thonburi (KMUTT)
+Bangkok, Thailand
+
+---
+
+## 📜 License
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+*[虎 - Hǔ - The Tiger: Powerful, agile, and relentless in pursuit of goals]*

package/bin/tiger.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const TIGER_HOME = process.env.TIGER_HOME || path.join(os.homedir(), '.tiger');
+
+// Ensure runtime dirs exist
+['', 'data', 'db', 'logs'].forEach((d) => fs.mkdirSync(path.join(TIGER_HOME, d), { recursive: true }));
+
+// Expose to child modules and the supervisor worker
+process.env.TIGER_HOME = TIGER_HOME;
+
+// chdir so all relative env paths (./data, ./db, .env) resolve inside ~/.tiger
+process.chdir(TIGER_HOME);
+
+const argv = process.argv.slice(2);
+const cmd = argv[0] || '';
+
+// ─── Help ────────────────────────────────────────────────────────────────────
+function showHelp() {
+  console.log(`
+Tiger Agent 🐯  — AI assistant with persistent memory
+
+Usage:
+  tiger onboard                  Interactive setup wizard
+  tiger onboard --install-daemon Setup + install system daemon (auto-start on boot)
+  tiger start                    Start CLI chat
+  tiger telegram                 Start Telegram bot (foreground)
+  tiger telegram --background    Start Telegram bot as background process
+  tiger stop                     Stop background Telegram bot
+  tiger status                   Show daemon / process status
+  tiger version                  Print version
+
+Config & data: ${TIGER_HOME}
+  `.trim());
+}
+
+// ─── Route commands ───────────────────────────────────────────────────────────
+switch (cmd) {
+  case 'onboard':
+    require(path.join(PKG_ROOT, 'scripts', 'onboard.js'));
+    break;
+
+  case 'version':
+  case '-v':
+  case '--version': {
+    const pkg = require(path.join(PKG_ROOT, 'package.json'));
+    console.log(pkg.version);
+    break;
+  }
+
+  case 'status': {
+    const pidFile = path.join(TIGER_HOME, 'tiger-telegram.pid');
+    if (!fs.existsSync(pidFile)) { console.log('Tiger daemon: not running'); break; }
+    const pid = Number(fs.readFileSync(pidFile, 'utf8').trim());
+    try { process.kill(pid, 0); console.log(`Tiger daemon: running (PID ${pid})`); }
+    catch (_) { console.log('Tiger daemon: not running (stale pid file)'); }
+    break;
+  }
+
+  case 'stop':
+    process.argv = [process.argv[0], process.argv[1], '--telegram-stop'];
+    require(path.join(PKG_ROOT, 'src', 'cli.js'));
+    break;
+
+  case 'telegram':
+    if (argv.includes('--background') || argv.includes('-b')) {
+      process.argv = [process.argv[0], process.argv[1], '--telegram', '--background'];
+    } else {
+      process.argv = [process.argv[0], process.argv[1], '--telegram'];
+    }
+    require(path.join(PKG_ROOT, 'src', 'cli.js'));
+    break;
+
+  case 'start':
+  case 'cli':
+  case '':
+    process.argv = [process.argv[0], process.argv[1]];
+    require(path.join(PKG_ROOT, 'src', 'cli.js'));
+    break;
+
+  case 'help':
+  case '--help':
+  case '-h':
+    showHelp();
+    break;
+
+  default:
+    console.error(`Unknown command: ${cmd}`);
+    showHelp();
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "tiger-agent",
+  "version": "0.2.0",
+  "description": "Cognitive AI agent with persistent memory, multi-provider LLM, and Telegram bot",
+  "type": "commonjs",
+  "main": "src/cli.js",
+  "bin": {
+    "tiger": "bin/tiger.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    ".env.example",
+    ".env.secrets.example"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"if(process.env.npm_config_global==='true'){console.log('\\n🐯 Tiger Agent installed!\\n\\nRun to get started:\\n  tiger onboard\\n')}\"",
+    "setup": "node scripts/setup.js",
+    "onboard": "node scripts/onboard.js",
+    "start": "node src/cli.js",
+    "telegram": "node src/cli.js --telegram",
+    "telegram:bg": "node src/cli.js --telegram --background",
+    "telegram:stop": "node src/cli.js --telegram-stop",
+    "cli": "node src/cli.js",
+    "memory:init": "python3 scripts/sqlite_memory.py init --db ./db/memory.sqlite",
+    "memory:stats": "python3 scripts/sqlite_memory.py stats --db ./db/memory.sqlite",
+    "memory:migrate": "node scripts/migrate-vector-db.js --from /tmp/tiger_memory.db --to ./db/memory.sqlite",
+    "memory:vec:check": "python3 scripts/sqlite_vec_setup.py",
+    "memory:vec:install": "python3 scripts/sqlite_vec_setup.py --install --write-env"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "llm",
+    "telegram",
+    "chatbot",
+    "memory",
+    "claude",
+    "zhipu",
+    "glm",
+    "kimi",
+    "minimax"
+  ],
+  "author": "AI Research Group, Dept. of Civil Engineering, KMUTT",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "clawhub": "^0.5.0",
+    "dotenv": "^16.4.5",
+    "node-telegram-bot-api": "^0.66.0"
+  }
+}

package/scripts/audit.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Tiger Audit Logger
+# Logs skill usage with sanitization (no secrets)
+# Format: TIMESTAMP | SKILL | ACTION | STATUS | USER_HASH
+
+TIGER_HOME="${TIGER_HOME:-$HOME/.tiger}"
+AUDIT_LOG="$TIGER_HOME/logs/audit.log"
+MAX_LOG_SIZE=10485760  # 10MB
+MAX_LOG_FILES=5
+
+# Create log directory
+mkdir -p "$(dirname "$AUDIT_LOG")"
+chmod 700 "$(dirname "$AUDIT_LOG")"
+
+# Rotate logs if too large
+rotate_logs() {
+    if [ -f "$AUDIT_LOG" ] && [ $(stat -f%z "$AUDIT_LOG" 2>/dev/null || stat -c%s "$AUDIT_LOG" 2>/dev/null || echo 0) -gt $MAX_LOG_SIZE ]; then
+        for i in $(seq $MAX_LOG_FILES -1 1); do
+            [ -f "$AUDIT_LOG.$i" ] && mv "$AUDIT_LOG.$i" "$AUDIT_LOG.$((i+1))"
+        done
+        [ -f "$AUDIT_LOG" ] && mv "$AUDIT_LOG" "$AUDIT_LOG.1"
+        touch "$AUDIT_LOG"
+        chmod 600 "$AUDIT_LOG"
+    fi
+}
+
+# Log function
+log_audit() {
+    rotate_logs
+    
+    local skill="$1"
+    local action="$2"
+    local status="$3"
+    local timestamp=$(date -Iseconds)
+    local user_hash=$(echo "$USER@$(hostname)" | sha256sum | cut -d' ' -f1 | head -c16)
+    
+    # Sanitize: remove potential secrets from action
+    local sanitized_action=$(echo "$action" | sed -E 's/(api[_-]?key|token|password|secret)[=:][^ ]+/\1=***/gi')
+    
+    echo "[$timestamp] | $skill | $sanitized_action | $status | $user_hash" >> "$AUDIT_LOG"
+    chmod 600 "$AUDIT_LOG"
+}
+
+# Example usage:
+# log_audit "nano-banana-pro-2" "generate_image --prompt '...'" "success"
+
+# If called directly, show usage
+if [ "${BASH_SOURCE[0]}" == "${0}" ]; then
+    echo "Tiger Audit Logger"
+    echo "Usage: source $0 && log_audit <skill> <action> <status>"
+    echo ""
+    echo "Recent audit entries:"
+    [ -f "$AUDIT_LOG" ] && tail -20 "$AUDIT_LOG" || echo "(no entries yet)"
+fi

package/scripts/backup.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Tiger Database Backup Script
+# Runs: Daily via cron or manual
+# Backs up: SQLite memory DB, config files
+
+set -e
+
+TIGER_HOME="${TIGER_HOME:-$HOME/.tiger}"
+BACKUP_DIR="$TIGER_HOME/backup"
+DB_PATH="$TIGER_HOME/memory/tiger_memory.db"
+DATE=$(date +%Y%m%d_%H%M%S)
+RETENTION_DAYS=30
+
+echo "🐯 Tiger Backup Started: $DATE"
+
+# Create backup directory
+mkdir -p "$BACKUP_DIR"
+
+# Backup SQLite database (with WAL if exists)
+if [ -f "$DB_PATH" ]; then
+    BACKUP_FILE="$BACKUP_DIR/tiger_memory_$DATE.db"
+    sqlite3 "$DB_PATH" ".backup '$BACKUP_FILE'"
+    gzip "$BACKUP_FILE"
+    echo "✅ Database backed up: ${BACKUP_FILE}.gz"
+else
+    echo "⚠️ Database not found at $DB_PATH"
+fi
+
+# Backup config (excluding secrets)
+if [ -d "$TIGER_HOME/config" ]; then
+    CONFIG_BACKUP="$BACKUP_DIR/config_$DATE.tar.gz"
+    tar -czf "$CONFIG_BACKUP" -C "$TIGER_HOME" config/ 2>/dev/null || true
+    echo "✅ Config backed up: $CONFIG_BACKUP"
+fi
+
+# Cleanup old backups (keep last 30 days)
+find "$BACKUP_DIR" -name "*.gz" -type f -mtime +$RETENTION_DAYS -delete
+echo "🧹 Cleaned backups older than $RETENTION_DAYS days"
+
+# Log backup event
+logger -t tiger-backup "Backup completed: $DATE"
+echo "✅ Backup completed successfully"

package/scripts/cryptoEnv.js

@@ -0,0 +1,57 @@
+const crypto = require('crypto');
+
+const DEFAULT_ITERATIONS = 310000;
+
+function deriveKey(passphrase, salt, iterations = DEFAULT_ITERATIONS) {
+  return crypto.pbkdf2Sync(
+    Buffer.from(String(passphrase), 'utf8'),
+    salt,
+    iterations,
+    32,
+    'sha256'
+  );
+}
+
+function encryptString(plaintext, passphrase, { iterations = DEFAULT_ITERATIONS } = {}) {
+  if (!passphrase) throw new Error('Missing passphrase');
+  const salt = crypto.randomBytes(16);
+  const iv = crypto.randomBytes(12);
+  const key = deriveKey(passphrase, salt, iterations);
+
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const ciphertext = Buffer.concat([cipher.update(Buffer.from(String(plaintext), 'utf8')), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  return {
+    v: 1,
+    alg: 'aes-256-gcm',
+    kdf: 'pbkdf2-sha256',
+    iterations,
+    salt_b64: salt.toString('base64'),
+    iv_b64: iv.toString('base64'),
+    tag_b64: tag.toString('base64'),
+    ciphertext_b64: ciphertext.toString('base64')
+  };
+}
+
+function decryptToString(payload, passphrase) {
+  if (!passphrase) throw new Error('Missing passphrase');
+  if (!payload || payload.v !== 1) throw new Error('Unsupported payload');
+
+  const salt = Buffer.from(payload.salt_b64, 'base64');
+  const iv = Buffer.from(payload.iv_b64, 'base64');
+  const tag = Buffer.from(payload.tag_b64, 'base64');
+  const ciphertext = Buffer.from(payload.ciphertext_b64, 'base64');
+
+  const key = deriveKey(passphrase, salt, Number(payload.iterations) || DEFAULT_ITERATIONS);
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(tag);
+
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return plaintext.toString('utf8');
+}
+
+module.exports = {
+  encryptString,
+  decryptToString
+};

package/scripts/decrypt-env.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { decryptToString } = require('./cryptoEnv');
+
+function arg(name, def = '') {
+  const idx = process.argv.indexOf(name);
+  if (idx === -1) return def;
+  return process.argv[idx + 1] || def;
+}
+
+const inPath = arg('--in', '.env.secrets.enc');
+const outPath = arg('--out', '.env.secrets');
+const passphrase = process.env.SECRETS_PASSPHRASE || '';
+
+if (!passphrase) {
+  console.error('Missing SECRETS_PASSPHRASE env var');
+  process.exit(2);
+}
+
+const absIn = path.resolve(process.cwd(), inPath);
+const absOut = path.resolve(process.cwd(), outPath);
+
+if (!fs.existsSync(absIn)) {
+  console.error(`Encrypted file not found: ${absIn}`);
+  process.exit(2);
+}
+
+const payload = JSON.parse(fs.readFileSync(absIn, 'utf8'));
+const plaintext = decryptToString(payload, passphrase);
+fs.writeFileSync(absOut, plaintext, { mode: 0o600 });
+
+console.log(`Wrote decrypted secrets to ${outPath}`);