feat(cups): add manual printer addition by IP/hostname (#1868)

Add a new "Add by Address" flow in the printer settings that allows
users to manually add printers by IP address or hostname, enabling
printing to devices not visible via mDNS/Avahi discovery (e.g.,
printers behind Tailscale subnet routers, VPNs, or across network
boundaries).

Go backend:
- New cups.testConnection IPC method that probes remote printers via
  IPP Get-Printer-Attributes with /ipp/print then / fallback
- Input validation with host sanitization and protocol allowlist
- Auth-aware probing (HTTP 401/403 reported as reachable)
- lpadmin CLI fallback for CreatePrinter/DeletePrinter when
  cups-pk-helper polkit authorization fails

QML frontend:
- "Add by Address" toggle alongside existing device discovery
- Manual entry form with host, port, protocol fields
- Test Connection button with loading state and result display
- Smart PPD auto-selection by probed makeModel with driverless fallback
- All strings use I18n.tr() with translator context

Includes 20+ unit tests covering validation, probe delegation, TLS
flag propagation, auth error detection, and handler routing.

core/internal/server/cups/actions.go

@@ -2,8 +2,10 @@ package cups
 
 import (
 	"errors"
+	"fmt"
 	"net"
 	"net/url"
+	"os/exec"
 	"strings"
 	"time"
 
@@ -275,13 +277,42 @@ func (m *Manager) GetClasses() ([]PrinterClass, error) {
 	return classes, nil
 }
 
+func createPrinterViaLpadmin(name, deviceURI, ppd, information, location string) error {
+	args := []string{"-p", name, "-E", "-v", deviceURI, "-m", ppd}
+	if information != "" {
+		args = append(args, "-D", information)
+	}
+	if location != "" {
+		args = append(args, "-L", location)
+	}
+	out, err := exec.Command("lpadmin", args...).CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("lpadmin failed: %s: %w", strings.TrimSpace(string(out)), err)
+	}
+	return nil
+}
+
+func deletePrinterViaLpadmin(name string) error {
+	out, err := exec.Command("lpadmin", "-x", name).CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("lpadmin failed: %s: %w", strings.TrimSpace(string(out)), err)
+	}
+	return nil
+}
+
 func (m *Manager) CreatePrinter(name, deviceURI, ppd string, shared bool, errorPolicy, information, location string) error {
 	usedPkHelper := false
 
 	err := m.client.CreatePrinter(name, deviceURI, ppd, shared, errorPolicy, information, location)
 	if isAuthError(err) && m.pkHelper != nil {
 		if err = m.pkHelper.PrinterAdd(name, deviceURI, ppd, information, location); err != nil {
-			return err
+			// pkHelper failed (e.g., no polkit agent), try lpadmin as last resort.
+			// lpadmin -E enables the printer, so no further setup needed.
+			if lpadminErr := createPrinterViaLpadmin(name, deviceURI, ppd, information, location); lpadminErr != nil {
+				return err
+			}
+			m.RefreshState()
+			return nil
 		}
 		usedPkHelper = true
 	} else if err != nil {
@@ -308,6 +339,12 @@ func (m *Manager) DeletePrinter(printerName string) error {
 	err := m.client.DeletePrinter(printerName)
 	if isAuthError(err) && m.pkHelper != nil {
 		err = m.pkHelper.PrinterDelete(printerName)
+		if err != nil {
+			// pkHelper failed, try lpadmin as last resort
+			if lpadminErr := deletePrinterViaLpadmin(printerName); lpadminErr == nil {
+				err = nil
+			}
+		}
 	}
 	if err == nil {
 		m.RefreshState()

core/internal/server/cups/handlers.go

@@ -70,6 +70,8 @@ func HandleRequest(conn net.Conn, req models.Request, manager *Manager) {
 		handleRestartJob(conn, req, manager)
 	case "cups.holdJob":
 		handleHoldJob(conn, req, manager)
+	case "cups.testConnection":
+		handleTestConnection(conn, req, manager)
 	default:
 		models.RespondError(conn, req.ID, fmt.Sprintf("unknown method: %s", req.Method))
 	}
@@ -464,3 +466,22 @@ func handleHoldJob(conn net.Conn, req models.Request, manager *Manager) {
 	}
 	models.Respond(conn, req.ID, models.SuccessResult{Success: true, Message: "job held"})
 }
+
+func handleTestConnection(conn net.Conn, req models.Request, manager *Manager) {
+	host, err := params.StringNonEmpty(req.Params, "host")
+	if err != nil {
+		models.RespondError(conn, req.ID, err.Error())
+		return
+	}
+
+	port := params.IntOpt(req.Params, "port", 631)
+	protocol := params.StringOpt(req.Params, "protocol", "ipp")
+
+	result, err := manager.TestRemotePrinter(host, port, protocol)
+	if err != nil {
+		models.RespondError(conn, req.ID, err.Error())
+		return
+	}
+
+	models.Respond(conn, req.ID, result)
+}

core/internal/server/cups/test_connection.go

@@ -0,0 +1,176 @@
+package cups
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"strings"
+	"time"
+
+	"github.com/AvengeMedia/DankMaterialShell/core/pkg/ipp"
+)
+
+var validProtocols = map[string]bool{
+	"ipp":    true,
+	"ipps":   true,
+	"lpd":    true,
+	"socket": true,
+}
+
+func validateTestConnectionParams(host string, port int, protocol string) error {
+	if host == "" {
+		return errors.New("host is required")
+	}
+	if strings.ContainsAny(host, " \t\n\r/\\") {
+		return errors.New("host contains invalid characters")
+	}
+	if port < 1 || port > 65535 {
+		return errors.New("port must be between 1 and 65535")
+	}
+	if protocol != "" && !validProtocols[protocol] {
+		return errors.New("protocol must be one of: ipp, ipps, lpd, socket")
+	}
+	return nil
+}
+
+const probeTimeout = 10 * time.Second
+
+func probeRemotePrinter(host string, port int, useTLS bool) (*RemotePrinterInfo, error) {
+	addr := net.JoinHostPort(host, fmt.Sprintf("%d", port))
+
+	// Fast fail: TCP reachability check
+	conn, err := net.DialTimeout("tcp", addr, probeTimeout)
+	if err != nil {
+		return &RemotePrinterInfo{
+			Reachable: false,
+			Error:     fmt.Sprintf("cannot reach %s: %s", addr, err.Error()),
+		}, nil
+	}
+	conn.Close()
+
+	// Create a temporary IPP client pointing at the remote host.
+	// The TCP dial above provides fast-fail for unreachable hosts.
+	// The IPP adapter's ResponseHeaderTimeout (90s) bounds stalling servers.
+	client := ipp.NewIPPClient(host, port, "", "", useTLS)
+
+	// Try /ipp/print first (modern driverless printers), then / (legacy)
+	info, err := probeIPPEndpoint(client, host, port, useTLS, "/ipp/print")
+	if err != nil {
+		// If we got an auth error, the printer exists but requires credentials.
+		// Report it as reachable with the URI that triggered the auth challenge.
+		if isAuthError(err) {
+			proto := "ipp"
+			if useTLS {
+				proto = "ipps"
+			}
+			return &RemotePrinterInfo{
+				Reachable: true,
+				URI:       fmt.Sprintf("%s://%s:%d/ipp/print", proto, host, port),
+				Info:      "authentication required",
+			}, nil
+		}
+		info, err = probeIPPEndpoint(client, host, port, useTLS, "/")
+	}
+	if err != nil {
+		if isAuthError(err) {
+			proto := "ipp"
+			if useTLS {
+				proto = "ipps"
+			}
+			return &RemotePrinterInfo{
+				Reachable: true,
+				URI:       fmt.Sprintf("%s://%s:%d/", proto, host, port),
+				Info:      "authentication required",
+			}, nil
+		}
+		// TCP reachable but not an IPP printer
+		return &RemotePrinterInfo{
+			Reachable: true,
+			Error:     fmt.Sprintf("host is reachable but does not appear to be an IPP printer: %s", err.Error()),
+		}, nil
+	}
+
+	return info, nil
+}
+
+func probeIPPEndpoint(client *ipp.IPPClient, host string, port int, useTLS bool, resourcePath string) (*RemotePrinterInfo, error) {
+	proto := "ipp"
+	if useTLS {
+		proto = "ipps"
+	}
+	printerURI := fmt.Sprintf("%s://%s:%d%s", proto, host, port, resourcePath)
+
+	httpProto := "http"
+	if useTLS {
+		httpProto = "https"
+	}
+	httpURL := fmt.Sprintf("%s://%s:%d%s", httpProto, host, port, resourcePath)
+
+	req := ipp.NewRequest(ipp.OperationGetPrinterAttributes, 1)
+	req.OperationAttributes[ipp.AttributePrinterURI] = printerURI
+	req.OperationAttributes[ipp.AttributeRequestedAttributes] = []string{
+		ipp.AttributePrinterName,
+		ipp.AttributePrinterMakeAndModel,
+		ipp.AttributePrinterState,
+		ipp.AttributePrinterInfo,
+		ipp.AttributePrinterUriSupported,
+	}
+
+	resp, err := client.SendRequest(httpURL, req, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	if len(resp.PrinterAttributes) == 0 {
+		return nil, errors.New("no printer attributes returned")
+	}
+
+	attrs := resp.PrinterAttributes[0]
+
+	return &RemotePrinterInfo{
+		Reachable: true,
+		MakeModel: getStringAttr(attrs, ipp.AttributePrinterMakeAndModel),
+		Name:      getStringAttr(attrs, ipp.AttributePrinterName),
+		Info:      getStringAttr(attrs, ipp.AttributePrinterInfo),
+		State:     parsePrinterState(attrs),
+		URI:       printerURI,
+	}, nil
+}
+
+// TestRemotePrinter validates inputs and probes a remote printer via IPP.
+// For lpd/socket protocols, only TCP reachability is tested.
+func (m *Manager) TestRemotePrinter(host string, port int, protocol string) (*RemotePrinterInfo, error) {
+	if protocol == "" {
+		protocol = "ipp"
+	}
+
+	if err := validateTestConnectionParams(host, port, protocol); err != nil {
+		return nil, err
+	}
+
+	// For non-IPP protocols, only check TCP reachability
+	if protocol == "lpd" || protocol == "socket" {
+		addr := net.JoinHostPort(host, fmt.Sprintf("%d", port))
+		conn, err := net.DialTimeout("tcp", addr, probeTimeout)
+		if err != nil {
+			return &RemotePrinterInfo{
+				Reachable: false,
+				Error:     fmt.Sprintf("cannot reach %s: %s", addr, err.Error()),
+			}, nil
+		}
+		conn.Close()
+		return &RemotePrinterInfo{
+			Reachable: true,
+			URI:       fmt.Sprintf("%s://%s:%d", protocol, host, port),
+		}, nil
+	}
+
+	useTLS := protocol == "ipps"
+
+	probeFn := m.probeRemoteFn
+	if probeFn == nil {
+		probeFn = probeRemotePrinter
+	}
+
+	return probeFn(host, port, useTLS)
+}

core/internal/server/cups/test_connection_test.go

@@ -0,0 +1,397 @@
+package cups
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"testing"
+
+	"github.com/AvengeMedia/DankMaterialShell/core/internal/server/models"
+	"github.com/AvengeMedia/DankMaterialShell/core/pkg/ipp"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestValidateTestConnectionParams(t *testing.T) {
+	tests := []struct {
+		name     string
+		host     string
+		port     int
+		protocol string
+		wantErr  string
+	}{
+		{
+			name:     "valid ipp",
+			host:     "192.168.0.5",
+			port:     631,
+			protocol: "ipp",
+			wantErr:  "",
+		},
+		{
+			name:     "valid ipps",
+			host:     "printer.local",
+			port:     443,
+			protocol: "ipps",
+			wantErr:  "",
+		},
+		{
+			name:     "valid lpd",
+			host:     "10.0.0.1",
+			port:     515,
+			protocol: "lpd",
+			wantErr:  "",
+		},
+		{
+			name:     "valid socket",
+			host:     "10.0.0.1",
+			port:     9100,
+			protocol: "socket",
+			wantErr:  "",
+		},
+		{
+			name:     "empty host",
+			host:     "",
+			port:     631,
+			protocol: "ipp",
+			wantErr:  "host is required",
+		},
+		{
+			name:     "port too low",
+			host:     "192.168.0.5",
+			port:     0,
+			protocol: "ipp",
+			wantErr:  "port must be between 1 and 65535",
+		},
+		{
+			name:     "port too high",
+			host:     "192.168.0.5",
+			port:     70000,
+			protocol: "ipp",
+			wantErr:  "port must be between 1 and 65535",
+		},
+		{
+			name:     "invalid protocol",
+			host:     "192.168.0.5",
+			port:     631,
+			protocol: "ftp",
+			wantErr:  "protocol must be one of: ipp, ipps, lpd, socket",
+		},
+		{
+			name:     "empty protocol treated as ipp",
+			host:     "192.168.0.5",
+			port:     631,
+			protocol: "",
+			wantErr:  "",
+		},
+		{
+			name:     "host with slash",
+			host:     "192.168.0.5/admin",
+			port:     631,
+			protocol: "ipp",
+			wantErr:  "host contains invalid characters",
+		},
+		{
+			name:     "host with space",
+			host:     "192.168.0.5 ",
+			port:     631,
+			protocol: "ipp",
+			wantErr:  "host contains invalid characters",
+		},
+		{
+			name:     "host with newline",
+			host:     "192.168.0.5\n",
+			port:     631,
+			protocol: "ipp",
+			wantErr:  "host contains invalid characters",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := validateTestConnectionParams(tt.host, tt.port, tt.protocol)
+			if tt.wantErr == "" {
+				assert.NoError(t, err)
+			} else {
+				assert.EqualError(t, err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestManager_TestRemotePrinter_Validation(t *testing.T) {
+	m := NewTestManager(nil, nil)
+
+	tests := []struct {
+		name     string
+		host     string
+		port     int
+		protocol string
+		wantErr  string
+	}{
+		{
+			name:     "empty host returns error",
+			host:     "",
+			port:     631,
+			protocol: "ipp",
+			wantErr:  "host is required",
+		},
+		{
+			name:     "invalid port returns error",
+			host:     "192.168.0.5",
+			port:     0,
+			protocol: "ipp",
+			wantErr:  "port must be between 1 and 65535",
+		},
+		{
+			name:     "invalid protocol returns error",
+			host:     "192.168.0.5",
+			port:     631,
+			protocol: "ftp",
+			wantErr:  "protocol must be one of: ipp, ipps, lpd, socket",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := m.TestRemotePrinter(tt.host, tt.port, tt.protocol)
+			assert.EqualError(t, err, tt.wantErr)
+		})
+	}
+}
+
+func TestManager_TestRemotePrinter_IPP(t *testing.T) {
+	tests := []struct {
+		name      string
+		protocol  string
+		probeRet  *RemotePrinterInfo
+		probeErr  error
+		wantTLS   bool
+		wantReach bool
+		wantModel string
+	}{
+		{
+			name:     "successful ipp probe",
+			protocol: "ipp",
+			probeRet: &RemotePrinterInfo{
+				Reachable: true,
+				MakeModel: "HP OfficeJet 8010",
+				Name:      "OfficeJet",
+				State:     "idle",
+				URI:       "ipp://192.168.0.5:631/ipp/print",
+			},
+			wantTLS:   false,
+			wantReach: true,
+			wantModel: "HP OfficeJet 8010",
+		},
+		{
+			name:     "successful ipps probe",
+			protocol: "ipps",
+			probeRet: &RemotePrinterInfo{
+				Reachable: true,
+				MakeModel: "HP OfficeJet 8010",
+				URI:       "ipps://192.168.0.5:631/ipp/print",
+			},
+			wantTLS:   true,
+			wantReach: true,
+			wantModel: "HP OfficeJet 8010",
+		},
+		{
+			name:     "unreachable host",
+			protocol: "ipp",
+			probeRet: &RemotePrinterInfo{
+				Reachable: false,
+				Error:     "cannot reach 192.168.0.5:631: connection refused",
+			},
+			wantReach: false,
+		},
+		{
+			name:     "empty protocol defaults to ipp",
+			protocol: "",
+			probeRet: &RemotePrinterInfo{
+				Reachable: true,
+				MakeModel: "Test Printer",
+			},
+			wantTLS:   false,
+			wantReach: true,
+			wantModel: "Test Printer",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var capturedTLS bool
+			m := NewTestManager(nil, nil)
+			m.probeRemoteFn = func(host string, port int, useTLS bool) (*RemotePrinterInfo, error) {
+				capturedTLS = useTLS
+				return tt.probeRet, tt.probeErr
+			}
+
+			result, err := m.TestRemotePrinter("192.168.0.5", 631, tt.protocol)
+			if tt.probeErr != nil {
+				assert.Error(t, err)
+				return
+			}
+			assert.NoError(t, err)
+			assert.Equal(t, tt.wantReach, result.Reachable)
+			assert.Equal(t, tt.wantModel, result.MakeModel)
+			assert.Equal(t, tt.wantTLS, capturedTLS)
+		})
+	}
+}
+
+func TestManager_TestRemotePrinter_AuthRequired(t *testing.T) {
+	m := NewTestManager(nil, nil)
+	m.probeRemoteFn = func(host string, port int, useTLS bool) (*RemotePrinterInfo, error) {
+		// Simulate what happens when the printer returns HTTP 401
+		return probeRemotePrinterWithAuthError(host, port, useTLS)
+	}
+
+	result, err := m.TestRemotePrinter("192.168.0.107", 631, "ipp")
+	assert.NoError(t, err)
+	assert.True(t, result.Reachable)
+	assert.Equal(t, "authentication required", result.Info)
+	assert.Contains(t, result.URI, "ipp://192.168.0.107:631")
+}
+
+// probeRemotePrinterWithAuthError simulates a probe where the printer
+// returns HTTP 401 on both endpoints.
+func probeRemotePrinterWithAuthError(host string, port int, useTLS bool) (*RemotePrinterInfo, error) {
+	// This simulates what probeRemotePrinter does when both endpoints
+	// return auth errors. We test the auth detection logic directly.
+	err := ipp.HTTPError{Code: 401}
+	if isAuthError(err) {
+		proto := "ipp"
+		if useTLS {
+			proto = "ipps"
+		}
+		return &RemotePrinterInfo{
+			Reachable: true,
+			URI:       fmt.Sprintf("%s://%s:%d/ipp/print", proto, host, port),
+			Info:      "authentication required",
+		}, nil
+	}
+	return nil, err
+}
+
+func TestManager_TestRemotePrinter_NonIPPProtocol(t *testing.T) {
+	m := NewTestManager(nil, nil)
+	probeCalled := false
+	m.probeRemoteFn = func(host string, port int, useTLS bool) (*RemotePrinterInfo, error) {
+		probeCalled = true
+		return nil, nil
+	}
+
+	// These will fail at TCP dial (no real server), but the important
+	// thing is that probeRemoteFn is NOT called for lpd/socket.
+	m.TestRemotePrinter("192.168.0.5", 9100, "socket")
+	assert.False(t, probeCalled, "probe function should not be called for socket protocol")
+
+	m.TestRemotePrinter("192.168.0.5", 515, "lpd")
+	assert.False(t, probeCalled, "probe function should not be called for lpd protocol")
+}
+
+func TestHandleTestConnection_Success(t *testing.T) {
+	m := NewTestManager(nil, nil)
+	m.probeRemoteFn = func(host string, port int, useTLS bool) (*RemotePrinterInfo, error) {
+		return &RemotePrinterInfo{
+			Reachable: true,
+			MakeModel: "HP OfficeJet 8010",
+			Name:      "OfficeJet",
+			State:     "idle",
+			URI:       "ipp://192.168.0.5:631/ipp/print",
+		}, nil
+	}
+
+	buf := &bytes.Buffer{}
+	conn := &mockConn{Buffer: buf}
+
+	req := models.Request{
+		ID:     1,
+		Method: "cups.testConnection",
+		Params: map[string]any{
+			"host": "192.168.0.5",
+		},
+	}
+
+	handleTestConnection(conn, req, m)
+
+	var resp models.Response[RemotePrinterInfo]
+	err := json.NewDecoder(buf).Decode(&resp)
+	assert.NoError(t, err)
+	assert.NotNil(t, resp.Result)
+	assert.True(t, resp.Result.Reachable)
+	assert.Equal(t, "HP OfficeJet 8010", resp.Result.MakeModel)
+}
+
+func TestHandleTestConnection_MissingHost(t *testing.T) {
+	m := NewTestManager(nil, nil)
+	buf := &bytes.Buffer{}
+	conn := &mockConn{Buffer: buf}
+
+	req := models.Request{
+		ID:     1,
+		Method: "cups.testConnection",
+		Params: map[string]any{},
+	}
+
+	handleTestConnection(conn, req, m)
+
+	var resp models.Response[any]
+	err := json.NewDecoder(buf).Decode(&resp)
+	assert.NoError(t, err)
+	assert.Nil(t, resp.Result)
+	assert.NotNil(t, resp.Error)
+}
+
+func TestHandleTestConnection_CustomPortAndProtocol(t *testing.T) {
+	m := NewTestManager(nil, nil)
+	m.probeRemoteFn = func(host string, port int, useTLS bool) (*RemotePrinterInfo, error) {
+		assert.Equal(t, 9631, port)
+		assert.True(t, useTLS)
+		return &RemotePrinterInfo{Reachable: true, URI: "ipps://192.168.0.5:9631/ipp/print"}, nil
+	}
+
+	buf := &bytes.Buffer{}
+	conn := &mockConn{Buffer: buf}
+
+	req := models.Request{
+		ID:     1,
+		Method: "cups.testConnection",
+		Params: map[string]any{
+			"host":     "192.168.0.5",
+			"port":     float64(9631),
+			"protocol": "ipps",
+		},
+	}
+
+	handleTestConnection(conn, req, m)
+
+	var resp models.Response[RemotePrinterInfo]
+	err := json.NewDecoder(buf).Decode(&resp)
+	assert.NoError(t, err)
+	assert.NotNil(t, resp.Result)
+	assert.True(t, resp.Result.Reachable)
+}
+
+func TestHandleRequest_TestConnection(t *testing.T) {
+	m := NewTestManager(nil, nil)
+	m.probeRemoteFn = func(host string, port int, useTLS bool) (*RemotePrinterInfo, error) {
+		return &RemotePrinterInfo{Reachable: true}, nil
+	}
+
+	buf := &bytes.Buffer{}
+	conn := &mockConn{Buffer: buf}
+
+	req := models.Request{
+		ID:     1,
+		Method: "cups.testConnection",
+		Params: map[string]any{"host": "192.168.0.5"},
+	}
+
+	HandleRequest(conn, req, m)
+
+	var resp models.Response[RemotePrinterInfo]
+	err := json.NewDecoder(buf).Decode(&resp)
+	assert.NoError(t, err)
+	assert.NotNil(t, resp.Result)
+	assert.True(t, resp.Result.Reachable)
+}

core/internal/server/cups/types.go

@@ -55,6 +55,16 @@ type PPD struct {
 	Type            string `json:"type"`
 }
 
+type RemotePrinterInfo struct {
+	Reachable bool   `json:"reachable"`
+	MakeModel string `json:"makeModel"`
+	Name      string `json:"name"`
+	Info      string `json:"info"`
+	State     string `json:"state"`
+	URI       string `json:"uri"`
+	Error     string `json:"error,omitempty"`
+}
+
 type PrinterClass struct {
 	Name     string   `json:"name"`
 	URI      string   `json:"uri"`
@@ -77,6 +87,7 @@ type Manager struct {
 	notifierWg        sync.WaitGroup
 	lastNotifiedState *CUPSState
 	baseURL           string
+	probeRemoteFn     func(host string, port int, useTLS bool) (*RemotePrinterInfo, error)
 }
 
 type SubscriptionManagerInterface interface {