Merge pull request #219 from unpoller/feat/authorize-guest

feat: add AuthorizeGuest helper for cmd/stamgr

Author: platinummonkey

mocks/mock_client.go

@@ -1228,3 +1228,8 @@ func (m *MockUnifi) GetSSLCertificate(_ *unifi.Site) (*unifi.SSLCertificate, err
 
 	return &a, nil
 }
+
+// AuthorizeGuest authorizes a guest client by MAC on a site.
+func (m *MockUnifi) AuthorizeGuest(_ *unifi.Site, _ string, _ int) error {
+	return nil
+}

stamgr.go

@@ -0,0 +1,53 @@
+package unifi
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+// ErrInvalidMinutes is returned when AuthorizeGuest is called with a negative duration.
+var ErrInvalidMinutes = fmt.Errorf("minutes must be >= 0")
+
+// ErrEmptyMAC is returned when AuthorizeGuest is called with an empty MAC.
+var ErrEmptyMAC = fmt.Errorf("mac must not be empty")
+
+// AuthorizeGuest authorizes a guest client (identified by MAC address) on the
+// given site via the stamgr command endpoint. minutes sets the authorization
+// duration; pass 0 to use the controller's default. This wraps a POST to
+// /api/s/{site}/cmd/stamgr with cmd=authorize-guest.
+func (u *Unifi) AuthorizeGuest(site *Site, mac string, minutes int) error {
+	if site == nil || site.Name == "" {
+		return ErrNoSiteProvided
+	}
+
+	if mac == "" {
+		return ErrEmptyMAC
+	}
+
+	if minutes < 0 {
+		return ErrInvalidMinutes
+	}
+
+	payload := struct {
+		Cmd     string `json:"cmd"`
+		MAC     string `json:"mac"`
+		Minutes int    `json:"minutes,omitempty"`
+	}{
+		Cmd:     "authorize-guest",
+		MAC:     mac,
+		Minutes: minutes,
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshalling authorize-guest payload: %w", err)
+	}
+
+	path := fmt.Sprintf(APIStaMgrPath, site.Name)
+
+	if _, err := u.PostJSON(path, string(body)); err != nil {
+		return fmt.Errorf("authorize-guest %s: %w", mac, err)
+	}
+
+	return nil
+}

stamgr_test.go

@@ -0,0 +1,136 @@
+package unifi // nolint: testpackage
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAuthorizeGuest(t *testing.T) {
+	t.Parallel()
+
+	type stamgrBody struct {
+		Cmd     string `json:"cmd"`
+		MAC     string `json:"mac"`
+		Minutes int    `json:"minutes,omitempty"`
+	}
+
+	var got stamgrBody
+
+	var gotPath, gotMethod string
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		gotMethod = r.Method
+
+		body, err := io.ReadAll(r.Body)
+		if err != nil {
+			w.WriteHeader(http.StatusInternalServerError)
+
+			return
+		}
+
+		if err := json.Unmarshal(body, &got); err != nil {
+			w.WriteHeader(http.StatusBadRequest)
+
+			return
+		}
+
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"data":[],"meta":{"rc":"ok"}}`))
+	}))
+	defer srv.Close()
+
+	u := &Unifi{
+		Client: &http.Client{},
+		Config: &Config{URL: srv.URL, DebugLog: discardLogs, ErrorLog: discardLogs},
+	}
+	site := &Site{Name: "default"}
+
+	err := u.AuthorizeGuest(site, "aa:bb:cc:dd:ee:ff", 60)
+	require.NoError(t, err)
+
+	a := assert.New(t)
+	a.Equal("/api/s/default/cmd/stamgr", gotPath)
+	a.Equal(http.MethodPost, gotMethod)
+	a.Equal("authorize-guest", got.Cmd)
+	a.Equal("aa:bb:cc:dd:ee:ff", got.MAC)
+	a.Equal(60, got.Minutes)
+}
+
+func TestAuthorizeGuestZeroMinutesOmitted(t *testing.T) {
+	t.Parallel()
+
+	var raw map[string]any
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, err := io.ReadAll(r.Body)
+		if err != nil {
+			w.WriteHeader(http.StatusInternalServerError)
+
+			return
+		}
+
+		if err := json.Unmarshal(body, &raw); err != nil {
+			w.WriteHeader(http.StatusBadRequest)
+
+			return
+		}
+
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"data":[],"meta":{"rc":"ok"}}`))
+	}))
+	defer srv.Close()
+
+	u := &Unifi{
+		Client: &http.Client{},
+		Config: &Config{URL: srv.URL, DebugLog: discardLogs, ErrorLog: discardLogs},
+	}
+
+	err := u.AuthorizeGuest(&Site{Name: "default"}, "aa:bb:cc:dd:ee:ff", 0)
+	require.NoError(t, err)
+
+	a := assert.New(t)
+	_, hasMinutes := raw["minutes"]
+	a.False(hasMinutes, "minutes should be omitted when 0")
+}
+
+func TestAuthorizeGuestValidation(t *testing.T) {
+	t.Parallel()
+
+	u := &Unifi{Client: &http.Client{}, Config: &Config{URL: "http://invalid", DebugLog: discardLogs, ErrorLog: discardLogs}}
+
+	a := assert.New(t)
+	a.ErrorIs(u.AuthorizeGuest(nil, "aa:bb:cc:dd:ee:ff", 0), ErrNoSiteProvided)
+	a.ErrorIs(u.AuthorizeGuest(&Site{Name: ""}, "aa:bb:cc:dd:ee:ff", 0), ErrNoSiteProvided)
+	a.ErrorIs(u.AuthorizeGuest(&Site{Name: "default"}, "", 0), ErrEmptyMAC)
+	a.ErrorIs(u.AuthorizeGuest(&Site{Name: "default"}, "aa:bb:cc:dd:ee:ff", -1), ErrInvalidMinutes)
+}
+
+func TestAuthorizeGuestControllerError(t *testing.T) {
+	t.Parallel()
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+		_, _ = w.Write([]byte(`{"data":[],"meta":{"rc":"error","msg":"api.err.LoginRequired"}}`))
+	}))
+	defer srv.Close()
+
+	u := &Unifi{
+		Client: &http.Client{},
+		Config: &Config{URL: srv.URL, DebugLog: discardLogs, ErrorLog: discardLogs},
+	}
+
+	err := u.AuthorizeGuest(&Site{Name: "default"}, "aa:bb:cc:dd:ee:ff", 0)
+
+	a := assert.New(t)
+	a.Error(err)
+	a.True(errors.Is(err, ErrInvalidStatusCode), "error should unwrap to ErrInvalidStatusCode")
+	a.Contains(err.Error(), "aa:bb:cc:dd:ee:ff", "error should include MAC for context")
+}

types.go

@@ -163,6 +163,7 @@ const (
 	APISystemLogPath          string = "/v2/api/site/%s/system-log/all"
 	APICommandPath            string = "/api/s/%s/cmd"
 	APIDevMgrPath             string = APICommandPath + "/devmgr"
+	APIStaMgrPath             string = APICommandPath + "/stamgr"
 	APIClientTrafficPath      string = "/v2/api/site/%s/traffic?start=%d&end=%d&includeUnidentified=%t"
 	APIClientTrafficByMacPath string = "/v2/api/site/%s/traffic/%s?start=%d&end=%d&includeUnidentified=%t&mac=%s"
 	APICountryTrafficPath     string = "/v2/api/site/%s/country-traffic?start=%d&end=%d"
@@ -721,6 +722,9 @@ type UnifiClient interface { //nolint: revive
 	GetPortForwards(site *Site) ([]*PortForward, error)
 	// GetSSLCertificate returns SSL certificate information for a site.
 	GetSSLCertificate(site *Site) (*SSLCertificate, error)
+	// AuthorizeGuest authorizes a guest client by MAC on a site for the given
+	// number of minutes. Pass minutes=0 to use the controller default.
+	AuthorizeGuest(site *Site, mac string, minutes int) error
 }
 
 // Unifi is what you get in return for providing a password! Unifi represents