TerdutTeam: mint and surface a real invite link (spec.invite)

The actual fix for the human-onboarding gap niklas/terdut-server#23 found --
not a terdut-server change at all. A team-scoped credential is already
owner-equivalent for POST/GET/DELETE /api/teams/{teamID}/invites
(requireTeamOwner's synthetic-membership mechanism, ratified not
accidental per that repo's SERVICE-ACCOUNTS.md), and invite redemption
bypasses signup_mode entirely -- this TerdutTeam controller just never
grew a feature to use either fact.

New spec.invite{enabled, role (member|owner, default member), maxUses
(1-100, default 1)} and status.inviteSecretRef. The Secret lives in the
TerdutTeam's OWN namespace, not the operator's: unlike
status.credentialsSecretRef (a durable, high-privilege credential, kept
operator-side per DESIGN.md §6), an invite is bounded and limited-use,
meant for this namespace's own human operators to read and hand out --
same precedent as TerdutAlertSource's status.webhookURLSecretRef, same-
namespace and OwnerReference'd so deleting the TerdutTeam garbage-collects
it automatically.

internal/controller/terdutteam_invite.go: mints on first spec.invite.enabled,
refreshes a day ahead of terdut-server's fixed 7-day TTL (reading the
Secret's own stored expiresAt, no extra server round-trip per reconcile),
revokes server-side and deletes the Secret when flipped back to false. A
lost invite Secret is silently re-minted rather than treated as
unrecoverable the way TerdutAlertSource's webhook key is -- nothing
external holds a durable dependency on one specific invite link staying
stable, it's read once by one human and handed out.

New tdclient.Invite/CreateInvite/RevokeInvite. New envtest coverage: mint
into the team's own namespace, refresh-before-expiry, revoke-on-disable
(internal/controller/terdutteam_controller_test.go's new "spec.invite"
Describe block), plus the fake server growing invite support
(terdutserver_controller_test.go) -- its handleTeamSubPath dispatcher was
split further (deadman switches into their own handleDeadmanSubPath,
matching the existing handleIntegrationSubPath precedent) to stay under
golangci-lint's gocyclo threshold with the new route added.

examples/demo updated to prove this end to end: 02-team-platform.yaml
turns on spec.invite; run-demo.sh's bootstrap_login/join_demo_teams (the
psql signup_mode flip + a direct team_members INSERT) are replaced by
redeem_platform_invite (reads status.inviteSecretRef, a real POST
/api/signup with the invite token) and join_payments_team (POST
/api/teams/{teamID}/members using Payments' own credential and alice's
user id resolved via GET /api/users, deliberately not given its own
spec.invite, so the demo shows both onboarding paths this feature
unlocks) -- zero kubectl exec/psql calls remain anywhere in the script.
README.md's "First login" section rewritten to match; it no longer
documents the admin-token curl call that 403s against current
terdut-server (niklas/terdut-server#23).

Depends on niklas/terdut-server#24 (the callerMayManageServiceAccount fix
for terdut-operator#3) being released before this is deployed for real --
not required to build or test this change itself, since the envtest fake
never modeled that authorization gap to begin with.

internal/controller/terdutserver_controller_test.go

@@ -9,6 +9,7 @@ import (
 	"strconv"
 	"strings"
 	"sync"
+	"time"
 
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -35,6 +36,11 @@ import (
 const (
 	fakeVersionString = "test"
 	errJSONKey        = "error"
+	// deadmanSwitchesPath is the literal path (not Printf'd like the others
+	// below) shared by the exact-match collection route and the dispatcher
+	// that routes into it -- goconst flags three occurrences of the same
+	// string, so this is that string, once.
+	deadmanSwitchesPath = "/deadman/switches"
 )
 
 // fakeTerdutServer reproduces the exact stateful semantics of
@@ -83,6 +89,14 @@ type fakeTerdutServer struct {
 	nextIntegrationID int64
 	integrations      map[int64]map[int64]tdclient.Integration // teamID -> integrationID -> integration
 	integrationDelete map[int64]bool                           // integrationID -> true once DELETEd, for 404-on-redelete
+
+	// invites/nextInviteID/inviteDelete back TerdutTeam's own invite-minting
+	// feature -- no unique constraint on an invite server-side either (every
+	// POST mints a brand new row, confirmed against source), same keyed-by-id
+	// shape as switches/integrations.
+	nextInviteID int64
+	invites      map[int64]map[int64]tdclient.Invite // teamID -> inviteID -> invite
+	inviteDelete map[int64]bool                      // inviteID -> true once DELETEd, for 404-on-redelete
 }
 
 func newFakeTerdutServer() (*fakeTerdutServer, *httptest.Server) {
@@ -100,6 +114,9 @@ func newFakeTerdutServer() (*fakeTerdutServer, *httptest.Server) {
 
 		integrations:      map[int64]map[int64]tdclient.Integration{},
 		integrationDelete: map[int64]bool{},
+
+		invites:      map[int64]map[int64]tdclient.Invite{},
+		inviteDelete: map[int64]bool{},
 	}
 	return f, httptest.NewServer(f)
 }
@@ -265,7 +282,26 @@ func (f *fakeTerdutServer) handleTeamSubPath(w http.ResponseWriter, r *http.Requ
 		f.escalation[id] = req
 		w.WriteHeader(http.StatusNoContent)
 
-	case rest == "/deadman/switches" && r.Method == http.MethodGet:
+	case rest == deadmanSwitchesPath || strings.HasPrefix(rest, deadmanSwitchesPath+"/"):
+		f.handleDeadmanSubPath(w, r, id, rest)
+
+	case rest == "/integrations" || strings.HasPrefix(rest, "/integrations/"):
+		f.handleIntegrationSubPath(w, r, id, rest)
+
+	case rest == "/invites" || strings.HasPrefix(rest, "/invites/"):
+		f.handleInviteSubPath(w, r, id, rest)
+
+	default:
+		w.WriteHeader(http.StatusNotFound)
+	}
+}
+
+// handleDeadmanSubPath answers GET/POST /api/teams/{id}/deadman/switches and
+// PUT/DELETE .../deadman/switches/{switchID} -- split out of
+// handleTeamSubPath for the same gocyclo reason as handleIntegrationSubPath.
+func (f *fakeTerdutServer) handleDeadmanSubPath(w http.ResponseWriter, r *http.Request, id int64, rest string) {
+	switch {
+	case rest == deadmanSwitchesPath && r.Method == http.MethodGet:
 		existing := f.switches[id]
 		out := make([]tdclient.DeadmanSwitch, 0, len(existing))
 		for _, s := range existing {
@@ -273,7 +309,7 @@ func (f *fakeTerdutServer) handleTeamSubPath(w http.ResponseWriter, r *http.Requ
 		}
 		writeJSON(w, http.StatusOK, out)
 
-	case rest == "/deadman/switches" && r.Method == http.MethodPost:
+	case rest == deadmanSwitchesPath && r.Method == http.MethodPost:
 		var req deadmanSwitchFakeRequest
 		_ = json.NewDecoder(r.Body).Decode(&req)
 		f.nextSwitchID++
@@ -328,8 +364,48 @@ func (f *fakeTerdutServer) handleTeamSubPath(w http.ResponseWriter, r *http.Requ
 		f.switchDelete[switchID] = true
 		w.WriteHeader(http.StatusNoContent)
 
-	case rest == "/integrations" || strings.HasPrefix(rest, "/integrations/"):
-		f.handleIntegrationSubPath(w, r, id, rest)
+	default:
+		w.WriteHeader(http.StatusNotFound)
+	}
+}
+
+// handleInviteSubPath answers POST /api/teams/{id}/invites and
+// DELETE .../invites/{inviteID} -- split out for the same gocyclo reason as
+// handleIntegrationSubPath.
+func (f *fakeTerdutServer) handleInviteSubPath(w http.ResponseWriter, r *http.Request, id int64, rest string) {
+	switch {
+	case rest == "/invites" && r.Method == http.MethodPost:
+		var req struct {
+			Role    string `json:"role"`
+			MaxUses int64  `json:"max_uses"`
+		}
+		_ = json.NewDecoder(r.Body).Decode(&req)
+		f.nextInviteID++
+		inviteID := f.nextInviteID
+		inv := tdclient.Invite{
+			ID: inviteID, TeamID: id, Role: req.Role, MaxUses: req.MaxUses,
+			ExpiresAt: time.Now().Add(7 * 24 * time.Hour),
+			URL:       fmt.Sprintf("https://terdut.example.invalid/signup?invite=invite-token-%d", inviteID),
+		}
+		if f.invites[id] == nil {
+			f.invites[id] = map[int64]tdclient.Invite{}
+		}
+		f.invites[id][inviteID] = inv
+		writeJSON(w, http.StatusCreated, inv)
+
+	case strings.HasPrefix(rest, "/invites/") && r.Method == http.MethodDelete:
+		inviteID, ok := parseTrailingID(rest, "/invites/")
+		if !ok {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		if _, exists := f.invites[id][inviteID]; !exists {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		delete(f.invites[id], inviteID)
+		f.inviteDelete[inviteID] = true
+		w.WriteHeader(http.StatusNoContent)
 
 	default:
 		w.WriteHeader(http.StatusNotFound)

internal/controller/terdutteam_controller.go

@@ -131,6 +131,9 @@ func (r *TerdutTeamReconciler) Reconcile(ctx context.Context, req ctrl.Request)
 	if err := teamClient.SetTeamOIDCGroups(ctx, team.Status.TeamID, team.Spec.OIDC.MemberGroup, team.Spec.OIDC.OwnerGroup); err != nil {
 		return ctrl.Result{}, fmt.Errorf("PUT /api/teams/%d/oidc-groups: %w", team.Status.TeamID, err)
 	}
+	if err := r.reconcileInvite(ctx, &team, teamClient); err != nil {
+		return ctrl.Result{}, err
+	}
 
 	meta.SetStatusCondition(&team.Status.Conditions, metav1.Condition{
 		Type:    terdutv1alpha1.ConditionReady,

internal/controller/terdutteam_controller_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"net/http/httptest"
+	"time"
 
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -251,6 +252,88 @@ var _ = Describe("TerdutTeam Controller", func() {
 		})
 	})
 
+	Describe("spec.invite", func() {
+		It("mints a link into the TerdutTeam's own namespace, not the operator's", func(ctx SpecContext) {
+			createTeam(ctx, "platform", sameNSRef())
+			reconcileOnce(ctx) // finalizer
+			reconcileOnce(ctx) // create+mint+apply
+
+			team := &terdutv1alpha1.TerdutTeam{}
+			Expect(k8sClient.Get(ctx, teamKey, team)).To(Succeed())
+			team.Spec.Invite.Enabled = true
+			Expect(k8sClient.Update(ctx, team)).To(Succeed())
+			reconcileOnce(ctx)
+
+			Expect(k8sClient.Get(ctx, teamKey, team)).To(Succeed())
+			Expect(team.Status.InviteSecretRef).NotTo(BeNil())
+
+			var secret corev1.Secret
+			Expect(k8sClient.Get(ctx, types.NamespacedName{
+				Name: team.Status.InviteSecretRef.Name, Namespace: team.Namespace,
+			}, &secret)).To(Succeed())
+			Expect(string(secret.Data[inviteSecretURLKey])).To(ContainSubstring("invite="))
+			Expect(string(secret.Data[inviteSecretInviteIDKey])).To(Equal("1"))
+
+			inv := fake.invites[team.Status.TeamID][1]
+			Expect(inv.Role).To(Equal("member"), "default role")
+			Expect(inv.MaxUses).To(Equal(int64(1)), "default max uses")
+		})
+
+		It("refreshes a link that's within a day of terdut-server's 7-day TTL", func(ctx SpecContext) {
+			createTeam(ctx, "platform", sameNSRef())
+			reconcileOnce(ctx)
+			reconcileOnce(ctx)
+
+			team := &terdutv1alpha1.TerdutTeam{}
+			Expect(k8sClient.Get(ctx, teamKey, team)).To(Succeed())
+			team.Spec.Invite.Enabled = true
+			Expect(k8sClient.Update(ctx, team)).To(Succeed())
+			reconcileOnce(ctx)
+
+			Expect(k8sClient.Get(ctx, teamKey, team)).To(Succeed())
+			firstSecretName := team.Status.InviteSecretRef.Name
+			var secret corev1.Secret
+			Expect(k8sClient.Get(ctx, types.NamespacedName{Name: firstSecretName, Namespace: team.Namespace}, &secret)).To(Succeed())
+
+			// Simulate the stored link being within the refresh window of
+			// expiry, the way it genuinely would be six days from now,
+			// without the test waiting six days.
+			secret.Data[inviteSecretExpiresAtKey] = []byte(time.Now().Add(12 * time.Hour).Format(time.RFC3339)) // inside inviteRefreshWindow
+			Expect(k8sClient.Update(ctx, &secret)).To(Succeed())
+
+			reconcileOnce(ctx)
+
+			Expect(fake.inviteDelete[1]).To(BeTrue(), "the stale invite should have been revoked")
+			Expect(fake.invites[team.Status.TeamID]).To(HaveKey(int64(2)), "a replacement should have been minted")
+		})
+
+		It("revokes the invite when spec.invite.enabled flips back to false", func(ctx SpecContext) {
+			createTeam(ctx, "platform", sameNSRef())
+			reconcileOnce(ctx)
+			reconcileOnce(ctx)
+
+			team := &terdutv1alpha1.TerdutTeam{}
+			Expect(k8sClient.Get(ctx, teamKey, team)).To(Succeed())
+			team.Spec.Invite.Enabled = true
+			Expect(k8sClient.Update(ctx, team)).To(Succeed())
+			reconcileOnce(ctx)
+
+			Expect(k8sClient.Get(ctx, teamKey, team)).To(Succeed())
+			secretName := team.Status.InviteSecretRef.Name
+			team.Spec.Invite.Enabled = false
+			Expect(k8sClient.Update(ctx, team)).To(Succeed())
+			reconcileOnce(ctx)
+
+			Expect(fake.inviteDelete[1]).To(BeTrue())
+			Expect(k8sClient.Get(ctx, teamKey, team)).To(Succeed())
+			Expect(team.Status.InviteSecretRef).To(BeNil())
+
+			var secret corev1.Secret
+			err := k8sClient.Get(ctx, types.NamespacedName{Name: secretName, Namespace: team.Namespace}, &secret)
+			Expect(err).To(HaveOccurred(), "the invite Secret should have been deleted")
+		})
+	})
+
 	Describe("deletion", func() {
 		It("deletes the team server-side and removes the credentials Secret", func(ctx SpecContext) {
 			createTeam(ctx, "to-delete", sameNSRef())

internal/controller/terdutteam_invite.go

@@ -0,0 +1,149 @@
+package controller
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"time"
+
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
+
+	terdutv1alpha1 "git.ryuvia.com/niklas/terdut-operator/api/v1alpha1"
+	"git.ryuvia.com/niklas/terdut-operator/internal/tdclient"
+)
+
+// Data keys inside the generated invite Secret, following the same naming
+// shape as TerdutAlertSource's webhookSecret*Key constants.
+const (
+	inviteSecretURLKey       = "url"
+	inviteSecretInviteIDKey  = "inviteID"
+	inviteSecretExpiresAtKey = "expiresAt"
+)
+
+// inviteRefreshWindow is how far ahead of expiry this controller mints a
+// replacement link, so a human reading status.inviteSecretRef never finds a
+// dead link mid-use. terdut-server's invite TTL is a fixed, unconfigurable
+// 7 days (internal/api/signup.go's inviteTTL) -- refreshing a full day
+// ahead of that leaves comfortable margin against this controller's own
+// 5-minute resync interval ever being delayed.
+const inviteRefreshWindow = 24 * time.Hour
+
+func inviteSecretName(team *terdutv1alpha1.TerdutTeam) string {
+	return team.Name + "-terdut-invite"
+}
+
+// reconcileInvite applies spec.invite against teamClient -- this team's own
+// team-scoped credential, already owner-equivalent for every /invites route
+// (terdut-server's SERVICE-ACCOUNTS.md, ratified not accidental). Mints,
+// refreshes ahead of expiry, or revokes, entirely independent of this
+// team's own Ready condition: an invite is a convenience for onboarding a
+// human, never something anything else in this reconcile waits on.
+func (r *TerdutTeamReconciler) reconcileInvite(ctx context.Context, team *terdutv1alpha1.TerdutTeam, teamClient *tdclient.Client) error {
+	if !team.Spec.Invite.Enabled {
+		return r.revokeInvite(ctx, team, teamClient)
+	}
+
+	secretName := inviteSecretName(team)
+	var secret corev1.Secret
+	err := r.Get(ctx, client.ObjectKey{Namespace: team.Namespace, Name: secretName}, &secret)
+	switch {
+	case err == nil:
+		expiresAt, parseErr := time.Parse(time.RFC3339, string(secret.Data[inviteSecretExpiresAtKey]))
+		if parseErr == nil && time.Until(expiresAt) > inviteRefreshWindow {
+			team.Status.InviteSecretRef = &terdutv1alpha1.LocalSecretRef{Name: secretName}
+			return nil // still fresh, nothing to do this reconcile
+		}
+		// Expired, about to expire, or unreadable: mint a replacement.
+		// Revoke the old row by id first (best-effort) so a leaked old link
+		// stops working immediately rather than lingering unrevoked until
+		// its own TTL -- failure here is not fatal, since the replacement
+		// below is what actually matters.
+		if oldID, idErr := strconv.ParseInt(string(secret.Data[inviteSecretInviteIDKey]), 10, 64); idErr == nil {
+			_ = teamClient.RevokeInvite(ctx, team.Status.TeamID, oldID)
+		}
+		return r.mintInvite(ctx, team, teamClient, secretName)
+	case apierrors.IsNotFound(err):
+		// Low stakes, unlike TerdutAlertSource's webhook URL: nothing
+		// external holds a durable dependency on one specific invite link
+		// staying stable the way an Alertmanager config depends on a
+		// webhook URL -- it's read once by one human and handed out. So
+		// this silently re-mints rather than failing closed the way
+		// TerdutAlertSource's ReasonWebhookSecretLost does for its Secret.
+		return r.mintInvite(ctx, team, teamClient, secretName)
+	default:
+		return err
+	}
+}
+
+func (r *TerdutTeamReconciler) mintInvite(
+	ctx context.Context, team *terdutv1alpha1.TerdutTeam, teamClient *tdclient.Client, secretName string,
+) error {
+	role := team.Spec.Invite.Role
+	if role == "" {
+		role = "member"
+	}
+	maxUses := team.Spec.Invite.MaxUses
+	if maxUses == 0 {
+		maxUses = 1
+	}
+	inv, err := teamClient.CreateInvite(ctx, team.Status.TeamID, role, maxUses)
+	if err != nil {
+		return fmt.Errorf("POST /api/teams/%d/invites: %w", team.Status.TeamID, err)
+	}
+
+	secret := &corev1.Secret{ObjectMeta: metav1.ObjectMeta{Name: secretName, Namespace: team.Namespace}}
+	if _, err := controllerutil.CreateOrUpdate(ctx, r.Client, secret, func() error {
+		secret.Data = map[string][]byte{
+			inviteSecretURLKey:       []byte(inv.URL),
+			inviteSecretInviteIDKey:  []byte(strconv.FormatInt(inv.ID, 10)),
+			inviteSecretExpiresAtKey: []byte(inv.ExpiresAt.Format(time.RFC3339)),
+		}
+		return controllerutil.SetControllerReference(team, secret, r.Scheme)
+	}); err != nil {
+		return err
+	}
+	team.Status.InviteSecretRef = &terdutv1alpha1.LocalSecretRef{Name: secretName}
+	if r.Recorder != nil {
+		r.Recorder.Eventf(team, nil, corev1.EventTypeNormal, terdutv1alpha1.ReasonInviteMinted, terdutv1alpha1.ReasonInviteMinted,
+			"invite link minted into Secret %q", secretName)
+	}
+	return nil
+}
+
+// revokeInvite tears down spec.invite's Secret and server-side row when
+// spec.invite.enabled is false (or was never set). Same-namespace and
+// OwnerReference'd, so deleting the TerdutTeam itself already garbage-
+// collects this Secret -- this path exists for the narrower case of
+// flipping enabled back to false on an otherwise-live TerdutTeam.
+func (r *TerdutTeamReconciler) revokeInvite(ctx context.Context, team *terdutv1alpha1.TerdutTeam, teamClient *tdclient.Client) error {
+	if team.Status.InviteSecretRef == nil {
+		return nil
+	}
+	name := team.Status.InviteSecretRef.Name
+	var secret corev1.Secret
+	err := r.Get(ctx, client.ObjectKey{Namespace: team.Namespace, Name: name}, &secret)
+	switch {
+	case err == nil:
+		if id, idErr := strconv.ParseInt(string(secret.Data[inviteSecretInviteIDKey]), 10, 64); idErr == nil {
+			if err := teamClient.RevokeInvite(ctx, team.Status.TeamID, id); err != nil {
+				return fmt.Errorf("DELETE /api/teams/%d/invites/%d: %w", team.Status.TeamID, id, err)
+			}
+		}
+		if err := r.Delete(ctx, &secret); err != nil && !apierrors.IsNotFound(err) {
+			return err
+		}
+	case !apierrors.IsNotFound(err):
+		return err
+	}
+
+	team.Status.InviteSecretRef = nil
+	if r.Recorder != nil {
+		r.Recorder.Eventf(team, nil, corev1.EventTypeNormal, terdutv1alpha1.ReasonInviteRevoked, terdutv1alpha1.ReasonInviteRevoked,
+			"invite link revoked")
+	}
+	return nil
+}

internal/tdclient/client.go

@@ -566,3 +566,50 @@ func (c *Client) DeleteIntegration(ctx context.Context, teamID, integrationID in
 	}
 	return c.do(req, nil)
 }
+
+// Invite is a standing link into a team (POST /api/teams/{teamID}/invites'
+// own response shape). URL carries the raw token exactly once, at creation
+// -- terdut-server never shows it again (same one-time-shown shape as an
+// integration's webhook key) -- so a caller that needs it later has to have
+// kept this response, not re-fetched it.
+type Invite struct {
+	ID        int64     `json:"id"`
+	TeamID    int64     `json:"team_id"`
+	Role      string    `json:"role"`
+	ExpiresAt time.Time `json:"expires_at"`
+	MaxUses   int64     `json:"max_uses"`
+	URL       string    `json:"url,omitempty"`
+}
+
+// CreateInvite calls POST /api/teams/{teamID}/invites -- owner-gated
+// (requireTeamOwner), so c must hold this team's own team-scoped
+// credential, which already satisfies that check via its synthetic owner
+// membership (terdut-server's SERVICE-ACCOUNTS.md). No conflict handling
+// needed: unlike a team or a service account, an invite has no unique name
+// to collide on -- every call mints a brand new row.
+func (c *Client) CreateInvite(ctx context.Context, teamID int64, role string, maxUses int64) (*Invite, error) {
+	req, err := c.newRequest(ctx, http.MethodPost, fmt.Sprintf("/api/teams/%d/invites", teamID),
+		map[string]any{"role": role, "max_uses": maxUses})
+	if err != nil {
+		return nil, err
+	}
+	var inv Invite
+	if err := c.do(req, &inv); err != nil {
+		return nil, err
+	}
+	return &inv, nil
+}
+
+// RevokeInvite calls DELETE /api/teams/{teamID}/invites/{inviteID} -- same
+// credential requirement as CreateInvite. A 404 (already revoked, or never
+// existed) is the caller's to treat as success if it wants to, the same way
+// DeleteTeam's own 404 handling works -- this method itself just reports
+// whatever terdut-server said.
+func (c *Client) RevokeInvite(ctx context.Context, teamID, inviteID int64) error {
+	req, err := c.newRequest(ctx, http.MethodDelete,
+		fmt.Sprintf("/api/teams/%d/invites/%d", teamID, inviteID), nil)
+	if err != nil {
+		return err
+	}
+	return c.do(req, nil)
+}