Add standard Workflow section to TODO.md

TODO.md

@@ -0,0 +1,143 @@
+# Workflow
+
+* branch (from `main`)
+* do the work in Next Step
+* move Next Step to the top of Completed Steps
+* move the top item of Future Steps into Next Step
+* commit (`TODO.md` changes in the same commit as the work)
+* merge to `main` if the branch is not protected, otherwise open a PR
+* push
+
+# Status
+
+pre-1.0. No git tags. Core resolver work in flight on feature/resolver
+(dirty: internal/resolver/resolver_test.go). Local checkout has diverged
+from origin: origin/main is 8 commits ahead (watcher orchestrator,
+unified TARGETS) and origin/feature/resolver already contains the full
+iterative resolver implementation with hermetic mocked tests.
+
+# Next Step
+
+Policy scaffold commit: add LICENSE, REPO_POLICIES.md, .editorconfig,
+.dockerignore, and .gitea/workflows/check.yml, and add the missing
+fmt-check, docker, and hooks targets to the Makefile. One commit, then
+confirm make check still passes.
+
+# Completed Steps
+
+- 2026-02-20: iterative DNS resolver implemented; tests made hermetic
+  with mocked DNS (origin/feature/resolver, unmerged)
+- 2026-02-20: CI actions and go install refs pinned to commit SHAs;
+  Gitea Actions workflow for make check (origin/ci/make-check, unmerged)
+- 2026-02-20: watcher monitoring orchestrator merged to main (#8)
+- 2026-02-20: DOMAINS/HOSTNAMES unified into single TARGETS config (#11)
+- 2026-02-19: TCP port connectivity checker, made concurrent with port
+  validation; gosec G704 SSRF findings fixed without suppression
+  (feature branches, unmerged)
+- 2026-02-19: TLS certificate inspector with no-peer-certificates error
+  path and IP SANs (feature branch, unmerged)
+- 2026-02-19: gosec SSRF and formatting fixes on main
+- 2026-02-19: initial scaffold with per-nameserver DNS monitoring model
+
+# Future Steps
+
+Compliance:
+
+- Add README sections required by policy (Description, Getting Started,
+  Rationale, Design, TODO, License, Author) if any are missing
+- Pin Dockerfile base images by sha256 and ensure the Docker build runs
+  make check
+
+Branch reconciliation:
+
+- Sync local checkout with origin: local main is 8 commits behind
+  origin/main; local feature/resolver has diverged from
+  origin/feature/resolver, which already implements the resolver
+- Merge in-flight branches to main once green: feature/resolver,
+  ci/make-check, feature/portcheck-implementation,
+  feature/tlscheck-implementation
+
+Resolver (plan from untracked TODO.md; largely implemented on
+origin/feature/resolver, verify each item before closing):
+
+- Add github.com/miekg/dns dependency
+- roots.go: hardcoded IANA root server list (a through m, IPv4/IPv6),
+  rootServers() returning ip:53 strings
+- query.go: low-level query(ctx, server, name, qtype): UDP with TCP
+  fallback on truncation, RD=0, context respected, 5s per-query timeout,
+  returns raw *dns.Msg
+- trace.go: iterative delegation chasing from roots: referral detection
+  (NOERROR, empty answer, NS in authority), glue extraction with
+  bailiwick check, out-of-bailiwick NS resolved with recursion guard,
+  delegation depth limit (20), retry across nameservers on failure, do
+  not chase CNAMEs inside trace
+- FindAuthoritativeNameservers: NS set via trace, sorted, FQDN
+  normalized, trailing dot handled; must pass its 9 tests
+- QueryNameserver: resolve NS host to IPs, query A/AAAA/CNAME/MX/TXT/
+  SRV/CAA/NS, build NameserverResponse with status mapping (OK,
+  NXDomain, NoData, Error), documented record formatting, sorted values,
+  lame delegation detection; must pass its 16 tests
+- QueryAllNameservers: find NS set for parent domain (public suffix
+  list), query all NS in parallel with bounded concurrency, return map
+  even when all fail, context cancellation; must pass its 4 tests
+- LookupNS: thin wrapper over FindAuthoritativeNameservers, sorted,
+  identical results; must pass its 3 tests
+- ResolveIPAddresses: collect A/AAAA from all NS, follow CNAME chains
+  with MaxCNAMEDepth, dedupe, sort, NXDOMAIN returns empty slice with
+  nil error; must pass its 9 tests
+- All 39 resolver tests pass, make check green, merge to main
+
+Watcher (internal/watcher/watcher.go):
+
+- Scheduling loop in Run(ctx): initial check on startup, separate
+  tickers for DNS/port and TLS intervals, persist state via state.Save()
+  after each cycle, clean shutdown on context cancel
+- Domain check: LookupNS, compare to stored state, store silently on
+  first run, notify with old/new NS lists on change
+- Hostname check: QueryAllNameservers, compare per-NS records; notify on
+  record changes, NS failure, NS recovery, inconsistency detected,
+  inconsistency resolved, empty response; store silently on first run
+- Port check: ResolveIPAddresses, check ports 80 and 443 per IP, notify
+  on open/closed transitions, handle new and disappeared IPs
+- TLS check: for each open IP:443, CheckCertificate; notify on expiry
+  warning, certificate change (CN/issuer/SANs), TLS failure/recovery
+
+Port checker (internal/portcheck/portcheck.go):
+
+- Tests against known-open ports and RFC documentation IPs
+- CheckPort: net.DialTimeout (5s), context respected; (true, nil) open,
+  (false, nil) closed/timeout/refused, error only for unexpected
+  failures
+
+TLS checker (internal/tlscheck/tlscheck.go):
+
+- Tests against known public HTTPS servers, verify fields populated
+- CheckCertificate: tls.Dial to specific IP:443 with hostname as SNI;
+  extract subject CN, issuer CN and org, NotAfter, SANs; error on
+  handshake failure
+
+Notification service (internal/notify/notify.go, Slack/Mattermost/ntfy
+backends exist):
+
+- Structured notification types: DNS change, port change, TLS expiry,
+  TLS change, NS failure, NS recovery, NS inconsistency
+- Per-backend formatting: Slack/Mattermost attachment colors (red
+  failures/expiry, yellow warnings, green recoveries, blue info); ntfy
+  priorities (urgent failures, high warnings, default changes, low
+  recoveries); include hostname, nameserver, old/new values, timestamps
+
+HTTP API handlers:
+
+- Wire *state.State and *watcher.Watcher into handler params
+- GET /api/v1/status: full state snapshot as JSON
+- GET /api/v1/domains: domain states with NS records and last-checked
+- GET /api/v1/hostnames: hostname states with per-NS record data
+
+Infrastructure notes (from untracked TODO.md):
+
+- Module path sneak.berlin/go/dnswatcher differs from the git.eeqj.de
+  remote intentionally; do not "fix" it
+- Dependencies: github.com/miekg/dns, golang.org/x/net/publicsuffix
+- Resolver tests originally used live DNS against *.dns.sneak.cloud
+  (required records documented in the test file header); origin now has
+  mocked hermetic tests, keep them hermetic

internal/notify/notify.go

@@ -1,5 +1,4 @@
-// Package notify provides notification delivery to Slack,
-// Mattermost, and ntfy.
+// Package notify provides notification delivery to Slack, Mattermost, and ntfy.
 package notify
 
 import (
@@ -8,7 +7,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"io"
 	"log/slog"
 	"net/http"
 	"net/url"
@@ -36,66 +34,8 @@ var (
 	ErrMattermostFailed = errors.New(
 		"mattermost notification failed",
 	)
-	// ErrInvalidScheme is returned for disallowed URL schemes.
-	ErrInvalidScheme = errors.New("URL scheme not allowed")
-	// ErrMissingHost is returned when a URL has no host.
-	ErrMissingHost = errors.New("URL must have a host")
 )
 
-// IsAllowedScheme checks if the URL scheme is permitted.
-func IsAllowedScheme(scheme string) bool {
-	return scheme == "https" || scheme == "http"
-}
-
-// ValidateWebhookURL validates and sanitizes a webhook URL.
-// It ensures the URL has an allowed scheme (http/https),
-// a non-empty host, and returns a pre-parsed *url.URL
-// reconstructed from validated components.
-func ValidateWebhookURL(raw string) (*url.URL, error) {
-	u, err := url.ParseRequestURI(raw)
-	if err != nil {
-		return nil, fmt.Errorf("invalid URL: %w", err)
-	}
-
-	if !IsAllowedScheme(u.Scheme) {
-		return nil, fmt.Errorf(
-			"%w: %s", ErrInvalidScheme, u.Scheme,
-		)
-	}
-
-	if u.Host == "" {
-		return nil, fmt.Errorf("%w", ErrMissingHost)
-	}
-
-	// Reconstruct from parsed components.
-	clean := &url.URL{
-		Scheme:   u.Scheme,
-		Host:     u.Host,
-		Path:     u.Path,
-		RawQuery: u.RawQuery,
-	}
-
-	return clean, nil
-}
-
-// newRequest creates an http.Request from a pre-validated *url.URL.
-// This avoids passing URL strings to http.NewRequestWithContext,
-// which gosec flags as a potential SSRF vector.
-func newRequest(
-	ctx context.Context,
-	method string,
-	target *url.URL,
-	body io.Reader,
-) *http.Request {
-	return (&http.Request{
-		Method: method,
-		URL:    target,
-		Host:   target.Host,
-		Header: make(http.Header),
-		Body:   io.NopCloser(body),
-	}).WithContext(ctx)
-}
-
 // Params contains dependencies for Service.
 type Params struct {
 	fx.In
@@ -107,7 +47,7 @@ type Params struct {
 // Service provides notification functionality.
 type Service struct {
 	log                  *slog.Logger
-	transport            http.RoundTripper
+	client               *http.Client
 	config               *config.Config
 	ntfyURL              *url.URL
 	slackWebhookURL      *url.URL
@@ -120,41 +60,33 @@ func New(
 	params Params,
 ) (*Service, error) {
 	svc := &Service{
-		log:       params.Logger.Get(),
-		transport: http.DefaultTransport,
-		config:    params.Config,
+		log: params.Logger.Get(),
+		client: &http.Client{
+			Timeout: httpClientTimeout,
+		},
+		config: params.Config,
 	}
 
 	if params.Config.NtfyTopic != "" {
-		u, err := ValidateWebhookURL(
-			params.Config.NtfyTopic,
-		)
+		u, err := url.ParseRequestURI(params.Config.NtfyTopic)
 		if err != nil {
-			return nil, fmt.Errorf(
-				"invalid ntfy topic URL: %w", err,
-			)
+			return nil, fmt.Errorf("invalid ntfy topic URL: %w", err)
 		}
 
 		svc.ntfyURL = u
 	}
 
 	if params.Config.SlackWebhook != "" {
-		u, err := ValidateWebhookURL(
-			params.Config.SlackWebhook,
-		)
+		u, err := url.ParseRequestURI(params.Config.SlackWebhook)
 		if err != nil {
-			return nil, fmt.Errorf(
-				"invalid slack webhook URL: %w", err,
-			)
+			return nil, fmt.Errorf("invalid slack webhook URL: %w", err)
 		}
 
 		svc.slackWebhookURL = u
 	}
 
 	if params.Config.MattermostWebhook != "" {
-		u, err := ValidateWebhookURL(
-			params.Config.MattermostWebhook,
-		)
+		u, err := url.ParseRequestURI(params.Config.MattermostWebhook)
 		if err != nil {
 			return nil, fmt.Errorf(
 				"invalid mattermost webhook URL: %w", err,
@@ -167,8 +99,7 @@ func New(
 	return svc, nil
 }
 
-// SendNotification sends a notification to all configured
-// endpoints.
+// SendNotification sends a notification to all configured endpoints.
 func (svc *Service) SendNotification(
 	ctx context.Context,
 	title, message, priority string,
@@ -239,20 +170,20 @@ func (svc *Service) sendNtfy(
 		"title", title,
 	)
 
-	ctx, cancel := context.WithTimeout(
-		ctx, httpClientTimeout,
-	)
-	defer cancel()
-
-	body := bytes.NewBufferString(message)
-	request := newRequest(
-		ctx, http.MethodPost, topicURL, body,
+	request, err := http.NewRequestWithContext(
+		ctx,
+		http.MethodPost,
+		topicURL.String(),
+		bytes.NewBufferString(message),
 	)
+	if err != nil {
+		return fmt.Errorf("creating ntfy request: %w", err)
+	}
 
 	request.Header.Set("Title", title)
 	request.Header.Set("Priority", ntfyPriority(priority))
 
-	resp, err := svc.transport.RoundTrip(request)
+	resp, err := svc.client.Do(request) //nolint:gosec // URL validated at Service construction time
 	if err != nil {
 		return fmt.Errorf("sending ntfy request: %w", err)
 	}
@@ -261,8 +192,7 @@ func (svc *Service) sendNtfy(
 
 	if resp.StatusCode >= httpStatusClientError {
 		return fmt.Errorf(
-			"%w: status %d",
-			ErrNtfyFailed, resp.StatusCode,
+			"%w: status %d", ErrNtfyFailed, resp.StatusCode,
 		)
 	}
 
@@ -302,11 +232,6 @@ func (svc *Service) sendSlack(
 	webhookURL *url.URL,
 	title, message, priority string,
 ) error {
-	ctx, cancel := context.WithTimeout(
-		ctx, httpClientTimeout,
-	)
-	defer cancel()
-
 	svc.log.Debug(
 		"sending webhook notification",
 		"url", webhookURL.String(),
@@ -325,19 +250,22 @@ func (svc *Service) sendSlack(
 
 	body, err := json.Marshal(payload)
 	if err != nil {
-		return fmt.Errorf(
-			"marshaling webhook payload: %w", err,
-		)
+		return fmt.Errorf("marshaling webhook payload: %w", err)
 	}
 
-	request := newRequest(
-		ctx, http.MethodPost, webhookURL,
+	request, err := http.NewRequestWithContext(
+		ctx,
+		http.MethodPost,
+		webhookURL.String(),
 		bytes.NewBuffer(body),
 	)
+	if err != nil {
+		return fmt.Errorf("creating webhook request: %w", err)
+	}
 
 	request.Header.Set("Content-Type", "application/json")
 
-	resp, err := svc.transport.RoundTrip(request)
+	resp, err := svc.client.Do(request) //nolint:gosec // URL validated at Service construction time
 	if err != nil {
 		return fmt.Errorf("sending webhook request: %w", err)
 	}

internal/notify/notify_test.go

@@ -1,100 +0,0 @@
-package notify_test
-
-import (
-	"testing"
-
-	"sneak.berlin/go/dnswatcher/internal/notify"
-)
-
-func TestValidateWebhookURLValid(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name    string
-		input   string
-		wantURL string
-	}{
-		{
-			name:    "valid https URL",
-			input:   "https://hooks.slack.com/T00/B00",
-			wantURL: "https://hooks.slack.com/T00/B00",
-		},
-		{
-			name:    "valid http URL",
-			input:   "http://localhost:8080/webhook",
-			wantURL: "http://localhost:8080/webhook",
-		},
-		{
-			name:    "https with query",
-			input:   "https://ntfy.sh/topic?auth=tok",
-			wantURL: "https://ntfy.sh/topic?auth=tok",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			got, err := notify.ValidateWebhookURL(tt.input)
-			if err != nil {
-				t.Fatalf("unexpected error: %v", err)
-			}
-
-			if got.String() != tt.wantURL {
-				t.Errorf(
-					"got %q, want %q",
-					got.String(), tt.wantURL,
-				)
-			}
-		})
-	}
-}
-
-func TestValidateWebhookURLInvalid(t *testing.T) {
-	t.Parallel()
-
-	invalid := []struct {
-		name  string
-		input string
-	}{
-		{"ftp scheme", "ftp://example.com/file"},
-		{"file scheme", "file:///etc/passwd"},
-		{"empty string", ""},
-		{"no scheme", "example.com/webhook"},
-		{"no host", "https:///path"},
-	}
-
-	for _, tt := range invalid {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			got, err := notify.ValidateWebhookURL(tt.input)
-			if err == nil {
-				t.Errorf(
-					"expected error for %q, got %v",
-					tt.input, got,
-				)
-			}
-		})
-	}
-}
-
-func TestIsAllowedScheme(t *testing.T) {
-	t.Parallel()
-
-	if !notify.IsAllowedScheme("https") {
-		t.Error("https should be allowed")
-	}
-
-	if !notify.IsAllowedScheme("http") {
-		t.Error("http should be allowed")
-	}
-
-	if notify.IsAllowedScheme("ftp") {
-		t.Error("ftp should not be allowed")
-	}
-
-	if notify.IsAllowedScheme("") {
-		t.Error("empty scheme should not be allowed")
-	}
-}