Metadata-Version: 2.4
Name: dnsctl-app
Version: 1.1.0
Summary: Secure, version-controlled DNS management tool with CLI and GUI
Author-email: Dhivijit Koppuravuri <me@dhivijit.dev>
License-Expression: MIT
Project-URL: Source, https://github.com/dhivijit/dnsctl
Project-URL: Issue Tracker, https://github.com/dhivijit/dnsctl/issues
Keywords: dns,devops,infrastructure,git,cli,security
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Requires-Dist: cryptography>=41.0
Requires-Dist: keyring>=24.0
Requires-Dist: click>=8.1
Requires-Dist: PyQt6>=6.6
Requires-Dist: GitPython>=3.1
Requires-Dist: qt-material>=2.14
Requires-Dist: qtawesome>=1.3
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pyinstaller>=6.0; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="dnsctl/icon.png" alt="DNSCTL Icon" width="128" height="128">

# DNSCTL

**Secure, version-controlled DNS management for Cloudflare (CLI + GUI)**

</div>

DNSCTL is a local infrastructure tool for safely managing Cloudflare DNS records using a Git-backed state model, drift detection, and a plan/apply workflow.

It combines:

- A powerful CLI for automation
- A PyQt GUI for visualization
- Secure secret handling
- Version-controlled state
- Protected record enforcement

Think of it as a lightweight, DNS-focused reconciliation engine for Cloudflare.

---

## ✨ Key Features

- **State Sync** — Pull DNS records into local JSON state
- **Local Editing** — Add / edit / delete records safely
- **Drift Detection** — Detect out-of-band dashboard changes
- **Plan / Apply Workflow** — Preview before pushing
- **Protected Records** — System + user-defined protection
- **Git-Backed History** — Every state change auto-committed
- **Secure Token Storage** — AES-GCM encrypted + OS keyring
- **Session Locking** — Auto-expires after inactivity
- **CLI + GUI Parity** — Same core engine

---

## 📦 Installation

### Windows

**Download the installer from the [Releases](https://github.com/dhivijit/dnsctl/releases) page.**

The installer includes both CLI and GUI applications with all dependencies bundled.

### macOS / Linux

```bash
git clone https://github.com/dhivijit/dnsctl.git
cd dnsctl
pip install .
```

**Requirements:**
- Python 3.11+
- Git
- OS keyring support (macOS Keychain / Linux Secret Service)

**Note:** For development mode, use `pip install -e .`

---

## 🚀 Quick Start

### 1. Initialize local state

```bash
dnsctl init
```

### 2. Store your Cloudflare API token (encrypted)

```bash
dnsctl login
```

The token is:
- Encrypted with AES-256-GCM
- Key derived via PBKDF2 (200k iterations)
- Stored securely in OS keyring

### 3. Unlock session

```bash
dnsctl unlock
```

### 4. Sync zones

```bash
dnsctl sync
```

---

## 🧰 CLI Overview

### Authentication

```bash
dnsctl init
dnsctl login
dnsctl unlock
dnsctl lock
dnsctl logout
```

### Sync & Status

```bash
dnsctl sync [-z ZONE]
dnsctl status
dnsctl diff
dnsctl plan
dnsctl apply
```

### Record Management (Local State)

```bash
dnsctl add --type A --name sub.example.com --content 1.2.3.4
dnsctl edit --type A --name sub.example.com --content 5.6.7.8
dnsctl rm --type A --name sub.example.com
```

### Protected Records

```bash
dnsctl protect --type A --name example.com --reason "Critical root record"
dnsctl unprotect --type A --name example.com
dnsctl protected
```

### History & Rollback

```bash
dnsctl log
dnsctl rollback <commit_sha>
```

### Import / Export

```bash
dnsctl export
dnsctl import zone.json
```

---

## 🖥 GUI

Launch:

```bash
dnsctl-g
```

Features:

- Zone selector
- Record type tabs (A, CNAME, MX, TXT, etc.)
- Drift status indicator
- Sync / Plan / Apply controls
- Record add/edit/delete dialogs
- History & rollback viewer
- Session unlock modal

The GUI uses the same reconciliation engine as the CLI.

---

## 🔐 Security Model

DNSCTL is designed for secure local infrastructure management.

### Token Handling

- API token is never stored in plaintext
- Encrypted with AES-GCM
- Derived from master password using PBKDF2-HMAC-SHA256
- Encrypted blob stored in OS keyring
- Session auto-expires (default: 15 minutes)

### Protected Records

Two layers of protection:

1. System-level (e.g., NS records)
2. User-defined protection flags

Protected records require explicit force to modify or delete.

---

## 🧠 Design Philosophy

DNSCTL is built around:

- Explicit change control
- Safe reconciliation
- Drift awareness
- Secure secret handling
- Recoverable state

It is intended for developers and security engineers who want more control than a web dashboard provides.

---

## ⚠️ Scope

DNSCTL is:

- A local DNS management tool
- Designed for single-user environments
- Focused on Cloudflare DNS

It is not:

- A multi-user SaaS system
- A remote secret manager
- A full Terraform replacement

---

## 📜 License

MIT License  
© Dhivijit
