dans

module
v0.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 23, 2026 License: AGPL-3.0

README

DANS

DNS Authorization and Name Service is a PostgreSQL-backed policy gateway for PowerDNS Authoritative. It lets identities and groups share a zone while limiting writes by identities without the DANS operator role to exact or Route 53-style glob matches over whole RRsets, including PTR records, without creating subzones.

DANS exposes the pinned PowerDNS 5.1 API plus identity, group, token, delegation, binding, lifecycle, and audit resources. Use it when DNS changes need delegated authority and an audit trail while ordinary authoritative DNS stays independent of the management plane.

Before you start

Use a checkout on macOS or Linux. Run the commands below from the directory containing Makefile, compose.yaml, and scripts/:

cd /path/to/checkout
make help

The supported evaluation path requires a running Docker daemon, Docker Compose v2, and Make. The service dependencies run in Docker; the Make targets and shell checks run from the checkout. The development wrapper uses a portable atomic mkdir lock on both macOS and Linux. Local stack state and credentials are kept under the ignored .dans/ directory.

Five-minute quickstart

The local stack is disposable and intended only for development and evaluation. It builds DANS from this checkout, initializes PostgreSQL and PowerDNS, starts a private Redis for rate limiting, and creates development-only credentials. Do not expose it publicly or reuse its credentials elsewhere.

Prerequisites are macOS or Linux, Docker with Compose v2, and Make. The quickstart does not require Go on the host.

make up
make smoke

make up initializes the installation, stores the local DANS operator token at .dans/dev/operator-token, and prints the console URL and sign-in token after startup succeeds. make smoke creates an isolated fixture, performs an allowed delegated RRset write, confirms an out-of-scope write is denied, queries authoritative DNS, and verifies the audit outcome.

After make up, optional make smoke-host repeats that fixture check and verifies the published loopback HTTP and DNS paths from the host over both UDP and TCP. It requires host curl and dig; ordinary make smoke remains Docker-only.

Successful output from make up includes loopback HTTP/DNS addresses and a console sign-in token. make smoke ends with smoke: ok ...; keep the token private and do not paste startup output into issues or logs.

Run stack lifecycle through Make. Its targets wrap Compose and keep container, volume, image, and credential state bound to this checkout, even if the checkout moves.

DANS listens at http://127.0.0.1:8080; authoritative DNS listens on TCP and UDP at 127.0.0.1:1053. To avoid port conflicts, export the two overrides before running stack commands:

export DANS_DEV_HTTP_PORT=18080
export DANS_DEV_DNS_PORT=15353
make up
make smoke

To use mirrored or custom dependency images, export these variables before running stack commands:

Service Image override Default image
PostgreSQL POSTGRES_IMAGE postgres:16.14
PowerDNS POWERDNS_IMAGE powerdns/pdns-auth-51:5.1.3
Redis REDIS_IMAGE redis:8.10.2
CLI tools CLI_IMAGE busybox:1.37.0-musl
Go builder GOLANG_IMAGE golang:1.26.5-alpine (digest-pinned)
Frontend builder NODE_IMAGE node:24-alpine

The root Compose stack uses each override when it is nonempty; unset or empty variables use the default image. It passes GOLANG_IMAGE and NODE_IMAGE as Docker build arguments for the Go and frontend stages. DANS still builds locally from this checkout with a checkout-scoped image tag. Direct Docker builds can use the same overrides with --build-arg.

Compose does not load .envrc automatically. If it contains your overrides, review the file before authorizing it with direnv allow, then run stack commands through direnv:

direnv allow
direnv exec . make up
direnv exec . make smoke

With direnv's shell hook enabled, ordinary make up and make smoke also inherit the loaded variables. Without direnv, export the variables directly in your shell. Choose images compatible with the stack configuration and existing data; changing PostgreSQL's major version requires a data migration, not just an image override.

The stack enables per-identity rate limiting with the built-in Route 53-style defaults (DANS_RATE_LIMIT_ENABLED=true, DANS_REDIS_URL=redis://redis:6379/0). Redis runs on the stack's private network without persistence or a host port, so its state disappears with the container. Bursting more than 50 requests from one token returns 429 with Retry-After; see rate limiting for every setting, default, and the policy file format.

Use make status to inspect the stack, make logs to follow logs, and make down to stop containers while preserving data and credentials. To delete the entire local installation, including PostgreSQL and PowerDNS data and local credentials, explicitly confirm the reset:

make reset CONFIRM=1

Workflow prerequisites

Use make help as the authoritative command reference. This table shows which tools belong on the host and which workflow uses Docker:

Workflow Host prerequisites Start here Where it runs
Evaluate the local service macOS/Linux, Docker Compose v2, Make make up then make smoke DANS, PostgreSQL, PowerDNS, and the CLI run in Docker
Verify published host access Evaluation prerequisites plus curl and dig make smoke-host HTTP/DNS probes run on the host; the fixture runs in Docker
Native Go work Go toolchain selected by go.mod (go1.26.5 currently) make test, make generate-check On the host
Frontend work Node.js 24, npm, and the Playwright Chromium browser make frontend, make frontend-test On the host
Full integration Docker, curl, dig, jq, mktemp, and standard shell tools make integration The harness and all services use Docker

The full integration image builds its Go and frontend dependencies in Docker, so it does not require a native Go or Node installation. make dev-contract checks the local Compose, Make, script, and documentation contract; CI also runs a Linux lifecycle pass covering persistence, credential recovery, refusal of an occupied checkout, and cleanup after an injected failure.

Troubleshooting

Start with observation before changing state:

docker info
docker compose version
make status
make logs

If Docker or Compose is unavailable, start the Docker daemon and repeat the first two checks. If a published port is occupied, inspect make status, choose unused loopback ports, and rerun the stack commands with both overrides:

export DANS_DEV_HTTP_PORT=18080
export DANS_DEV_DNS_PORT=15353
make up
make smoke

If readiness fails, keep the containers running long enough to inspect make status and make logs. A dependency, migration, or PowerDNS failure is not repaired by deleting the local token; correct the underlying failure and retry.

If a command reports a stale development lock after an interruption, first verify that no stack command or Docker operation is still active. Only then remove the specific lock directory named by the diagnostic and retry; never remove a lock held by a live operation.

If .dans/dev/compose-project is missing, reset refuses to guess which legacy Compose project belongs to the checkout. Inspect the legacy project first, then provide the verified name explicitly: DANS_DEV_LEGACY_PROJECT_NAME=dans-dev make reset CONFIRM=1.

If the local token is missing or the API rejects it with HTTP 401, rerun make up. Startup can recover a token only for the existing enabled local development operator, validates it before replacing .dans/dev/operator-token, and keeps the file restricted. It does not create, enable, or promote identities, and it does not recover from non-401 transport, database, or dependency failures. An unexpected identity or disabled/non-operator account fails closed; use the token recovery runbook for production procedures.

make down stops the local containers but preserves database/DNS volumes and .dans/dev, so a later make up reuses the installation and credential. make smoke intentionally retains its synthetic fixtures for repeatable inspection. When a disposable checkout is no longer needed, make reset CONFIRM=1 removes the local credentials, volumes, and project state; it is destructive and is not a first-line troubleshooting step. For deployed systems, use the deployment examples and operations runbooks, not the local Compose recovery behavior.

Browser console

Open the console URL printed by make up and sign in with its operator token. Both http://localhost:8080/console/ and http://127.0.0.1:8080/console/ work locally; adjust the port if overridden. The local Compose stack explicitly enables development-http cookies so Safari can sign in over HTTP. These cookies remain HttpOnly and SameSite=Strict, with the same seven-day maximum and current token checks. The default secure mode uses a separate Secure cookie and HTTPS ingress for production.

The console provides zones, complete RRset editing, server-side paginated browsing, operator delegations, identities, groups, direct membership, and zone binding recovery. Every signed-in identity can inspect its own access and create or revoke its API tokens. Operators can inspect current authority separately from retained assignments and filter or download audit history as NDJSON. Large zones index on first access; the table shows progress and freshness. See the console guide and API/session contract.

How it works

flowchart LR
    management[Management client] -->|DANS HTTP API| dans[DANS]
    dans -->|Authorize and persist audit intent| postgres[(PostgreSQL)]
    postgres -->|Decision| dans
    dans -->|Private PowerDNS API| powerdns[PowerDNS Authoritative]
    dns[DNS client or resolver] -->|DNS directly on port 53| powerdns

Management requests pass through DANS, which evaluates PostgreSQL-backed policy and records audit state before making authorized changes through the private PowerDNS API. DNS queries go directly to PowerDNS, so authoritative serving does not depend on DANS availability.

Contributing

Native development uses the Go version in go.mod. Building the embedded React/TypeScript console additionally uses Node.js 24 and npm. The common checks are:

make frontend
make frontend-test
make test
make generate-check
make integration
make dev-contract

make test runs every unit test, including the rate limiter against its in-memory backend. Redis-backed rate-limit tests run under the integration build tag and need a disposable Redis; make integration starts one automatically, or run them directly:

docker run -d --rm --name dans-redis-test -p 127.0.0.1:56379:6379 redis:8.10.2
DANS_TEST_REDIS_URL=redis://127.0.0.1:56379/0 go test -tags integration ./internal/ratelimit/
docker stop dans-redis-test

Run make help for the authoritative list and description of supported commands. make generate uses the pinned Go 1.26.5 toolchain so the compressed API artifact matches CI and release builds. make frontend installs the pinned lockfile and rebuilds checked-in embedded assets; rebuild them after changing web/. For frontend iteration, npm --prefix web run dev serves the console and proxies /api to the local DANS service. Install the test browser once with cd web && npx playwright install chromium. Production requires only the DANS executable, not Node.js.

Production boundary

The root Compose stack is not a production deployment. A platform operator should place private DANS instances behind trusted TLS ingress, connect them to externally managed PostgreSQL and PowerDNS services, and prevent clients from reaching the PowerDNS API or key directly. See the deployment examples, immutable configuration reference, and operations runbooks.

In this documentation, a DANS operator is a privileged identity inside DANS; a platform operator deploys and runs the service.

Further documentation

Directories

Path Synopsis
api
Package api provides primitives to interact with the openapi HTTP API.
Package api provides primitives to interact with the openapi HTTP API.
openapi
Package openapi embeds the exact checked-in combined API contract.
Package openapi embeds the exact checked-in combined API contract.
cmd
dans command
internal
cli
contract
Package contract validates invariants in the combined OpenAPI contract.
Package contract validates invariants in the combined OpenAPI contract.
delegation
Package delegation implements immutable RRset selector semantics.
Package delegation implements immutable RRset selector semantics.
dnsname
Package dnsname canonicalizes absolute DNS owner names for policy decisions.
Package dnsname canonicalizes absolute DNS owner names for policy decisions.
httpapi
Package httpapi contains HTTP trust-boundary primitives shared by handlers.
Package httpapi contains HTTP trust-boundary primitives shared by handlers.
httpserver
Package httpserver contains the DANS HTTP trust-boundary and lifecycle.
Package httpserver contains the DANS HTTP trust-boundary and lifecycle.
identifier
Package identifier creates and validates DANS resource and credential IDs.
Package identifier creates and validates DANS resource and credential IDs.
page
Package page implements bounded keyset-pagination cursors.
Package page implements bounded keyset-pagination cursors.
ratelimit
Package ratelimit meters identity request rate and DNS change throughput with Route 53-style token buckets shared by every API instance.
Package ratelimit meters identity request rate and DNS change throughput with Route 53-style token buckets shared by every API instance.
upstream
Package upstream connects DANS to its single PowerDNS API upstream.
Package upstream connects DANS to its single PowerDNS API upstream.
webconsole
Package webconsole serves the embedded browser application.
Package webconsole serves the embedded browser application.
openspec

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL