checkers: load external checker plugins from .so files

Scan -plugins-directory paths at startup, open each .so via plugin.Open,
look up the NewCheckerPlugin symbol from checker-sdk-go, and register the
returned definition and observation provider in the global checker
registries. A pluginLoader indirection keeps the door open for future
plugin kinds.

internal/app/app.go

@@ -93,6 +93,9 @@ func NewApp(cfg *happydns.Options) *App {
 	app.initStorageEngine()
 	app.initNewsletter()
 	app.initInsights()
+	if err := app.initPlugins(); err != nil {
+		log.Fatalf("Plugin initialization error: %s", err)
+	}
 	app.initUsecases()
 	app.initCaptcha()
 	app.setupRouter()
@@ -108,6 +111,9 @@ func NewAppWithStorage(cfg *happydns.Options, store storage.Storage) *App {
 
 	app.initMailer()
 	app.initNewsletter()
+	if err := app.initPlugins(); err != nil {
+		log.Fatalf("Plugin initialization error: %s", err)
+	}
 	app.initUsecases()
 	app.initCaptcha()
 	app.setupRouter()

internal/app/plugins.go

@@ -0,0 +1,187 @@
+// This file is part of the happyDomain (R) project.
+// Copyright (c) 2020-2026 happyDomain
+// Authors: Pierre-Olivier Mercier, et al.
+//
+// This program is offered under a commercial and under the AGPL license.
+// For commercial licensing, contact us at <contact@happydomain.org>.
+//
+// For AGPL licensing:
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+package app
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"plugin"
+
+	sdk "git.happydns.org/checker-sdk-go/checker"
+	"git.happydns.org/happyDomain/internal/checker"
+)
+
+// pluginSymbols is the minimal subset of *plugin.Plugin used by the loaders.
+// It exists so that loaders can be unit-tested with a fake instead of
+// requiring a real .so file built via `go build -buildmode=plugin`.
+type pluginSymbols interface {
+	Lookup(symName string) (plugin.Symbol, error)
+}
+
+// pluginLoader attempts to find and register one specific kind of plugin
+// symbol from an already-opened .so file.
+//
+// It returns (true, nil) when the symbol was found and registration
+// succeeded, (true, err) when the symbol was found but something went wrong,
+// and (false, nil) when the symbol simply isn't present in that file (which
+// is not considered an error — a single .so may implement only a subset of
+// the known plugin types).
+type pluginLoader func(p pluginSymbols, fname string) (found bool, err error)
+
+// safeCall invokes fn while recovering from any panic raised by plugin code.
+// A panicking factory must not take the whole server down at startup; the
+// recovered value is converted to an error so the caller can log/skip the
+// offending plugin like any other failure.
+func safeCall(symbol string, fname string, fn func() error) (err error) {
+	defer func() {
+		if r := recover(); r != nil {
+			err = fmt.Errorf("plugin %q panicked in %s: %v", fname, symbol, r)
+		}
+	}()
+	return fn()
+}
+
+// pluginLoaders is the authoritative list of plugin types that happyDomain
+// knows about. To support a new plugin type, add a single entry here.
+var pluginLoaders = []pluginLoader{
+	loadCheckerPlugin,
+}
+
+// loadCheckerPlugin handles the NewCheckerPlugin symbol exported by checkers
+// built against checker-sdk-go (see ../../checker-dummy/README.md).
+func loadCheckerPlugin(p pluginSymbols, fname string) (bool, error) {
+	sym, err := p.Lookup("NewCheckerPlugin")
+	if err != nil {
+		// Symbol not present in this .so — not an error.
+		return false, nil
+	}
+
+	factory, ok := sym.(func() (*sdk.CheckerDefinition, sdk.ObservationProvider, error))
+	if !ok {
+		return true, fmt.Errorf("symbol NewCheckerPlugin has unexpected type %T", sym)
+	}
+
+	def, provider, err := factory()
+	if err != nil {
+		return true, err
+	}
+	if def == nil {
+		return true, fmt.Errorf("NewCheckerPlugin returned a nil CheckerDefinition")
+	}
+	if provider == nil {
+		return true, fmt.Errorf("NewCheckerPlugin returned a nil ObservationProvider")
+	}
+
+	checker.RegisterObservationProvider(provider)
+	checker.RegisterExternalizableChecker(def)
+	log.Printf("Plugin %s (%s) loaded", def.ID, fname)
+	return true, nil
+}
+
+// checkPluginDirectoryPermissions refuses to load plugins from a directory
+// that any non-owner can write to. Loading a .so file is arbitrary code
+// execution as the happyDomain process, so a world- or group-writable
+// plugin directory is treated as a fatal misconfiguration: any local user
+// (or any process sharing the group) able to drop a file there could take
+// over the server. Operators who genuinely need shared deployment should
+// stage plugins elsewhere and rsync them into a directory owned and
+// writable only by the happyDomain user.
+func checkPluginDirectoryPermissions(directory string) error {
+	info, err := os.Stat(directory)
+	if err != nil {
+		return fmt.Errorf("unable to stat plugins directory %q: %s", directory, err)
+	}
+	if !info.IsDir() {
+		return fmt.Errorf("plugins path %q is not a directory", directory)
+	}
+	mode := info.Mode().Perm()
+	if mode&0o022 != 0 {
+		return fmt.Errorf("plugins directory %q is group- or world-writable (mode %#o); refusing to load plugins from it", directory, mode)
+	}
+	return nil
+}
+
+// initPlugins scans each directory listed in cfg.PluginsDirectories and loads
+// every .so file found as a Go plugin. A directory that cannot be read is a
+// fatal configuration error; individual plugin failures are logged and
+// skipped so that one bad .so does not prevent the others from loading.
+func (a *App) initPlugins() error {
+	for _, directory := range a.cfg.PluginsDirectories {
+		if err := checkPluginDirectoryPermissions(directory); err != nil {
+			return err
+		}
+
+		files, err := os.ReadDir(directory)
+		if err != nil {
+			return fmt.Errorf("unable to read plugins directory %q: %s", directory, err)
+		}
+
+		for _, file := range files {
+			if file.IsDir() {
+				continue
+			}
+
+			// Only attempt to load shared-object files.
+			if filepath.Ext(file.Name()) != ".so" {
+				continue
+			}
+
+			fname := filepath.Join(directory, file.Name())
+
+			if err := loadPlugin(fname); err != nil {
+				log.Printf("Unable to load plugin %q: %s", fname, err)
+			}
+		}
+	}
+
+	return nil
+}
+
+// loadPlugin opens the .so file at fname and runs every registered
+// pluginLoader against it. A loader that does not find its symbol is silently
+// skipped. If no loader recognises any symbol in the file a warning is
+// logged, because the file might be a valid plugin for a future version of
+// happyDomain. The first loader error encountered is returned immediately.
+func loadPlugin(fname string) error {
+	p, err := plugin.Open(fname)
+	if err != nil {
+		return err
+	}
+
+	anyFound := false
+	for _, loader := range pluginLoaders {
+		found, err := loader(p, fname)
+		if err != nil {
+			return err
+		}
+		if found {
+			anyFound = true
+		}
+	}
+
+	if !anyFound {
+		log.Printf("Warning: plugin %q exports no recognised symbols", fname)
+	}
+	return nil
+}

internal/app/plugins_test.go

@@ -0,0 +1,96 @@
+// This file is part of the happyDomain (R) project.
+// Copyright (c) 2020-2026 happyDomain
+// Authors: Pierre-Olivier Mercier, et al.
+//
+// This program is offered under a commercial and under the AGPL license.
+// For commercial licensing, contact us at <contact@happydomain.org>.
+//
+// For AGPL licensing:
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+package app
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"plugin"
+	"testing"
+)
+
+// fakeSymbols is a pluginSymbols implementation backed by a static map. It
+// lets the loader tests exercise their behaviour without having to compile a
+// real .so file via `go build -buildmode=plugin`.
+type fakeSymbols struct {
+	syms map[string]plugin.Symbol
+}
+
+func (f *fakeSymbols) Lookup(name string) (plugin.Symbol, error) {
+	if s, ok := f.syms[name]; ok {
+		return s, nil
+	}
+	return nil, fmt.Errorf("symbol %q not found", name)
+}
+
+// TestLoadPlugin_NoRecognisedSymbols verifies that when a .so file exports
+// none of the known plugin symbols, every loader returns (false, nil) — i.e.
+// the file is silently skipped rather than reported as an error. loadPlugin
+// itself logs a warning in that situation; we exercise the inner loop here
+// because the outer call requires plugin.Open and a real .so file.
+func TestLoadPlugin_NoRecognisedSymbols(t *testing.T) {
+	fs := &fakeSymbols{}
+	for _, loader := range pluginLoaders {
+		found, err := loader(fs, "empty.so")
+		if found || err != nil {
+			t.Fatalf("loader returned (%v, %v) for empty symbol set, expected (false, nil)", found, err)
+		}
+	}
+}
+
+func TestCheckPluginDirectoryPermissions(t *testing.T) {
+	dir := t.TempDir()
+
+	// A freshly-created TempDir is owner-only on every platform we run on,
+	// so this must be accepted.
+	if err := os.Chmod(dir, 0o750); err != nil {
+		t.Fatalf("chmod 0750: %v", err)
+	}
+	if err := checkPluginDirectoryPermissions(dir); err != nil {
+		t.Errorf("expected 0750 directory to be accepted, got %v", err)
+	}
+
+	// World-writable: must be refused.
+	if err := os.Chmod(dir, 0o777); err != nil {
+		t.Fatalf("chmod 0777: %v", err)
+	}
+	if err := checkPluginDirectoryPermissions(dir); err == nil {
+		t.Errorf("expected 0777 directory to be refused")
+	}
+
+	// Group-writable: must also be refused.
+	if err := os.Chmod(dir, 0o770); err != nil {
+		t.Fatalf("chmod 0770: %v", err)
+	}
+	if err := checkPluginDirectoryPermissions(dir); err == nil {
+		t.Errorf("expected 0770 directory to be refused")
+	}
+
+	// Restore permissions so t.TempDir cleanup can remove the directory.
+	_ = os.Chmod(dir, 0o700)
+
+	// Non-existent path: must be refused.
+	if err := checkPluginDirectoryPermissions(filepath.Join(dir, "does-not-exist")); err == nil {
+		t.Errorf("expected missing directory to be refused")
+	}
+}

internal/config/cli.go

@@ -62,6 +62,8 @@ func declareFlags(o *happydns.Options) {
 	flag.StringVar(&o.CaptchaProvider, "captcha-provider", o.CaptchaProvider, "Captcha provider to use for bot protection (altcha, hcaptcha, recaptchav2, turnstile, or empty to disable)")
 	flag.IntVar(&o.CaptchaLoginThreshold, "captcha-login-threshold", 3, "Number of failed login attempts before captcha is required (0 = always require when provider configured)")
 
+	flag.Var(&stringSlice{&o.PluginsDirectories}, "plugins-directory", "Path to a directory containing checker plugins (.so files); may be repeated")
+
 	// Others flags are declared in some other files likes sources, storages, ... when they need specials configurations
 }
 

internal/config/custom.go

@@ -25,8 +25,27 @@ import (
 	"encoding/base64"
 	"net/mail"
 	"net/url"
+	"strings"
 )
 
+// stringSlice is a flag.Value that accumulates string values across repeated
+// invocations of the same flag (e.g. -plugins-directory a -plugins-directory b).
+type stringSlice struct {
+	Values *[]string
+}
+
+func (s *stringSlice) String() string {
+	if s.Values == nil {
+		return ""
+	}
+	return strings.Join(*s.Values, ",")
+}
+
+func (s *stringSlice) Set(value string) error {
+	*s.Values = append(*s.Values, value)
+	return nil
+}
+
 type JWTSecretKey struct {
 	Secret *[]byte
 }

model/config.go

@@ -103,6 +103,10 @@ type Options struct {
 	// CaptchaLoginThreshold is the number of consecutive login failures before captcha is required.
 	// 0 means always require captcha at login (when provider is configured).
 	CaptchaLoginThreshold int
+
+	// PluginsDirectories lists filesystem paths scanned at startup for
+	// checker plugins (.so files).
+	PluginsDirectories []string
 }
 
 // GetBaseURL returns the full url to the absolute ExternalURL, including BaseURL.