pending-dns 1.2.5 → 1.4.0

package/.github/codeql/codeql-config.yml

@@ -0,0 +1,11 @@
+name: "PendingDNS CodeQL config"
+
+# Exclude code that is not part of the production runtime from analysis.
+# These paths generate only false-positive noise:
+#   - the test suite intentionally disables TLS verification and resolves
+#     throwaway domains
+#   - the example scripts are developer helpers, not shipped code
+paths-ignore:
+    - test
+    - '**/test/**'
+    - example

package/.github/workflows/codeql.yml

@@ -0,0 +1,52 @@
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+  schedule:
+    - cron: '40 17 * * 6'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Skip release-please's auto-generated release PR: it only changes CHANGELOG/version,
+    # so there is no new code to scan. (Matches the guard in test.yml.)
+    if: ${{ !startsWith(github.ref_name, 'release-please--') && !startsWith(github.head_ref, 'release-please--') }}
+    runs-on: ubuntu-latest
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: javascript-typescript
+          build-mode: none
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        config-file: ./.github/codeql/codeql-config.yml
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

package/.github/workflows/deploy.yml

@@ -5,14 +5,27 @@ on:
 
 name: Deploy instance
 
+permissions:
+    contents: read
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
 jobs:
     deploy:
         name: Deploy
-        runs-on: ubuntu-latest
+        runs-on: ubuntu-24.04
+        timeout-minutes: 15
 
         steps:
             - name: Checkout
-              uses: actions/checkout@v2
+              uses: actions/checkout@v6
+
+            - name: Use Node.js 24
+              uses: actions/setup-node@v6
+              with:
+                  node-version: 24
 
             - name: Install SSH key
               uses: shimataro/ssh-key-action@v2
@@ -29,7 +42,7 @@ jobs:
               id: deploy
               run: |
                   echo $GITHUB_SHA > commit.txt
-                  npm install --production
+                  npm install --omit=dev
                   tar czf /tmp/${SERVICE_NAME}.tar.gz --exclude .git .
                   scp /tmp/${SERVICE_NAME}.tar.gz deploy@${TARGET_HOST_01}:
                   scp /tmp/${SERVICE_NAME}.tar.gz deploy@${TARGET_HOST_02}:

package/.github/workflows/release.yaml

@@ -0,0 +1,43 @@
+on:
+    push:
+        branches:
+            - master
+
+permissions:
+    contents: write
+    pull-requests: write
+    id-token: write
+
+name: Manage Release
+jobs:
+    release_please:
+        name: Create or prepare release
+        runs-on: ubuntu-24.04
+        outputs:
+            major: ${{ steps.release.outputs.major }}
+            minor: ${{ steps.release.outputs.minor }}
+            patch: ${{ steps.release.outputs.patch }}
+            release_created: ${{ steps.release.outputs.release_created }}
+        steps:
+            # Uses release-please-config.json and .release-please-manifest.json
+            # from the repository root (manifest mode).
+            - uses: googleapis/release-please-action@v4
+              id: release
+
+    publish:
+        name: Publish NPM package
+        runs-on: ubuntu-24.04
+        needs: release_please
+        if: ${{ needs.release_please.outputs.release_created }}
+        permissions:
+            contents: read
+            # Required for npm provenance / OIDC trusted publishing.
+            id-token: write
+        steps:
+            - uses: actions/checkout@v6
+            - uses: actions/setup-node@v6
+              with:
+                  node-version: 24
+                  registry-url: "https://registry.npmjs.org"
+            - run: npm ci
+            - run: npm publish --provenance --access public

package/.github/workflows/test.yml

@@ -0,0 +1,75 @@
+name: Run Tests
+
+on:
+    push:
+    pull_request:
+
+permissions:
+    contents: read
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    # Skip CI for release-please's auto-generated release PR / branch: it only bumps the
+    # version + CHANGELOG (no code change), so re-running the suite is wasted work.
+    license_check:
+        name: License Compliance Check
+        if: ${{ !startsWith(github.ref_name, 'release-please--') && !startsWith(github.head_ref, 'release-please--') }}
+        runs-on: ubuntu-24.04
+        timeout-minutes: 10
+        steps:
+            - uses: actions/checkout@v6
+            - name: Use Node.js 24
+              uses: actions/setup-node@v6
+              with:
+                  node-version: 24
+                  cache: npm
+            - run: npm install
+            - name: Run License Checks
+              run: npm run licenses
+
+    lint:
+        name: Lint
+        if: ${{ !startsWith(github.ref_name, 'release-please--') && !startsWith(github.head_ref, 'release-please--') }}
+        runs-on: ubuntu-24.04
+        timeout-minutes: 10
+        steps:
+            - uses: actions/checkout@v6
+            - name: Use Node.js 24
+              uses: actions/setup-node@v6
+              with:
+                  node-version: 24
+                  cache: npm
+            - run: npm install
+            - name: Run ESLint
+              run: npm run lint
+
+    unit:
+        name: Unit Tests
+        if: ${{ !startsWith(github.ref_name, 'release-please--') && !startsWith(github.head_ref, 'release-please--') }}
+        runs-on: ubuntu-24.04
+        timeout-minutes: 10
+        services:
+            redis:
+                image: redis
+                options: >-
+                    --health-cmd "redis-cli ping"
+                    --health-interval 10s
+                    --health-timeout 5s
+                    --health-retries 5
+                ports:
+                    - 6379:6379
+        steps:
+            - uses: actions/checkout@v6
+            - name: Use Node.js 24
+              uses: actions/setup-node@v6
+              with:
+                  node-version: 24
+                  cache: npm
+            - run: npm install
+            - name: Run tests
+              run: npm test
+              env:
+                  NODE_ENV: test

package/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+    ".": "1.4.0"
+}

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [1.4.0](https://github.com/postalsys/pending-dns/compare/v1.3.0...v1.4.0) (2026-06-20)
+
+
+### Features
+
+* add DNSSEC online signing, TLSA records, and EDNS UDP truncation ([414beb7](https://github.com/postalsys/pending-dns/commit/414beb7114d56f35e2d02e945abfb4125ee51404))
+* replace Bugsnag with self-hosted Sentry error reporting ([3b374c7](https://github.com/postalsys/pending-dns/commit/3b374c737ff0a22509f79976bee18ab9d425f8bd))
+
+## [1.3.0](https://github.com/postalsys/pending-dns/compare/pending-dns-v1.2.5...pending-dns-v1.3.0) (2026-06-18)
+
+
+### Features
+
+* replace Bugsnag with self-hosted Sentry error reporting ([3b374c7](https://github.com/postalsys/pending-dns/commit/3b374c737ff0a22509f79976bee18ab9d425f8bd))

package/CLAUDE.md

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+PendingDNS is a lightweight, API-driven **authoritative** DNS server (UDP + TCP), bundled with a REST API for managing zone records, a public HTTP/HTTPS redirect/proxy server, automatic Let's Encrypt certificate generation, and periodic health checks. All state lives in Redis.
+
+## Commands
+
+```bash
+npm start          # run the whole app (node server.js)
+npm test           # run the test suite (requires a local Redis on 127.0.0.1:6379)
+npm run lint       # ESLint 9 (flat config: eslint.config.js)
+npm run licenses   # regenerate licenses.txt (license-report)
+```
+
+Running the app or tests requires a reachable Redis and a config with a valid `acme.email` (the bootstrap in `server.js` exits otherwise). For local runs, either set it in `config/development.toml` or pass `--acme.email=you@example.com`.
+
+### Tests
+
+- Built on the Node.js built-in test runner (`node:test`). `npm test` runs `NODE_ENV=test node --test --test-force-exit --test-concurrency=1 test/*.test.js`.
+- `NODE_ENV=test` loads `config/test.toml`, which points Redis at a **dedicated database (db 15)**. `test/helpers.js#flushTestDb` wipes db 15 between cases and **refuses to run unless the Redis URL ends in `/15`** — so tests never touch dev (db 2) or prod data. Always run tests with `NODE_ENV=test`.
+- `--test-concurrency=1` is required because all test files share db 15. `--test-force-exit` is required because requiring `lib/db` opens persistent ioredis connections; every test file must also call `closeDb()` in an `after()` hook or the process hangs.
+- Some `cached-resolver`/`dns-server` tests do real DNS lookups (e.g. `one.one.one.one`); they are written to skip or tolerate missing network.
+
+Run a single file or filter by test name:
+
+```bash
+NODE_ENV=test node --test --test-force-exit test/zone-store.test.js
+NODE_ENV=test node --test --test-force-exit --test-name-pattern="wildcard" test/*.test.js
+```
+
+### Building standalone executables
+
+Executables are built with `@yao-pkg/pkg` (the maintained `pkg` fork) via the `pkg` block in `package.json`, targeting node24. The org-wide `../emailengine-api/upload.sh <repo>` script installs `@yao-pkg/pkg` globally, then runs `npm run build-source` followed by `npm run build-dist` (or `build-dist-fast` for an unsigned test build) and signs/notarizes/uploads the artifacts. Output binaries are named `pending-dns-<target>` under `ee-dist/`.
+
+Because workers are loaded through **dynamic `require()` / `worker_threads`** (see below), `pkg.scripts` must list `lib/**/*.js` and `workers/**/*.js` or the worker code is missing from the snapshot. Runtime files read via `__dirname` (`lib/lua/health.lua`, `config/*.pem`) must be in `pkg.assets`. Do **not** add `pkg.options` like `max_old_space_size`: the workers forward `argv`, and an injected V8 flag leaks in as a bogus module path and crashes every worker.
+
+## Architecture
+
+### Process model (the most important thing to understand)
+
+`server.js` is the supervisor. For each enabled subsystem (`api`, `dns`, `public`, `health`) it spawns a **worker thread** running `workers/<type>.js`, and restarts it on exit. Each `workers/<type>.js` is itself a small bootstrap that:
+
+1. installs crash handlers + optional Sentry error reporting via `lib/sentry.js#initSentry` (only when `SENTRY_DSN` / `[sentry] dsn` is set; uses Sentry's uncaught-exception / unhandled-rejection integrations so crashes are reported, then `closeProcess`'s `if (!logger.errorReportingEnabled)` lets Sentry flush+exit),
+2. uses Node `cluster` to fork `config[type].workers` processes (or runs in-thread when `workers === 1` and no user/group drop is configured),
+3. dynamically `require`s the implementation: ``require(`../lib/${type}-server.js`)`` (or `-worker.js` for `health`) and calls it,
+4. drops privileges via `config.process.user`/`group` after ports are bound.
+
+So `lib/<type>-server.js` are entry points reached **only through dynamic requires** — static analysis (and `pkg`) won't find them. The implementations are: `lib/api-server.js`, `lib/dns-server.js`, `lib/public-server.js`, `lib/health-worker.js`.
+
+### Configuration (`wild-config`)
+
+Config is loaded by `wild-config` from `config/default.toml` merged with `config/<NODE_ENV>.toml`, then overridden by CLI args (`--dns.port=53`) and `appconf_*` env vars. `NODE_CONFIG_PATH` points to an external file in production (see `systemd/pending-dns.service`). Values are coerced to the type of the default (a string env var for a numeric default becomes a number). Config is read from `process.cwd()/config`, **not** from `__dirname` — relevant for packaged binaries, which need a `config/` directory next to them.
+
+### Redis data model (`lib/zone-store.js`)
+
+This is the heart of the system and is non-obvious:
+
+- **Domain names are stored label-reversed**: `www.example.com` → `com.example.www` (`domainToName`/`nameToDomain`). This lets `resolveZone` walk *up* from a name to its registered zone by progressively dropping the most-specific label. A "zone" is any name with a `d:<name>:z` set; the shortest possible zone is the 2-label boundary (e.g. `example.com`).
+- Keys: `d:<name>:z` is a **set of record keys** belonging to that zone; `d:<name>:r:<TYPE>` is a **hash** of `hid → JSON.stringify(valueArray)`. Each record's value is a positional array whose meaning depends on type (e.g. A = `[address, healthCheckUri]`, MX = `[exchange, priority]`, CAA = `[value, tag, flags]`, TLSA = `[usage, selector, matchingType, certificate]`, URL = `[url, code, proxy]`).
+- A record's public **ID is `base64url(name \x01 TYPE \x01 hid)`** (`getFullId`/`parseFullId`); `hid` is a `nanoid()`. IDs are opaque and stable only while domain+type are unchanged (an `update` that changes either deletes and re-adds, producing a new ID).
+- **Wildcards** are single-label: a record stored under subdomain `*.foo` matches `anything.foo.<zone>` only (`resolve` retries with the last label replaced by `*`).
+- **Read/write split**: reads go to `db.redisRead`, writes to `db.redisWrite` (configurable as separate master/replica URLs). The health-check Lua script `lib/lua/health.lua` is registered as a custom command `nextHealth` on the write client.
+
+### DNS request handling (`lib/dns-handler.js` + custom servers)
+
+`lib/dns-udp-server.js` and `lib/dns-tcp-server.js` are hand-rolled servers that parse/serialize with `dns2`'s `Packet` (the project does **not** use dns2's built-in server). `lib/dns-server.js` wires them to `dnsHandler` and returns the bound server handles.
+
+`processQuestion` does more than a lookup: for an A/AAAA query it also pulls `CNAME`, `ANAME`, and `URL` records; it follows CNAME chains recursively (depth-limited); A/AAAA results are health-filtered and shuffled; MX is priority-sorted. When nothing is stored it synthesizes fallbacks — `NS` from `config.ns`, a `SOA` from `config.soa`, default Let's Encrypt `CAA` records, and `version.bind`-style CHAOS TXT answers.
+
+Two pseudo-record types: **ANAME** (apex alias) is resolved to real A/AAAA at query time via `lib/cached-resolver.js` (a Redis-cached wrapper over Node's `dns.Resolver`, with soft/hard TTLs for both hits and errors). **URL** records answer A/AAAA with the redirect server IPs from `config.public.hosts`; the actual redirect/proxy happens in `lib/public-server.js`.
+
+### DNSSEC online signing (`lib/dnssec.js`, `lib/dnssec-wire.js`)
+
+DNSSEC is **online (query-time) signing**, gated on `[dnssec] enabled` AND a per-zone key AND the client's EDNS **DO** bit. `lib/dnssec-wire.js` is a pure, dependency-free (only `crypto` + `ipaddr.js`) wire/crypto layer: canonical RDATA/name encoding (RFC 4034 6.2), the `ALGS` table for algorithms 8/13/15, key-tag + DS-digest computation, NSEC bitmaps, and RRSIG encoding. **Invariant:** signatures are computed over the canonical uncompressed lowercased wire form produced here, never over dns2's serialization (validators decompress + downcase before verifying, so the two agree).
+
+`lib/dnssec.js` owns per-zone keys and signing orchestration. Keys live in Redis: `d:dnssec:<revname>` is the state hash (`enabled`, `algorithm`, `activeKeyTag`) and `d:dnssec:<revname>:keys` is a hash of `hid → JSON` (private key PEM + public material). A zone has one **CSK** per algorithm; an algorithm rollover keeps both and signs with every algorithm (RFC 6840 5.11) until `removeKey`. `getSigner` assembles + caches the signer per process (short `signerCacheTtl`, since API and DNS run as separate workers); `enableZone`/`removeKey`/`disableZone` mutate under a shared Redis lock (`lib/lock.js`) and invalidate the cache.
+
+The query-time path is `lib/dns-handler.js#signResponse` (DO queries only): it serves+self-signs DNSKEY at the apex, signs each in-zone RRset (`signSection`, but never a below-apex delegation NS — RFC 4035 2.2), and proves denial-of-existence as **NODATA (NOERROR) "black lies"** — a signed SOA + a compact NSEC at the queried name (`bitmapTypeNums`/`nsecRecord`), never NXDOMAIN or NSEC3, because the server synthesizes CAA/SOA for any name. The NSEC bitmap lists only **answerable** types and must exclude the queried-absent type (e.g. a `URL` record only advertises the `config.public.hosts` families) or a validator SERVFAILs. The API (`lib/api-server.js`) exposes `GET/POST/DELETE /v1/zone/{zone}/dnssec` and `DELETE .../dnssec/key/{keyTag}`.
+
+**TLSA** records are stored as `[usage, selector, matchingType, certificate]` (even-length hex, guarded in the API Joi schema, the store's `add`/`update`, and `encodeTLSARdata`). dns2 has no TLSA/RRSIG/NSEC/DS encoder, so those are emitted as `{ type:<num>, data:<Buffer> }` and routed through dns2's raw-RDATA (RFC 3597) fallback; `dns-handler.js` merges `wire.EXTRA_TYPES` into its type maps to recognize them.
+
+**EDNS / truncation** (`lib/dns-server.js`): `parseEdns` reads the OPT (DO bit + advertised payload size); `finalizeResponse` replaces the additional section with our own OPT and, for UDP, truncates with TC=1 above the smaller of the requestor's advertised size and our configured `udpPayloadSize` (anti-fragmentation), so the client retries over TCP.
+
+### Certificates & the public server
+
+`lib/certs.js` issues Let's Encrypt certs via the **dns-01** challenge, using the zone store itself as the ACME DNS provider (it writes/reads the `_acme-challenge` TXT records). Concurrent issuance is guarded with an `ioredfour` Redis lock (the shared `lib/lock.js`, also used by DNSSEC key management; callers namespace their own lock keys); results and a per-domain renewal lock are cached in Redis. `lib/public-server.js` uses an SNI callback to load the right cert per hostname (falling back to a bundled self-signed cert in `config/`), then serves URL-record redirects or reverse-proxies (`proxy=true`), with TLS session tickets stored in Redis.
+
+### Testability seams
+
+Production code exposes hooks used only by tests: `lib/api-server.js` exports `createServer()` (build the Hapi server without `start()`, for `server.inject()`); `lib/dns-server.js`'s `init()` awaits binding and returns `{ udpServer, tcpServer }`, and also attaches `.testables` (`parseEdns`, `finalizeResponse`); `lib/dns-handler.js` (`signResponse`, `bitmapTypeNums`, `processQuestion`, ...), `lib/certs.js`, and `lib/dnssec.js` attach a `.testables` object. `lib/dnssec-wire.js` is pure and is tested directly.
+
+## CI / release
+
+GitHub Actions mirror the `postalsys/emailengine` conventions and run on Node 24: `test.yml` (license check + lint + tests with a Redis service), `codeql.yml`, and `release.yaml` (release-please in manifest mode — see `release-please-config.json` + `.release-please-manifest.json`; publishes to npm via OIDC trusted publishing, which must be configured registry-side). `deploy.yml` tarballs the repo and ships it to the two name servers. Security policy lives in `SECURITY.md` + a GPG-signed `SECURITY.txt`.
+
+## Commit conventions
+
+- Use **Conventional Commits** (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `ci:`, etc.). release-please derives the version bump and `CHANGELOG.md` from these prefixes, so `feat:`/`fix:` commits landing on `master` are what open a release PR.
+- **Do not** add Claude (or any AI assistant) as a co-author / co-contributor in commit messages.
+- For commits that do not change runtime behaviour (docs, comments, CI/workflow tweaks, formatting), append `[skip ci]` to the commit message to avoid triggering the workflows. **Exception:** never add `[skip ci]` to a `feat:`/`fix:` commit — those must run so the release workflow fires.
+- Run `npm run lint` and `npm test` before committing (the test run needs a local Redis; see the Tests section).
+- After pushing, check the workflow runs (`gh run list --branch <branch>`) and report their status. If a run fails for an unrelated infrastructure reason (auth errors, HTTP 403, "account suspended"), check <https://www.githubstatus.com/> for an active incident before assuming the change is at fault.
+
+## Code style
+
+- No emojis in code or documentation — printable ASCII only.
+- Use a single hyphen-minus (`-`) as a dash in user-facing strings and docs; never em dashes, en dashes, or double hyphens (`--`).
+- Never swallow errors at the global `uncaughtException` / `unhandledRejection` handlers to keep a worker alive — those handlers are the last line of defence and the worker is expected to exit. Fix the error at its source (add the missing `try/catch`, `.catch()`, or `error` listener at the call site) instead.

package/README.md

@@ -6,11 +6,12 @@ Lightweight API driven Authoritative DNS server.
 
 -   All records can be edited over **REST API**
 -   All **changes are effective immediatelly** (or as long as it takes for Redis - eg. the backend for storing data - to distribute changes from master to replica instances)
--   **Basic record types** (A, AAAA, CNAME, TXT, MX, CAA)
+-   **Basic record types** (A, AAAA, CNAME, TXT, MX, CAA, NS, TLSA)
 -   **ANAME pseudo-record** for apex domains
 -   **URL pseudo-record** for HTTP and HTTPS redirects. Valid HTTPS certificates are generated automatically, HTTPS host gets A+ rating from SSLabs.
 -   URL record can be turned into a **Cloudflare-like proxying** by using `proxy=true` flag. Though, while Cloudflare makes things faster then PendingDNS makes things slightly slower due to not caching anything.
 -   Periodic **health checks** to filter out unhealthy A/AAAA records
+-   **DNSSEC** with online (live) signing, enabled per zone over the API
 -   **Lightweight**
 -   Can be **geographically distributed**. All writes go to central Redis master, all reads are done from local Redis replica
 -   Request **certificates over API**
@@ -19,19 +20,20 @@ Lightweight API driven Authoritative DNS server.
 
 -   No support for zone files, all records must be managed over API
 -   Only the most basic and common record types
--   No support for DNSSEC
+-   DNSSEC uses online signing; denial of existence is NODATA (NOERROR) with compact NSEC "black lies" (no NSEC3, no true NXDOMAIN). Algorithm rollover is supported by re-enabling a zone with a new algorithm; there is no automated scheduled key rollover
 -   Only plain old DNS over UDP and TCP, no DoH, no DoT
+-   UDP responses are capped at the smaller of the requestor's advertised EDNS payload size and the server's configured `[dnssec] udpPayloadSize` (1232 by default; 512 when the requestor advertises no EDNS), and truncated with TC=1 above that limit, per RFC 1035; clients then retry over TCP
 -   Barely tested on [Project Pending](https://projectpending.com/). Do not use this for mission critical domains. PendingDNS is only good for leftover domains, ie. for development and testing.
 
 ## Requirements
 
--   **Node.js**, preferrably v12+
+-   **Node.js**, v18 or newer
 -   **Redis**, any version should do as only basic commands are used
 
 ## Usage
 
 ```
-$ npm install --production
+$ npm install --omit=dev
 $ npm start
 ```
 
@@ -45,9 +47,9 @@ As root run the following commands to set up PendingDNS:
 
 ```
 $ cd /opt
-$ git clone git://github.com/postalsys/pending-dns.git
+$ git clone https://github.com/postalsys/pending-dns.git
 $ cd pending-dns
-$ npm install --production
+$ npm install --omit=dev
 $ cp systemd/pending-dns.service /etc/systemd/system
 $ cp config/default.toml /etc/pending-dns.toml
 ```
@@ -110,6 +112,28 @@ Without proper setup domain registrars do not allow your name server domain name
 
 ![](https://cldup.com/l0U6jc5pfM.png)
 
+## Development
+
+Install all dependencies (including dev dependencies):
+
+```
+$ npm install
+```
+
+### Tests
+
+The test suite runs with the built-in Node.js test runner and needs a **local Redis** instance listening on `127.0.0.1:6379`. Tests use a dedicated database (`db 15`) which is flushed between runs, so it does not touch development or production data.
+
+```
+$ npm test
+```
+
+### Linting
+
+```
+$ npm run lint
+```
+
 ## API
 
 You can see the entire API docs from the swagger page at http://127.0.0.1:5080/docs
@@ -129,7 +153,8 @@ $ curl -X GET "http://127.0.0.1:5080/v1/zone/mailtanker.com/records"
         {
             "id": "Y29tLm1haWx0YW5rZXIBQQEzc3lKWkkzbGo",
             "type": "A",
-            "address": "18.203.150.145"
+            "address": "18.203.150.145",
+            "healthCheck": false
         },
         {
             "id": "Y29tLm1haWx0YW5rZXIud3d3AUNOQU1FAXhhV1lnbnFaMA",
@@ -165,7 +190,7 @@ $ curl -X POST "http://127.0.0.1:5080/v1/zone/mailtanker.com/records" -H "Conten
 All record types have the following properties
 
 -   **subdomain** (optional) subdomain this record applies to. If blank, or "@" or missing then the record is created for zone domain.
--   **type** one of A, AAAA, CNAME, ANAME, URL, MX, TXT, CAA, NS
+-   **type** one of A, AAAA, CNAME, ANAME, URL, MX, TXT, CAA, NS, TLSA
 
 #### Type specific options
 
@@ -203,7 +228,16 @@ All record types have the following properties
 **CAA**
 
 -   **value** is the domain name of the provider, eg. `letsencrypt.org`
--   **tag** is the CAA tag, eg. `issue` or `issuewild`
+-   **tag** is the CAA tag, one of `issue`, `issuewild` or `iodef`
+-   **flags** (Number, default is `0`) is the CAA flags octet (0-255)
+
+**TLSA**
+
+-   **subdomain** typically uses the DANE form `_port._proto`, eg. `_443._tcp.www`
+-   **usage** (Number, 0-3) certificate usage: 0 PKIX-TA, 1 PKIX-EE, 2 DANE-TA, 3 DANE-EE
+-   **selector** (Number, 0-1) 0 for the full certificate, 1 for the SubjectPublicKeyInfo
+-   **matchingType** (Number, 0-2) 0 full, 1 SHA-256, 2 SHA-512
+-   **certificate** (String) the certificate association data as a hex string
 
 **URL**
 
@@ -276,6 +310,74 @@ $ curl -X POST "http://127.0.0.1:5080/v1/acme" -H "Content-Type: application/jso
 }
 ```
 
+### DNSSEC
+
+PendingDNS signs answers **online** (at query time) for zones that have DNSSEC enabled. DNSSEC must be turned on globally (`[dnssec] enabled = true`) and then enabled per zone over the API; enabling a zone generates a signing key (a CSK) that is stored in Redis and used to sign every RRset on the fly. Signing only happens for clients that set the EDNS DO bit. Denial of existence is always **NODATA (NOERROR)** with a signed compact NSEC ("black lies"): because the server can synthesize CAA/NS/SOA for any name, no name is treated as truly nonexistent, so there is no NXDOMAIN and no NSEC3.
+
+After enabling a zone you must copy the returned **DS** record to the parent zone at your registrar to complete the chain of trust.
+
+**Enable DNSSEC for a zone**
+
+**POST /v1/zone/{zone}/dnssec**
+
+The optional `algorithm` selects the signing algorithm: `13` ECDSA P-256/SHA-256 (default), `15` Ed25519, or `8` RSASHA256.
+
+```
+$ curl -X POST "http://127.0.0.1:5080/v1/zone/mailtanker.com/dnssec" -H "Content-Type: application/json" -d '{
+    "algorithm": 13
+}'
+```
+
+```json
+{
+    "zone": "mailtanker.com",
+    "enabled": true,
+    "algorithm": 13,
+    "keyTag": 48234,
+    "ds": [{ "keyTag": 48234, "algorithm": 13, "digestType": 2, "digest": "a4f5...", "presentation": "48234 13 2 a4f5..." }],
+    "dnskey": [{ "flags": 257, "protocol": 3, "algorithm": 13, "publicKey": "GjL2...", "keyTag": 48234, "presentation": "257 3 13 GjL2..." }]
+}
+```
+
+**Get DNSSEC status (DS and DNSKEY records)**
+
+**GET /v1/zone/{zone}/dnssec**
+
+```
+$ curl -X GET "http://127.0.0.1:5080/v1/zone/mailtanker.com/dnssec"
+```
+
+Returns the same `enabled`, `algorithm`, `keyTag`, `ds` and `dnskey` shape as the enable response. For a zone that has never had DNSSEC enabled, `enabled` is `false` and the `ds`/`dnskey` arrays are empty.
+
+**Disable DNSSEC for a zone**
+
+**DELETE /v1/zone/{zone}/dnssec**
+
+```
+$ curl -X DELETE "http://127.0.0.1:5080/v1/zone/mailtanker.com/dnssec"
+```
+
+```json
+{
+    "zone": "mailtanker.com",
+    "disabled": true
+}
+```
+
+**Roll the signing key to a new algorithm**
+
+Re-POST to the enable endpoint with a different `algorithm`. A new key is generated and kept alongside the old one, and the zone is signed with **both** algorithms (every RRset gets an RRSIG per algorithm) so validation keeps working during the rollover. The response lists every key in `ds`/`dnskey`. Publish the new **DS** at the registrar, wait for the old DS TTL to expire, then remove the old key.
+
+**Remove a signing key (finish a rollover)**
+
+**DELETE /v1/zone/{zone}/dnssec/key/{keyTag}**
+
+Removes a non-active key. Removing the active key or the last remaining key is refused.
+
+```
+$ curl -X DELETE "http://127.0.0.1:5080/v1/zone/mailtanker.com/dnssec/key/48234"
+```
+
 ## Acknowledgments
 
 -   All DNS parsing / compiling is done using [dns2](https://www.npmjs.com/package/dns2) module by [Liu Song](https://github.com/song940)

package/SECURITY.md

@@ -0,0 +1,88 @@
+# Security Policy
+
+PendingDNS is a lightweight, API-driven authoritative DNS server. It also runs a
+public HTTP/HTTPS redirect/proxy server and generates Let's Encrypt certificates
+over an ACME flow, and it stores all zone data in Redis. Because it is exposed to
+untrusted DNS and HTTP traffic and handles certificate private keys, we take
+security reports seriously and aim to respond quickly.
+
+## Supported Versions
+
+Security fixes are released only against the latest version. We do not backport
+patches to older releases - upgrading to the current release line is the
+supported way to receive security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x     | :white_check_mark: |
+| < 1.0   | :x:                |
+
+If you are on an older version, please upgrade. See the release notes at
+<https://github.com/postalsys/pending-dns/releases> before updating.
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues,
+pull requests, or discussions.**
+
+Report privately through one of the following channels:
+
+1. **GitHub Security Advisories (preferred).** Open a private report at
+   <https://github.com/postalsys/pending-dns/security/advisories/new>. This keeps
+   the discussion private until a fix is published and lets us credit you.
+2. **Email.** Send details to **andris@postalsys.com** (the contact listed in
+   [`SECURITY.txt`](SECURITY.txt)). Encrypt sensitive details if possible using
+   the key referenced there.
+
+When reporting, please include as much of the following as you can:
+
+- The affected version(s) and environment (PendingDNS version, Node.js version,
+  OS, deployment method - npm or prebuilt binary).
+- The component involved (e.g. the UDP/TCP DNS server, the REST API, the public
+  HTTP/HTTPS redirect and proxy server, ACME certificate generation, health
+  checks, or the Redis-backed zone store).
+- A clear description of the issue and its impact (e.g. cache poisoning, DNS
+  amplification, request smuggling, SSRF via the URL/proxy records or health
+  checks, certificate mis-issuance, credential or private-key disclosure,
+  injection, information disclosure, denial of service).
+- A minimal proof of concept or reproduction steps.
+- Any suggested remediation, if you have one.
+
+We are a small team, so there is no guaranteed response time - sometimes reports
+are handled within hours, sometimes they take longer. Accepted issues are fixed
+in a new release and coordinated through a GitHub Security Advisory, and
+reporters who wish to be named are credited.
+
+## CVEs
+
+We track and disclose vulnerabilities through GitHub Security Advisories. We do
+not request or manage CVE identifiers ourselves. If you need a CVE assigned for a
+reported issue, please request one yourself - for example, through GitHub's own
+CVE request flow on the published advisory, or another CNA.
+
+## Scope
+
+In scope: the PendingDNS application source in this repository - the
+authoritative DNS server (UDP and TCP), the REST API for managing zone records,
+the public HTTP/HTTPS redirect and proxy server, ACME/Let's Encrypt certificate
+generation and storage, the health-check subsystem, and the Redis-backed zone
+store.
+
+Out of scope:
+
+- Vulnerabilities in your own application code or automation that integrates
+  with the PendingDNS API.
+- Misconfiguration of your deployment - for example, exposing the management API
+  to untrusted networks, an unauthenticated or publicly reachable Redis instance,
+  binding the DNS server in a way that enables open-resolver-style abuse, or
+  missing TLS on the API.
+- The inherent properties of plain DNS over UDP/TCP without DNSSEC (PendingDNS
+  does not implement DNSSEC, DoH, or DoT by design).
+- Issues that require an already-compromised host or pre-existing administrator
+  access.
+- Vulnerabilities in third-party services PendingDNS connects to (Let's Encrypt,
+  upstream resolvers, health-check targets).
+- Social-engineering reports and missing security headers without a
+  demonstrated, concrete impact.
+
+Thank you for helping keep PendingDNS and its users safe.