V0.7.0 shell contract (#54)

server/handlers/groups.go

@@ -4,11 +4,13 @@ import (
 	"database/sql"
 	"errors"
 	"net/http"
+	"time"
 
 	"github.com/gin-gonic/gin"
 
 	"armature/auth"
 	"armature/database"
+	"armature/events"
 	"armature/models"
 	"armature/notifications"
 	"armature/store"
@@ -43,12 +45,30 @@ type setResourceGrantRequest struct {
 
 type GroupHandler struct {
 	stores store.Stores
+	hub    *events.Hub
 }
 
 func NewGroupHandler(s store.Stores) *GroupHandler {
 	return &GroupHandler{stores: s}
 }
 
+// SetHub attaches the event hub for auth change notifications.
+func (h *GroupHandler) SetHub(hub *events.Hub) {
+	h.hub = hub
+}
+
+// notifyAuthChanged sends an auth.changed event to a specific user.
+func (h *GroupHandler) notifyAuthChanged(userID, reason string) {
+	if h.hub == nil {
+		return
+	}
+	h.hub.PublishToUser(userID, events.Event{
+		Label:   "auth.changed",
+		Payload: events.MustJSON(map[string]string{"reason": reason}),
+		Ts:      time.Now().UnixMilli(),
+	})
+}
+
 // ── Admin: List All Groups ──────────────────
 
 func (h *GroupHandler) ListGroups(c *gin.Context) {
@@ -249,6 +269,7 @@ func (h *GroupHandler) AddMember(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"ok": true})
+	h.notifyAuthChanged(req.UserID, "group_member_added")
 	AuditLog(h.stores.Audit, c, "group.member.add", "group", groupID, map[string]interface{}{
 		"user_id": req.UserID,
 	})
@@ -279,6 +300,7 @@ func (h *GroupHandler) RemoveMember(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"ok": true})
+	h.notifyAuthChanged(userID, "group_member_removed")
 	AuditLog(h.stores.Audit, c, "group.member.remove", "group", groupID, map[string]interface{}{
 		"user_id": userID,
 	})

server/handlers/notifications.go

@@ -137,10 +137,9 @@ func (h *NotificationHandler) MarkAllRead(c *gin.Context) {
 
 	// Sync badge across tabs
 	if h.hub != nil {
-		payload, _ := json.Marshal(map[string]string{"action": "mark_all_read"})
 		h.hub.PublishToUser(userID, events.Event{
-			Label:   "notification.read",
-			Payload: payload,
+			Label:   "notification.all_read",
+			Payload: events.MustJSON(map[string]string{}),
 			Ts:      time.Now().UnixMilli(),
 		})
 	}

server/handlers/packages.go

@@ -11,11 +11,13 @@ import (
 	"path/filepath"
 	"regexp"
 	"strings"
+	"time"
 
 	"github.com/gin-gonic/gin"
 	"go.starlark.net/starlark"
 
 	"armature/database"
+	"armature/events"
 	"armature/models"
 	"armature/sandbox"
 	"armature/store"
@@ -34,6 +36,7 @@ type PackageHandler struct {
 	bundledDir     string           // e.g. /app/bundled-packages — .pkg archive source
 	sandbox        *sandbox.Sandbox
 	runner         *sandbox.Runner
+	hub            *events.Hub
 }
 
 func NewPackageHandler(s store.Stores, packagesDir ...string) *PackageHandler {
@@ -60,6 +63,23 @@ func (h *PackageHandler) SetRunner(r *sandbox.Runner) {
 	h.runner = r
 }
 
+// SetHub attaches the event hub for broadcasting package lifecycle events.
+func (h *PackageHandler) SetHub(hub *events.Hub) {
+	h.hub = hub
+}
+
+// broadcastPackageChanged emits a package.changed event to all clients.
+func (h *PackageHandler) broadcastPackageChanged(action, id string) {
+	if h.hub == nil {
+		return
+	}
+	h.hub.Broadcast(events.Event{
+		Label:   "package.changed",
+		Payload: events.MustJSON(map[string]string{"action": action, "id": id}),
+		Ts:      time.Now().UnixMilli(),
+	})
+}
+
 // ListPackages returns all registered packages.
 // GET /api/v1/admin/packages
 func (h *PackageHandler) ListPackages(c *gin.Context) {
@@ -116,6 +136,7 @@ func (h *PackageHandler) EnablePackage(c *gin.Context) {
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"id": id, "enabled": true})
+	h.broadcastPackageChanged("enabled", id)
 }
 
 // DisablePackage disables a package. Admin cannot be disabled.
@@ -133,6 +154,7 @@ func (h *PackageHandler) DisablePackage(c *gin.Context) {
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"id": id, "enabled": false})
+	h.broadcastPackageChanged("disabled", id)
 }
 
 // DeletePackage uninstalls a package. Core packages cannot be deleted.
@@ -180,6 +202,7 @@ func (h *PackageHandler) DeletePackage(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"id": id, "deleted": true})
+	h.broadcastPackageChanged("deleted", id)
 }
 
 // InstallPackage uploads and installs a .pkg/.surface archive.
@@ -586,6 +609,7 @@ func (h *PackageHandler) InstallPackage(c *gin.Context) {
 		resp["status"] = "dormant"
 	}
 	c.JSON(http.StatusOK, resp)
+	h.broadcastPackageChanged("installed", pkgID)
 }
 
 // extractableRelPath returns the relative path for a zip entry if it
@@ -1073,6 +1097,7 @@ func (h *PackageHandler) UpdatePackage(c *gin.Context) {
 		"previous_version": previousVersion,
 		"changes":          schemaChanges,
 	})
+	h.broadcastPackageChanged("updated", pkgID)
 }
 
 // mergePackageSettings merges existing settings with a new manifest's settings schema.

server/handlers/teams.go

@@ -7,11 +7,13 @@ import (
 	"fmt"
 	"net/http"
 	"strconv"
+	"time"
 
 	"github.com/gin-gonic/gin"
 
 	"armature/crypto"
 	"armature/database"
+	"armature/events"
 	"armature/models"
 	"armature/store"
 )
@@ -44,12 +46,30 @@ type updateMemberRequest struct {
 type TeamHandler struct{
 	stores store.Stores
 	vault  *crypto.KeyResolver
+	hub    *events.Hub
 }
 
 func NewTeamHandler(s store.Stores, vault *crypto.KeyResolver) *TeamHandler {
 	return &TeamHandler{stores: s, vault: vault}
 }
 
+// SetHub attaches the event hub for auth change notifications.
+func (h *TeamHandler) SetHub(hub *events.Hub) {
+	h.hub = hub
+}
+
+// notifyAuthChanged sends an auth.changed event to a specific user.
+func (h *TeamHandler) notifyAuthChanged(userID, reason string) {
+	if h.hub == nil {
+		return
+	}
+	h.hub.PublishToUser(userID, events.Event{
+		Label:   "auth.changed",
+		Payload: events.MustJSON(map[string]string{"reason": reason}),
+		Ts:      time.Now().UnixMilli(),
+	})
+}
+
 // ── Admin: List All Teams ───────────────────
 
 func (h *TeamHandler) ListTeams(c *gin.Context) {
@@ -278,6 +298,7 @@ func (h *TeamHandler) AddMember(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusCreated, gin.H{"id": id})
+	h.notifyAuthChanged(req.UserID, "team_member_added")
 	AuditLog(h.stores.Audit, c, "team.add_member", "team", getTeamID(c), map[string]interface{}{
 		"user_id": req.UserID, "role": req.Role,
 	})
@@ -312,6 +333,9 @@ func (h *TeamHandler) UpdateMember(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"ok": true})
+	if uid := h.memberUserID(c.Request.Context(), teamID, memberID); uid != "" {
+		h.notifyAuthChanged(uid, "team_role")
+	}
 	AuditLog(h.stores.Audit, c, "team.update_member", "team", getTeamID(c), map[string]interface{}{
 		"member_id": memberID, "role": req.Role,
 	})
@@ -323,6 +347,9 @@ func (h *TeamHandler) RemoveMember(c *gin.Context) {
 	teamID := getTeamID(c)
 	memberID := c.Param("memberId")
 
+	// Look up user_id before delete for auth notification
+	affectedUID := h.memberUserID(c.Request.Context(), teamID, memberID)
+
 	n, err := h.stores.Teams.DeleteMemberByID(c.Request.Context(), memberID, teamID)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "remove failed"})
@@ -334,6 +361,9 @@ func (h *TeamHandler) RemoveMember(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"ok": true})
+	if affectedUID != "" {
+		h.notifyAuthChanged(affectedUID, "team_member_removed")
+	}
 	AuditLog(h.stores.Audit, c, "team.remove_member", "team", getTeamID(c), map[string]interface{}{
 		"member_id": memberID,
 	})
@@ -467,9 +497,39 @@ func (h *TeamHandler) UpdateRoles(c *gin.Context) {
 	}
 
 	c.JSON(http.StatusOK, gin.H{"data": roles})
+	// Notify all team members — role definitions changed
+	h.notifyTeamMembers(c.Request.Context(), teamID, "team_roles_updated")
 	AuditLog(h.stores.Audit, c, "team.update_roles", "team", teamID, map[string]interface{}{"roles": roles})
 }
 
+// memberUserID looks up the user_id for a team member by row ID.
+func (h *TeamHandler) memberUserID(ctx context.Context, teamID, memberID string) string {
+	members, err := h.stores.Teams.ListMembers(ctx, teamID)
+	if err != nil {
+		return ""
+	}
+	for _, m := range members {
+		if m.ID == memberID {
+			return m.UserID
+		}
+	}
+	return ""
+}
+
+// notifyTeamMembers sends an auth.changed event to all members of a team.
+func (h *TeamHandler) notifyTeamMembers(ctx context.Context, teamID, reason string) {
+	if h.hub == nil {
+		return
+	}
+	members, err := h.stores.Teams.ListMembers(ctx, teamID)
+	if err != nil {
+		return
+	}
+	for _, m := range members {
+		h.notifyAuthChanged(m.UserID, reason)
+	}
+}
+
 // getTeamRoles reads the roles array from team settings, falling back to builtins.
 func getTeamRoles(ctx context.Context, stores store.Stores, teamID string) []string {
 	team, err := stores.Teams.GetByID(ctx, teamID)