satsuki: PowerDNS frontend for managing subdomains

A Rust-based web frontend for delegating and managing subdomains under a configured base domain using PowerDNS. Users can register a subdomain, authenticate using Basic Auth, and manage DNS records through both a JSON API and the bundled React/Vite frontend under frontend/.

This project contains:

• A backend (Rust, axum, tokio)
• A PowerDNS integration layer
• A SQLite database containing only user metadata
• A TypeScript frontend (React + Vite) that consumes the API
• A builder-friendly CLI (satsuki-pdns-frontend) for embedding or standalone use

---

Quick installation

# with Rustup
cargo install satsuki

Or download pre-built binaries from Releases.

Features

🟦 Subdomain registration

Users select a subdomain (e.g., alice) → the system provisions:

• A zone on the subdomain PowerDNS instance
• A NS delegation in the base PowerDNS instance
• A user row in SQLite (with Argon2 password hash)

🟦 Authentication using Basic Auth

• Username = the subdomain name
• Password = user-chosen
• Frontend stores credentials in localStorage
• All API calls use Authorization: Basic …

🟦 DNS Record Management

Users can read/write DNS RRsets for their zone only. The UI automatically normalizes relative owners, decodes IDNs for display, and punycodes them again on save. NS at the apex is protected and controlled only via NS-mode endpoints.

🟦 Switchable NS Mode

Two modes:

• Internal NS mode → subdomain resolves using configured internal nameservers
• External NS mode → user provides third-party NS records; hosted zone remains editable but inactive until internal mode is restored

🟦 Minimal & secure persistence

Only SQLite contains:

• User/subdomain name
• Argon2 password hash
• External NS settings (if any)

All DNS data stays in PowerDNS.

---

Architecture

Components

• Rust (server)

  • axum web server
  • sqlx SQLite backend
  • reqwest PowerDNS API client
  • argon2 password hashing
  • thiserror, anyhow for errors
  • regex + custom validation

• PowerDNS

  • One “base” PDNS instance → manages the parent zone
  • One “subdomain” PDNS instance → manages each user zone

---

Configuration

satsuki-pdns-frontend uses a flexible builder pattern that is configured from the CLI.

Example invocation

satsuki-pdns-frontend \
  --base-domain example.com \
  --db-path ./data/users.sqlite \
  --listen 0.0.0.0:8080 \
  --base-pdns-url http://127.0.0.1:8081/api/v1 \
  --base-pdns-key secret123 \
  --base-pdns-server-id localhost \
  --sub-pdns-url http://127.0.0.1:8082/api/v1 \
  --sub-pdns-key otherkey456 \
  --sub-pdns-server-id localhost \
  --internal-ns ns1.example.net. \
  --internal-ns ns2.example.net.

Notes:

• --base-domain example.com (without trailing dot)
• Internal NS names must be FQDNs; they are forced to end with .

---

Subdomain Label Rules

User-provided subdomain labels (e.g., alice in alice.example.com) must satisfy:

• [a-z0-9-] only
• Length 1–63
• Cannot start/end with -
• Cannot contain --
• ASCII only

These rules avoid ambiguous DNS behavior and ensure safety.

Reserved Subdomain Names

A small set of infrastructure-friendly labels (e.g. www, mail, ftp, smtp, email) plus the RFC 2606/6761 special-use names (example, invalid, localhost, test) are blocked by default.
Override or extend this list through AppConfig::disallowed_subdomains if you need different policies.

---

API Overview

All API endpoints return JSON.

Public Endpoints

GET /health

Returns {"status":"ok"} so load balancers and the bundled frontend can verify that the process is alive. This endpoint never touches the database or PowerDNS.

POST /api/signup

Registers a new subdomain. The payload must pass validate_subdomain_name, cannot appear in the disallowed list, and the password is Argon2-hashed before storage.

{
  "subdomain": "alice",
  "password": "supers3cret"
}

When the request succeeds:

1. A zone is created on the sub-PDNS instance.
2. Apex NS + SOA RRsets inside that zone are replaced with the configured internal values.
3. The parent/base PDNS zone receives an NS delegation.
4. The SQLite row is inserted.

Failures during steps (2)–(4) trigger best-effort cleanup of both PDNS instances. Duplicate subdomains return HTTP 409.

POST /api/signin

Checks credentials and updates last_login_at when successful. Response body is {"ok": true} on success and 401 on failures (no session cookies are issued—the caller stores Basic Auth credentials).

{
  "subdomain": "alice",
  "password": "supers3cret"
}

GET /api/subdomain/check?name=<label>

Validates the label and reports availability:

{ "available": true }

Reserved labels (e.g. www, mail, localhost, …​) are treated as unavailable even if they are not in the database.

GET /api/about

Returns basic metadata for the deployment:

{ "base_domain": "example.com" }

GET /api/subdomain/list

Fetches the NS RRsets from the base PowerDNS zone and groups them by owner name (including the apex entry). Example response:

[
  {
    "name": "example.com.",
    "records": ["ns1.example.net.", "ns2.example.net."]
  },
  {
    "name": "custom.example.com.",
    "records": ["ns1.custom-dns.com.", "ns2.custom-dns.com."]
  }
]

GET /api/subdomain/soa

Returns the parent-zone SOA line used by the frontend’s BIND-style helper:

{ "soa": "ns1.example.net. hostmaster.example.net. 2024010101 7200 900 1209600 300" }

GET /metrics

Exports Prometheus text metrics, currently satsuki_subdomains_total, which counts unique delegated subdomains (i.e., non-apex NS RRsets in the parent zone):

satsuki_subdomains_total 42

Authenticated Endpoints

All authenticated endpoints require:

Authorization: Basic base64("subdomain:password")

GET /api/zone

Returns every RRset for the user’s zone except the apex NS RRset, which is managed by the NS-mode endpoints. Example:

[
  {
    "name": "www.alice.example.com.",
    "rrtype": "A",
    "ttl": 300,
    "content": "203.0.113.5",
    "priority": null
  }
]

PUT /api/zone

Replaces the submitted RRsets. Records are grouped by (name, rrtype) and each group must share the same TTL. Apex NS and SOA changes are rejected to keep the NS-mode flow authoritative.

{
  "records": [
    {
      "name": "www.alice.example.com.",
      "rrtype": "A",
      "ttl": 600,
      "content": "203.0.113.5",
      "priority": null
    }
  ]
}

POST /api/ns-mode/internal

Replaces the parent-zone delegation with the configured internal NS values and clears any stored external NS details in the database. Use this to “bring the zone home” after previously pointing it to third-party nameservers.

POST /api/ns-mode/external

Switches the parent-zone delegation to user-provided nameservers. The payload must contain 1–6 FQDNs that end with a dot:

{
  "ns": ["ns1.custom-dns.com.", "ns2.custom-dns.com."]
}

The accepted NS list is stored in SQLite so the UI can reflect the user’s current configuration.

GET /api/profile

Returns the logged-in user’s metadata:

{
  "subdomain": "alice",
  "external_ns": false,
  "external_ns1": null,
  "external_ns2": null,
  "external_ns3": null,
  "external_ns4": null,
  "external_ns5": null,
  "external_ns6": null
}

POST /api/password/change

Allows a logged-in user to rotate their password without re-registering. Requires the current password and a new secret (minimum 8 characters):

{
  "current_password": "supers3cret",
  "new_password": "evenB3tter!"
}

Invalid current passwords return 401; successful changes return {"ok": true}.

---

Database Schema

migrations/0001_init.sql:

CREATE TABLE IF NOT EXISTS users (
  id              INTEGER PRIMARY KEY AUTOINCREMENT,
  subdomain       TEXT NOT NULL UNIQUE,
  password_hash   TEXT NOT NULL,
  external_ns     INTEGER NOT NULL DEFAULT 0,
  external_ns1    TEXT,
  external_ns2    TEXT,
  external_ns3    TEXT,
  external_ns4    TEXT,
  external_ns5    TEXT,
  external_ns6    TEXT,
  created_at      TEXT NOT NULL,
  updated_at      TEXT NOT NULL,
  last_login_at   TEXT
);

---

Development Setup

Requirements

• Rust stable
• PowerDNS running (2 instances ideally)
• sqlx-cli (optional for migrations)
• Node.js 18+ (for the React/Vite frontend under frontend/) (Optional)

Frontend (React + Vite) (Optional)

npm install
npm run dev     # serves frontend from ./frontend
npm run build   # emits static assets into ./dist

Running in dev mode

cargo run -- --base-domain example.com --db-path ./dev.sqlite ...

Database migrations

With sqlx-cli:

sqlx migrate run

Or rely on:

sqlx::migrate!().run(&pool)

which runs automatically on startup.

---

PowerDNS Requirements

Base PowerDNS instance must contain:

• The parent zone for your base domain (example.com.)
• Accessible via API (/servers/{id}/zones/...)

Subdomain PowerDNS instance must allow:

• POST /servers/{id}/zones to create user zones
• PATCH /servers/{id}/zones/{zone} to modify RRsets

---

Security Notes

• Always serve over HTTPS
• Use Argon2 password hashing (already implemented)
• Never send PowerDNS API keys to the frontend
• Basic Auth is safe only over HTTPS
• User-submitted hostnames validated strictly

---

Future Enhancements

• Metrics / deeper health reporting
• Zone cloning / templates
• Audit logging
• Account deletion workflow

---

License

Apache-2.0 or MPL-2.0.