refactor(workload): plugin architecture wave + apps UI + volume scopes

Completes the workload-first refactor's plugin layer:

- internal/workload/plugin/ — Source/Trigger plugin contract,
  registry, types (Workload, DeploymentIntent, InboundEvent,
  PublicFace). Self-registering init() pattern + blank-import
  in cmd/server/main.go.
- Source plugins: image (blue-green with multi-face proxy routing),
  compose, static. Trigger plugins: registry, git, manual.
- internal/deployer/dispatch.go — DispatchPlugin/Teardown/Reconcile
  seam routing the legacy deployer through plugins.
- internal/api/workload_*.go — REST surface: workloads, env,
  volumes, chain (parent/children), promote-from. hooks.go
  serves /api/hooks/kinds/{kind}/schema for the wizard.
- internal/store: workload_env (encrypt-at-rest secrets) and
  workload_volumes tables, keyed on workload_id.
- cmd/server/static_backend.go — phantom-row adapter delegating
  the static source plugin to the legacy staticsite.Manager
  (deleted at hard cutover once the static inline port lands).
- web/src/routes/apps/ — /apps list + /apps/new wizard +
  /apps/[id] detail with kind-aware compose / image / static
  forms (Advanced JSON toggle), env panel, volumes panel,
  webhook panel, chain panel, manual deploy.

Volume scope generalization (v2 resolver):

- internal/volume.ResolveWorkloadPath (workload-keyed, sits
  next to legacy ResolvePath). Honors all VolumeScope values:
  absolute, ephemeral, instance, stage, project, project_named,
  named. internal/workload/plugin/source/image/image.go
  computeMounts wires settings + imageTag through. Coverage in
  internal/volume/resolver_test.go (portable Linux/Windows via
  t.TempDir).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

internal/api/hooks.go

@@ -0,0 +1,154 @@
+package api
+
+import (
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"github.com/alexei/tinyforge/internal/workload/plugin"
+)
+
+// getHookKindSchema returns the sample config shape for one registered
+// plugin kind. Used by /apps/new and the edit form so the JSON editor's
+// initial body is derived from the plugin itself rather than hardcoded
+// in the frontend.
+//
+//	GET /api/hooks/kinds/{kind}/schema
+func (s *Server) getHookKindSchema(w http.ResponseWriter, r *http.Request) {
+	kind := chi.URLParam(r, "kind")
+	sample, ok := plugin.SchemaSampleFor(kind)
+	if !ok {
+		respondNotFound(w, "plugin kind")
+		return
+	}
+	respondJSON(w, http.StatusOK, map[string]any{
+		"kind":   kind,
+		"sample": sample,
+	})
+}
+
+// listHookKinds reports every registered Source and Trigger so operators
+// can verify the plugin registry is wired correctly without writing
+// a workload.
+//
+//	GET /api/hooks/kinds
+func (s *Server) listHookKinds(w http.ResponseWriter, r *http.Request) {
+	respondJSON(w, http.StatusOK, map[string]any{
+		"sources":  plugin.SourceKinds(),
+		"triggers": plugin.TriggerKinds(),
+	})
+}
+
+// dispatchGeneric accepts a pre-normalized InboundEvent payload and fans
+// it out across registered triggers. The body shape mirrors
+// plugin.InboundEvent — vendor-specific webhook parsing (Gitea / GitHub /
+// generic registry) stays in the legacy /api/webhook/* handlers until
+// Phase 5 of the refactor migrates them into trigger-specific ingress.
+//
+//	POST /api/hooks/generic
+//	{
+//	  "kind": "image-push",
+//	  "image": { "registry": "...", "repo": "owner/app", "tag": "v1" }
+//	}
+//
+// Until the store rewrite lands and workloads carry source_kind /
+// trigger_kind, the workloads iteration here returns an empty list and
+// the response reports zero matches. This still exercises the registry
+// path so operators can curl it and confirm wiring.
+func (s *Server) dispatchGeneric(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		respondError(w, http.StatusBadRequest, "read body: "+err.Error())
+		return
+	}
+	var evt plugin.InboundEvent
+	if err := json.Unmarshal(body, &evt); err != nil {
+		respondError(w, http.StatusBadRequest, "invalid InboundEvent: "+err.Error())
+		return
+	}
+	if evt.Kind == "" {
+		respondError(w, http.StatusBadRequest, "kind is required")
+		return
+	}
+
+	ctx := r.Context()
+	triggers := plugin.AllTriggers()
+	workloads := listPluginWorkloads(s)
+	deps := s.deployer.PluginDeps()
+
+	type matchReport struct {
+		WorkloadID    string `json:"workload_id"`
+		TriggerKind   string `json:"trigger_kind"`
+		Reference     string `json:"reference"`
+		Dispatched    bool   `json:"dispatched"`
+		DispatchError string `json:"dispatch_error,omitempty"`
+	}
+	matches := []matchReport{}
+
+	for _, wl := range workloads {
+		trig, ok := triggers[wl.TriggerKind]
+		if !ok {
+			continue
+		}
+		intent, err := trig.Match(ctx, deps, wl, evt)
+		if err != nil {
+			slog.Warn("hooks: trigger match error",
+				"trigger", wl.TriggerKind, "workload", wl.ID, "error", err)
+			continue
+		}
+		if intent == nil {
+			continue
+		}
+		if intent.TriggeredAt.IsZero() {
+			intent.TriggeredAt = time.Now().UTC()
+		}
+		report := matchReport{
+			WorkloadID:  wl.ID,
+			TriggerKind: wl.TriggerKind,
+			Reference:   intent.Reference,
+		}
+		if err := s.deployer.DispatchPlugin(ctx, wl, *intent); err != nil {
+			// Wrapped error can carry registry-auth bytes / compose stdout
+			// (i.e. user secrets baked into the YAML); keep it server-side
+			// only and return a generic flag to the client.
+			slog.Warn("hooks: dispatch failed",
+				"workload", wl.ID, "trigger", wl.TriggerKind, "error", err)
+			report.DispatchError = "dispatch failed; see server logs"
+		} else {
+			report.Dispatched = true
+		}
+		matches = append(matches, report)
+	}
+
+	respondJSON(w, http.StatusAccepted, map[string]any{
+		"event_kind":         evt.Kind,
+		"examined_triggers":  len(triggers),
+		"examined_workloads": len(workloads),
+		"matches":            matches,
+	})
+}
+
+// listPluginWorkloads returns every workload row whose source_kind and
+// trigger_kind are both set — these are the rows that opted into the new
+// plugin pipeline. Legacy rows (kind/ref_id pointing at project/stack/site
+// with empty source_kind) are skipped so the ingress only fires intents
+// for workloads that have a registered Source + Trigger to dispatch them.
+func listPluginWorkloads(s *Server) []plugin.Workload {
+	rows, err := s.store.ListWorkloads("")
+	if err != nil {
+		slog.Warn("hooks: list workloads failed", "error", err)
+		return nil
+	}
+	out := make([]plugin.Workload, 0, len(rows))
+	for _, w := range rows {
+		if w.SourceKind == "" || w.TriggerKind == "" {
+			continue
+		}
+		out = append(out, toPluginWorkload(w))
+	}
+	return out
+}

internal/api/instances.go

@@ -10,6 +10,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"github.com/alexei/tinyforge/internal/store"
+	"github.com/alexei/tinyforge/internal/workload/plugin"
 )
 
 // listInstances handles GET /api/projects/{id}/stages/{stage}/instances.
@@ -216,10 +217,21 @@ func (s *Server) controlInstance(w http.ResponseWriter, r *http.Request, action
 	})
 }
 
-// DeployTriggerer is the interface for triggering deployments.
+// DeployTriggerer is the interface for triggering deployments. The legacy
+// project/stage methods continue to drive image-tag CI promotions; the
+// plugin methods (DispatchPlugin / DispatchTeardown / DispatchReconcile)
+// route through the unified Source registry. Both surfaces are kept on
+// one interface so the API layer holds a single deployer reference and
+// the type assertion in hooks.go / workloads_plugin.go is replaced with
+// compile-time checking.
 type DeployTriggerer interface {
 	TriggerDeploy(ctx context.Context, projectID, stageID, imageTag string) error
 	AsyncTriggerDeploy(ctx context.Context, projectID, stageID, imageTag string) (string, error)
+
+	DispatchPlugin(ctx context.Context, w plugin.Workload, intent plugin.DeploymentIntent) error
+	DispatchTeardown(ctx context.Context, w plugin.Workload) error
+	DispatchReconcile(ctx context.Context, w plugin.Workload) error
+	PluginDeps() plugin.Deps
 }
 
 // resolveAndAuthorizeInstance loads the container row identified by {iid} and

internal/api/middleware.go

@@ -161,6 +161,24 @@ func jsonContentType(next http.Handler) http.Handler {
 	})
 }
 
+// deprecated marks responses with RFC-8594-style headers so API consumers
+// can detect that an endpoint is on its way out. The Workload-first
+// refactor is migrating away from /api/projects, /api/stages,
+// /api/static_sites, and /api/stacks toward /api/workloads; this signals
+// it to integrators without breaking them. Date is the operator-facing
+// sunset hint, not a hard switch.
+func deprecated(replacement string) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Deprecation", "true")
+			if replacement != "" {
+				w.Header().Set("Link", `<`+replacement+`>; rel="successor-version"`)
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
 // rateLimitMiddleware wraps a handler with per-IP rate limiting using the
 // supplied limiter. Requests over the limit get 429.
 func rateLimitMiddleware(rl *rateLimiter) func(http.Handler) http.Handler {

internal/api/response.go

@@ -38,6 +38,10 @@ func respondNotFound(w http.ResponseWriter, entity string) {
 
 // decodeJSON reads and decodes the request body into the given value.
 // Returns false and writes a 400 error response if decoding fails.
+//
+// Lenient: unknown fields are silently dropped to keep legacy clients
+// compatible. New endpoints that take opaque user-controlled JSON should
+// use decodeJSONStrict instead.
 func decodeJSON(w http.ResponseWriter, r *http.Request, v any) bool {
 	if err := json.NewDecoder(r.Body).Decode(v); err != nil {
 		respondError(w, http.StatusBadRequest, "invalid JSON: "+err.Error())
@@ -45,3 +49,17 @@ func decodeJSON(w http.ResponseWriter, r *http.Request, v any) bool {
 	}
 	return true
 }
+
+// decodeJSONStrict is decodeJSON plus DisallowUnknownFields. Use for
+// endpoints whose request shape is opaque (e.g. workload source/trigger
+// config blobs) — surfacing typos client-side beats silently dropping
+// fields the server then can't act on.
+func decodeJSONStrict(w http.ResponseWriter, r *http.Request, v any) bool {
+	dec := json.NewDecoder(r.Body)
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(v); err != nil {
+		respondError(w, http.StatusBadRequest, "invalid JSON: "+err.Error())
+		return false
+	}
+	return true
+}

internal/api/workload_chain.go

@@ -0,0 +1,213 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"github.com/alexei/tinyforge/internal/auth"
+	"github.com/alexei/tinyforge/internal/store"
+	"github.com/alexei/tinyforge/internal/workload/plugin"
+)
+
+// chainNode is the lightweight shape returned by /chain — we deliberately
+// don't return full plugin.Workload values for ancestor/descendant rows
+// because the secret fields don't belong in a chain-traversal response.
+type chainNode struct {
+	ID         string `json:"id"`
+	Name       string `json:"name"`
+	SourceKind string `json:"source_kind"`
+	TriggerKind string `json:"trigger_kind"`
+	CreatedAt  string `json:"created_at"`
+	UpdatedAt  string `json:"updated_at"`
+}
+
+func chainNodeOf(w store.Workload) chainNode {
+	return chainNode{
+		ID:          w.ID,
+		Name:        w.Name,
+		SourceKind:  w.SourceKind,
+		TriggerKind: w.TriggerKind,
+		CreatedAt:   w.CreatedAt,
+		UpdatedAt:   w.UpdatedAt,
+	}
+}
+
+// getWorkloadChain handles GET /api/workloads/{id}/chain.
+//
+// Returns the workload's parent (or nil), itself, and its direct children
+// — i.e. one hop in each direction along the parent_workload_id graph.
+// Deeper traversal is left to the client: the chain is a tree the user
+// builds incrementally, and a server-side recursive walk would surprise
+// operators with O(N) loads on big graphs.
+func (s *Server) getWorkloadChain(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+
+	self, err := s.store.GetWorkloadByID(id)
+	if err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "get workload")
+		return
+	}
+
+	var parent *chainNode
+	if self.ParentWorkloadID != "" {
+		p, err := s.store.GetWorkloadByID(self.ParentWorkloadID)
+		if err == nil {
+			node := chainNodeOf(p)
+			parent = &node
+		} else if !errors.Is(err, store.ErrNotFound) {
+			slog.Warn("chain: parent lookup failed", "workload", id, "parent", self.ParentWorkloadID, "error", err)
+		}
+	}
+
+	childRows, err := s.store.ListChildrenByParent(self.ID)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "list children")
+		return
+	}
+	children := make([]chainNode, 0, len(childRows))
+	for _, c := range childRows {
+		children = append(children, chainNodeOf(c))
+	}
+
+	respondJSON(w, http.StatusOK, map[string]any{
+		"parent":   parent,
+		"self":     chainNodeOf(self),
+		"children": children,
+	})
+}
+
+// promoteFromRequest is the body of /promote-from. ImageTag is optional —
+// when blank the server falls back to whatever tag the source workload's
+// most recent running container reports. The endpoint is intentionally
+// non-destructive: it updates the SourceConfig.default_tag and queues a
+// manual deploy. It does not change parent_workload_id.
+type promoteFromRequest struct {
+	ImageTag string `json:"image_tag"`
+	Deploy   bool   `json:"deploy"`
+}
+
+// promoteFromWorkload handles POST /api/workloads/{id}/promote-from/{sourceID}.
+//
+// Copies the source workload's currently-running image tag into the
+// target's SourceConfig.default_tag, optionally triggering an immediate
+// deploy. The target's existing config blob is preserved aside from the
+// promoted field. Both workloads must use the same source_kind (image)
+// — promoting across kinds is undefined and rejected.
+func (s *Server) promoteFromWorkload(w http.ResponseWriter, r *http.Request) {
+	targetID := chi.URLParam(r, "id")
+	sourceID := chi.URLParam(r, "sourceID")
+	if targetID == sourceID {
+		respondError(w, http.StatusBadRequest, "target and source must differ")
+		return
+	}
+
+	target, err := s.store.GetWorkloadByID(targetID)
+	if err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "get target workload")
+		return
+	}
+	source, err := s.store.GetWorkloadByID(sourceID)
+	if err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "source workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "get source workload")
+		return
+	}
+	if target.SourceKind != "image" || source.SourceKind != "image" {
+		respondError(w, http.StatusBadRequest, "promote-from is only defined for image source workloads on both ends")
+		return
+	}
+
+	var req promoteFromRequest
+	if r.ContentLength > 0 {
+		if !decodeJSONStrict(w, r, &req) {
+			return
+		}
+	}
+
+	// Resolve the tag: explicit override wins; otherwise pick the running
+	// container's image_tag on the source workload.
+	tag := strings.TrimSpace(req.ImageTag)
+	if tag == "" {
+		rows, err := s.store.ListContainersByWorkload(sourceID)
+		if err != nil {
+			respondError(w, http.StatusInternalServerError, "list source containers")
+			return
+		}
+		for _, c := range rows {
+			if c.State == "running" && c.ImageTag != "" {
+				tag = c.ImageTag
+				break
+			}
+		}
+		if tag == "" {
+			respondError(w, http.StatusBadRequest, "source workload has no running container; specify image_tag explicitly")
+			return
+		}
+	}
+
+	// Decode target source_config, patch default_tag, re-encode.
+	cfg := map[string]any{}
+	if target.SourceConfig != "" && target.SourceConfig != "{}" {
+		if err := json.Unmarshal([]byte(target.SourceConfig), &cfg); err != nil {
+			respondError(w, http.StatusInternalServerError, "decode target source_config")
+			return
+		}
+	}
+	cfg["default_tag"] = tag
+	patched, err := json.Marshal(cfg)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "encode target source_config")
+		return
+	}
+	target.SourceConfig = string(patched)
+	if err := s.store.UpdateWorkload(target); err != nil {
+		slog.Error("promote: update target", "target", targetID, "error", err)
+		respondError(w, http.StatusInternalServerError, "update target workload")
+		return
+	}
+
+	actor := "promote"
+	if claims, ok := auth.ClaimsFromContext(r.Context()); ok && claims.Username != "" {
+		actor = claims.Username
+	}
+	resp := map[string]any{
+		"workload_id":   targetID,
+		"source_id":     sourceID,
+		"promoted_tag":  tag,
+		"deploy_queued": false,
+	}
+	if req.Deploy {
+		intent := plugin.DeploymentIntent{
+			Reason:      "promote",
+			Reference:   tag,
+			Metadata:    map[string]string{"source_workload_id": sourceID},
+			TriggeredAt: time.Now().UTC(),
+			TriggeredBy: actor,
+		}
+		if err := s.deployer.DispatchPlugin(r.Context(), toPluginWorkload(target), intent); err != nil {
+			slog.Warn("promote: dispatch failed", "target", targetID, "error", err)
+			respondError(w, http.StatusInternalServerError, "dispatch failed; see server logs")
+			return
+		}
+		resp["deploy_queued"] = true
+	}
+	respondJSON(w, http.StatusOK, resp)
+}
+

internal/api/workload_convert.go

@@ -0,0 +1,89 @@
+package api
+
+import (
+	"encoding/json"
+	"log/slog"
+
+	"github.com/alexei/tinyforge/internal/store"
+	"github.com/alexei/tinyforge/internal/workload/plugin"
+)
+
+// toPluginWorkload converts a persisted store.Workload row into the value
+// shape that Source / Trigger plugins consume. Lives in the api package
+// (rather than store or plugin) to keep plugin's dependency graph free of
+// store imports and avoid the cycle that would form otherwise.
+//
+// SourceConfig / TriggerConfig are passed through as raw JSON; the matching
+// plugin decodes them with plugin.SourceConfigOf[T] / TriggerConfigOf[T].
+// PublicFaces is decoded eagerly because every consumer needs the parsed
+// slice (proxy registration, UI, validation).
+func toPluginWorkload(w store.Workload) plugin.Workload {
+	var faces []plugin.PublicFace
+	if w.PublicFaces != "" {
+		if err := json.Unmarshal([]byte(w.PublicFaces), &faces); err != nil {
+			slog.Warn("workload: invalid public_faces JSON, treating as empty",
+				"workload", w.ID, "error", err)
+			faces = nil
+		}
+	}
+	return plugin.Workload{
+		ID:                      w.ID,
+		Name:                    w.Name,
+		GroupID:                 w.AppID,
+		ParentWorkloadID:        w.ParentWorkloadID,
+		SourceKind:              w.SourceKind,
+		SourceConfig:            json.RawMessage(w.SourceConfig),
+		TriggerKind:             w.TriggerKind,
+		TriggerConfig:           json.RawMessage(w.TriggerConfig),
+		PublicFaces:             faces,
+		NotificationURL:         w.NotificationURL,
+		NotificationSecret:      w.NotificationSecret,
+		WebhookSecret:           w.WebhookSecret,
+		WebhookSigningSecret:    w.WebhookSigningSecret,
+		WebhookRequireSignature: w.WebhookRequireSignature,
+		CreatedAt:               w.CreatedAt,
+		UpdatedAt:               w.UpdatedAt,
+	}
+}
+
+// fromPluginWorkload is the symmetric direction — used by /api/workloads
+// create + update handlers. Returns a store.Workload ready to pass to
+// store.CreateWorkload / store.UpdateWorkload. The caller is responsible
+// for re-encoding PublicFaces; we do it here to keep the JSON shape in
+// one place.
+func fromPluginWorkload(p plugin.Workload) (store.Workload, error) {
+	facesJSON := "[]"
+	if len(p.PublicFaces) > 0 {
+		b, err := json.Marshal(p.PublicFaces)
+		if err != nil {
+			return store.Workload{}, err
+		}
+		facesJSON = string(b)
+	}
+	srcCfg := string(p.SourceConfig)
+	if srcCfg == "" {
+		srcCfg = "{}"
+	}
+	trgCfg := string(p.TriggerConfig)
+	if trgCfg == "" {
+		trgCfg = "{}"
+	}
+	return store.Workload{
+		ID:                      p.ID,
+		Name:                    p.Name,
+		AppID:                   p.GroupID,
+		ParentWorkloadID:        p.ParentWorkloadID,
+		SourceKind:              p.SourceKind,
+		SourceConfig:            srcCfg,
+		TriggerKind:             p.TriggerKind,
+		TriggerConfig:           trgCfg,
+		PublicFaces:             facesJSON,
+		NotificationURL:         p.NotificationURL,
+		NotificationSecret:      p.NotificationSecret,
+		WebhookSecret:           p.WebhookSecret,
+		WebhookSigningSecret:    p.WebhookSigningSecret,
+		WebhookRequireSignature: p.WebhookRequireSignature,
+		CreatedAt:               p.CreatedAt,
+		UpdatedAt:               p.UpdatedAt,
+	}, nil
+}

internal/api/workload_env.go

@@ -0,0 +1,214 @@
+package api
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	"github.com/alexei/tinyforge/internal/crypto"
+	"github.com/alexei/tinyforge/internal/store"
+)
+
+// workloadEnvRow is the JSON shape returned to clients. Plaintext is
+// redacted for encrypted entries — once a value is encrypted, the
+// server treats it as write-only. To rotate, the operator submits a new
+// value; to read, they have to look at the running container.
+type workloadEnvRow struct {
+	ID         string `json:"id"`
+	WorkloadID string `json:"workload_id"`
+	Key        string `json:"key"`
+	Value      string `json:"value"`
+	Encrypted  bool   `json:"encrypted"`
+	CreatedAt  string `json:"created_at"`
+	UpdatedAt  string `json:"updated_at"`
+}
+
+func (s *Server) listWorkloadEnv(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+	if _, err := s.store.GetWorkloadByID(id); err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "get workload")
+		return
+	}
+	rows, err := s.store.ListWorkloadEnv(id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "list workload env")
+		return
+	}
+	out := make([]workloadEnvRow, 0, len(rows))
+	for _, e := range rows {
+		row := workloadEnvRow{
+			ID:         e.ID,
+			WorkloadID: e.WorkloadID,
+			Key:        e.Key,
+			Encrypted:  e.Encrypted,
+			CreatedAt:  e.CreatedAt,
+			UpdatedAt:  e.UpdatedAt,
+		}
+		if e.Encrypted {
+			row.Value = "" // write-only after encryption
+		} else {
+			row.Value = e.Value
+		}
+		out = append(out, row)
+	}
+	respondJSON(w, http.StatusOK, out)
+}
+
+// setWorkloadEnvRequest is the POST/PUT body. Encrypted=true causes the
+// server to encrypt the value at rest with the global encryption key.
+type setWorkloadEnvRequest struct {
+	Key       string `json:"key"`
+	Value     string `json:"value"`
+	Encrypted bool   `json:"encrypted"`
+}
+
+func (s *Server) setWorkloadEnv(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+	if _, err := s.store.GetWorkloadByID(id); err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "get workload")
+		return
+	}
+	var req setWorkloadEnvRequest
+	if !decodeJSONStrict(w, r, &req) {
+		return
+	}
+	req.Key = strings.TrimSpace(req.Key)
+	if req.Key == "" {
+		respondError(w, http.StatusBadRequest, "key is required")
+		return
+	}
+	if !validEnvKey(req.Key) {
+		respondError(w, http.StatusBadRequest, "key must match [A-Za-z_][A-Za-z0-9_]*")
+		return
+	}
+	value := req.Value
+	if req.Encrypted && value != "" {
+		enc, err := crypto.Encrypt(s.encKey, value)
+		if err != nil {
+			respondError(w, http.StatusInternalServerError, "encrypt value")
+			return
+		}
+		value = enc
+	}
+	row, err := s.store.SetWorkloadEnv(store.WorkloadEnv{
+		WorkloadID: id,
+		Key:        req.Key,
+		Value:      value,
+		Encrypted:  req.Encrypted,
+	})
+	if err != nil {
+		slog.Error("set workload env", "workload", id, "key", req.Key, "error", err)
+		respondError(w, http.StatusInternalServerError, "set workload env")
+		return
+	}
+	respondJSON(w, http.StatusOK, workloadEnvRow{
+		ID:         row.ID,
+		WorkloadID: row.WorkloadID,
+		Key:        row.Key,
+		Value:      "", // never echo even fresh writes — caller already has it
+		Encrypted:  row.Encrypted,
+		CreatedAt:  row.CreatedAt,
+		UpdatedAt:  row.UpdatedAt,
+	})
+}
+
+func (s *Server) deleteWorkloadEnv(w http.ResponseWriter, r *http.Request) {
+	envID := chi.URLParam(r, "envID")
+	if err := s.store.DeleteWorkloadEnv(envID); err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload env")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "delete workload env")
+		return
+	}
+	respondJSON(w, http.StatusOK, map[string]string{"deleted": envID})
+}
+
+// getWorkloadWebhook handles GET /api/workloads/{id}/webhook. Returns
+// the canonical URL + secret + signature-state flags. Lazily generates
+// a secret if the workload row predates the column.
+func (s *Server) getWorkloadWebhook(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+	secret, err := s.store.EnsureWorkloadWebhookSecret(id)
+	if err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		slog.Error("ensure workload webhook secret", "workload", id, "error", err)
+		respondError(w, http.StatusInternalServerError, "failed to get webhook secret")
+		return
+	}
+	row, err := s.store.GetWorkloadByID(id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to get workload")
+		return
+	}
+	respondJSON(w, http.StatusOK, webhookURLResponse{
+		WebhookURL:              "/api/webhook/workloads/" + secret,
+		WebhookSecret:           secret,
+		HasSigningSecret:        row.WebhookSigningSecret != "",
+		WebhookRequireSignature: row.WebhookRequireSignature,
+	})
+}
+
+// regenerateWorkloadWebhook handles POST /api/workloads/{id}/webhook/regenerate.
+// Rotates the URL secret. The old secret is invalidated immediately —
+// any external system still hitting the old URL gets a 404 on next call.
+func (s *Server) regenerateWorkloadWebhook(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+	if _, err := s.store.GetWorkloadByID(id); err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "failed to get workload")
+		return
+	}
+	secret := generateWebhookSecret()
+	if err := s.store.SetWorkloadWebhookSecret(id, secret); err != nil {
+		slog.Error("rotate workload webhook secret", "workload", id, "error", err)
+		respondError(w, http.StatusInternalServerError, "failed to rotate webhook secret")
+		return
+	}
+	row, _ := s.store.GetWorkloadByID(id)
+	respondJSON(w, http.StatusOK, webhookURLResponse{
+		WebhookURL:              "/api/webhook/workloads/" + secret,
+		WebhookSecret:           secret,
+		HasSigningSecret:        row.WebhookSigningSecret != "",
+		WebhookRequireSignature: row.WebhookRequireSignature,
+	})
+}
+
+// validEnvKey accepts POSIX-style env names. Rejects anything that would
+// confuse Docker's env parser (=, spaces, control chars).
+func validEnvKey(k string) bool {
+	if len(k) == 0 || len(k) > 256 {
+		return false
+	}
+	for i, ch := range k {
+		switch {
+		case ch >= 'A' && ch <= 'Z',
+			ch >= 'a' && ch <= 'z',
+			ch == '_':
+			continue
+		case (ch >= '0' && ch <= '9') && i > 0:
+			continue
+		default:
+			return false
+		}
+	}
+	return true
+}

internal/api/workload_volumes.go

@@ -0,0 +1,114 @@
+package api
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	"github.com/alexei/tinyforge/internal/store"
+)
+
+// workloadVolumeRequest is the body shape accepted by the upsert
+// endpoint. Defaults to scope=absolute when unset.
+type workloadVolumeRequest struct {
+	Source string `json:"source"`
+	Target string `json:"target"`
+	Scope  string `json:"scope"`
+	Name   string `json:"name"`
+}
+
+func (s *Server) listWorkloadVolumes(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+	if _, err := s.store.GetWorkloadByID(id); err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "get workload")
+		return
+	}
+	rows, err := s.store.ListWorkloadVolumes(id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "list workload volumes")
+		return
+	}
+	respondJSON(w, http.StatusOK, rows)
+}
+
+func (s *Server) setWorkloadVolume(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+	if _, err := s.store.GetWorkloadByID(id); err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "get workload")
+		return
+	}
+	var req workloadVolumeRequest
+	if !decodeJSONStrict(w, r, &req) {
+		return
+	}
+	req.Target = strings.TrimSpace(req.Target)
+	if req.Target == "" {
+		respondError(w, http.StatusBadRequest, "target is required")
+		return
+	}
+	if !strings.HasPrefix(req.Target, "/") {
+		respondError(w, http.StatusBadRequest, "target must be an absolute container path")
+		return
+	}
+	if strings.Contains(req.Target, "..") {
+		respondError(w, http.StatusBadRequest, "target may not contain path traversal segments")
+		return
+	}
+	scope := req.Scope
+	if scope == "" {
+		scope = string(store.VolumeScopeAbsolute)
+	}
+	if !store.IsValidVolumeScope(scope) {
+		respondError(w, http.StatusBadRequest, "invalid scope")
+		return
+	}
+	// Absolute-scope mounts must reference a real host path; allow-list
+	// enforcement happens at deploy time against settings.AllowedVolumePaths.
+	if scope == string(store.VolumeScopeAbsolute) {
+		if strings.TrimSpace(req.Source) == "" {
+			respondError(w, http.StatusBadRequest, "source is required for absolute scope")
+			return
+		}
+		if strings.Contains(req.Source, "..") {
+			respondError(w, http.StatusBadRequest, "source may not contain path traversal segments")
+			return
+		}
+	}
+	row, err := s.store.SetWorkloadVolume(store.WorkloadVolume{
+		WorkloadID: id,
+		Source:     req.Source,
+		Target:     req.Target,
+		Scope:      scope,
+		Name:       req.Name,
+	})
+	if err != nil {
+		slog.Error("set workload volume", "workload", id, "target", req.Target, "error", err)
+		respondError(w, http.StatusInternalServerError, "set workload volume")
+		return
+	}
+	respondJSON(w, http.StatusOK, row)
+}
+
+func (s *Server) deleteWorkloadVolume(w http.ResponseWriter, r *http.Request) {
+	volID := chi.URLParam(r, "volID")
+	if err := s.store.DeleteWorkloadVolume(volID); err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload volume")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "delete workload volume")
+		return
+	}
+	respondJSON(w, http.StatusOK, map[string]string{"deleted": volID})
+}

internal/api/workloads.go

@@ -36,6 +36,36 @@ func (s *Server) getWorkload(w http.ResponseWriter, r *http.Request) {
 	respondJSON(w, http.StatusOK, wl)
 }
 
+// streamWorkloadContainerLogs handles GET /api/workloads/{id}/containers/{cid}/logs.
+// Reuses the shared SSE/JSON log streamer; ownership is verified by joining
+// through workload_id on the container row so an attacker can't stream
+// logs from a foreign container by guessing IDs under the wrong workload URL.
+func (s *Server) streamWorkloadContainerLogs(w http.ResponseWriter, r *http.Request) {
+	workloadID := chi.URLParam(r, "id")
+	containerRowID := chi.URLParam(r, "cid")
+
+	c, err := s.store.GetContainerByID(containerRowID)
+	if err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "container")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "internal server error")
+		return
+	}
+	if c.WorkloadID != workloadID {
+		// Returning 404 (not 403) so the existence of a container under
+		// another workload is not confirmed.
+		respondNotFound(w, "container")
+		return
+	}
+	if c.ContainerID == "" {
+		respondError(w, http.StatusBadRequest, "container row has no docker container bound")
+		return
+	}
+	s.streamLogsForContainer(w, r, c.ContainerID)
+}
+
 // listWorkloadContainers handles GET /api/workloads/{id}/containers.
 // Returns every Container row owned by this workload, newest first. The
 // frontend's <WorkloadContainers> component uses this on every kind-specific

internal/api/workloads_plugin.go

@@ -0,0 +1,293 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"github.com/alexei/tinyforge/internal/auth"
+	"github.com/alexei/tinyforge/internal/store"
+	"github.com/alexei/tinyforge/internal/workload/plugin"
+)
+
+// pluginWorkloadRequest is the JSON body accepted by create + update.
+// SourceConfig / TriggerConfig are raw JSON blobs validated by the
+// matching plugin's Validate() before persistence.
+type pluginWorkloadRequest struct {
+	Name                    string              `json:"name"`
+	GroupID                 string              `json:"group_id"`
+	ParentWorkloadID        string              `json:"parent_workload_id"`
+	SourceKind              string              `json:"source_kind"`
+	SourceConfig            json.RawMessage     `json:"source_config"`
+	TriggerKind             string              `json:"trigger_kind"`
+	TriggerConfig           json.RawMessage     `json:"trigger_config"`
+	PublicFaces             []plugin.PublicFace `json:"public_faces"`
+	NotificationURL         string              `json:"notification_url"`
+	WebhookRequireSignature bool                `json:"webhook_require_signature"`
+}
+
+// Per-blob caps so two opaque JSON fields can't blow past the route-level
+// body limit individually. The route already caps the whole body, but a
+// 1 MiB SourceConfig is unreasonable for any source we plan to support.
+const (
+	maxSourceConfigBytes  = 64 << 10 // 64 KiB
+	maxTriggerConfigBytes = 16 << 10 // 16 KiB
+	// Hard upper bound on public faces — multi-face is now supported (route
+	// IDs are stored per-fqdn in container.extra_json so teardown is clean)
+	// but a workload with hundreds of public faces is almost certainly a
+	// bug in the caller, not legitimate config.
+	maxPublicFaces = 16
+)
+
+// createPluginWorkload handles POST /api/workloads.
+//
+// Validates source/trigger kinds against the registered plugins, runs each
+// plugin's own Validate() on its config blob, then persists the row. The
+// row is created with the new plugin-shape fields populated; the legacy
+// kind/ref_id columns stay empty for plugin-native workloads.
+func (s *Server) createPluginWorkload(w http.ResponseWriter, r *http.Request) {
+	var req pluginWorkloadRequest
+	if !decodeJSONStrict(w, r, &req) {
+		return
+	}
+	if strings.TrimSpace(req.Name) == "" {
+		respondError(w, http.StatusBadRequest, "name is required")
+		return
+	}
+	if err := validatePluginKinds(req); err != nil {
+		respondError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+
+	pw := plugin.Workload{
+		Name:                    req.Name,
+		GroupID:                 req.GroupID,
+		ParentWorkloadID:        req.ParentWorkloadID,
+		SourceKind:              req.SourceKind,
+		SourceConfig:            req.SourceConfig,
+		TriggerKind:             req.TriggerKind,
+		TriggerConfig:           req.TriggerConfig,
+		PublicFaces:             req.PublicFaces,
+		NotificationURL:         req.NotificationURL,
+		WebhookRequireSignature: req.WebhookRequireSignature,
+	}
+	sw, err := fromPluginWorkload(pw)
+	if err != nil {
+		respondError(w, http.StatusBadRequest, "encode workload: "+err.Error())
+		return
+	}
+	// Plugin-native rows are flagged with kind="plugin"; ref_id is left
+	// empty by the caller and filled with the generated ID below so the
+	// UNIQUE(kind, ref_id) index can hold many plugin workloads (each
+	// pair is the row's own ID, which is itself unique).
+	sw.Kind = "plugin"
+	created, err := s.store.CreateWorkload(sw)
+	if err != nil {
+		slog.Error("create plugin workload", "error", err)
+		respondError(w, http.StatusInternalServerError, "create workload")
+		return
+	}
+	if created.RefID == "" {
+		// Self-reference so (kind, ref_id) stays unique. Done as a follow-up
+		// update — CreateWorkload generates the UUID itself, so the value is
+		// only known after insert.
+		created.RefID = created.ID
+		if err := s.store.UpdateWorkload(created); err != nil {
+			slog.Warn("backfill plugin workload ref_id", "id", created.ID, "error", err)
+		}
+	}
+	respondJSON(w, http.StatusCreated, toPluginWorkload(created))
+}
+
+// updatePluginWorkload handles PUT /api/workloads/{id}/plugin. Only the
+// fields that belong to the plugin model are mutable here; legacy
+// project/stack/site fields are edited through their own endpoints during
+// the cutover.
+func (s *Server) updatePluginWorkload(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+
+	existing, err := s.store.GetWorkloadByID(id)
+	if err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "get workload")
+		return
+	}
+
+	var req pluginWorkloadRequest
+	if !decodeJSONStrict(w, r, &req) {
+		return
+	}
+	if err := validatePluginKinds(req); err != nil {
+		respondError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+
+	if req.Name != "" {
+		existing.Name = req.Name
+	}
+	existing.AppID = req.GroupID
+	existing.ParentWorkloadID = req.ParentWorkloadID
+	existing.SourceKind = req.SourceKind
+	if len(req.SourceConfig) > 0 {
+		existing.SourceConfig = string(req.SourceConfig)
+	}
+	existing.TriggerKind = req.TriggerKind
+	if len(req.TriggerConfig) > 0 {
+		existing.TriggerConfig = string(req.TriggerConfig)
+	}
+	if req.PublicFaces != nil {
+		b, _ := json.Marshal(req.PublicFaces)
+		existing.PublicFaces = string(b)
+	}
+	existing.NotificationURL = req.NotificationURL
+	existing.WebhookRequireSignature = req.WebhookRequireSignature
+
+	if err := s.store.UpdateWorkload(existing); err != nil {
+		slog.Error("update plugin workload", "error", err)
+		respondError(w, http.StatusInternalServerError, "update workload")
+		return
+	}
+	respondJSON(w, http.StatusOK, toPluginWorkload(existing))
+}
+
+// deployPluginWorkload handles POST /api/workloads/{id}/deploy.
+//
+// Builds a manual DeploymentIntent and dispatches it through the matching
+// Source plugin — independent of whatever TriggerKind the workload has
+// configured. The body is optional; supplying `reference` overrides what
+// the Source uses (e.g. force a specific image tag).
+func (s *Server) deployPluginWorkload(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+
+	row, err := s.store.GetWorkloadByID(id)
+	if err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "get workload")
+		return
+	}
+	if row.SourceKind == "" {
+		respondError(w, http.StatusBadRequest, "workload has no source_kind; cannot dispatch")
+		return
+	}
+
+	var body struct {
+		Reference string `json:"reference"`
+		Note      string `json:"note"`
+	}
+	if r.ContentLength > 0 {
+		if !decodeJSONStrict(w, r, &body) {
+			return
+		}
+	}
+
+	actor := "manual"
+	if claims, ok := auth.ClaimsFromContext(r.Context()); ok && claims.Username != "" {
+		actor = claims.Username
+	}
+	intent := plugin.DeploymentIntent{
+		Reason:      "manual",
+		Reference:   body.Reference,
+		Metadata:    map[string]string{"note": body.Note},
+		TriggeredAt: time.Now().UTC(),
+		TriggeredBy: actor,
+	}
+	if err := s.deployer.DispatchPlugin(r.Context(), toPluginWorkload(row), intent); err != nil {
+		// Full error stays in the server log; the client gets a generic
+		// message because the wrapped error can carry registry-auth bytes
+		// or compose-stdout secrets.
+		slog.Warn("manual dispatch failed", "workload", id, "actor", actor, "error", err)
+		respondError(w, http.StatusInternalServerError, "dispatch failed; see server logs")
+		return
+	}
+	respondJSON(w, http.StatusAccepted, map[string]any{
+		"workload_id":  id,
+		"reference":    intent.Reference,
+		"triggered_by": actor,
+	})
+}
+
+// deletePluginWorkload handles DELETE /api/workloads/{id}.
+//
+// Performs Source.Teardown first so containers / proxy routes / DNS are
+// cleaned up before the workload row is dropped. A teardown failure is
+// logged but does not block the row delete — the row must not outlive
+// the things it owns even when the cleanup is partial.
+func (s *Server) deletePluginWorkload(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+
+	row, err := s.store.GetWorkloadByID(id)
+	if err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "get workload")
+		return
+	}
+
+	if row.SourceKind != "" {
+		if err := s.deployer.DispatchTeardown(r.Context(), toPluginWorkload(row)); err != nil {
+			slog.Warn("delete workload: teardown error",
+				"workload", id, "kind", row.SourceKind, "error", err)
+		}
+	}
+
+	if err := s.store.DeleteWorkload(id); err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			respondNotFound(w, "workload")
+			return
+		}
+		respondError(w, http.StatusInternalServerError, "delete workload")
+		return
+	}
+	respondJSON(w, http.StatusOK, map[string]string{"deleted": id})
+}
+
+// validatePluginKinds verifies the requested source_kind and trigger_kind
+// resolve to registered plugins, then asks each plugin to validate its
+// own config blob. Empty kinds are allowed (legacy rows or partial setup).
+// Per-blob byte caps and the v1 single-face limit are enforced here so a
+// hand-crafted DB write can't bypass them later.
+func validatePluginKinds(req pluginWorkloadRequest) error {
+	if len(req.SourceConfig) > maxSourceConfigBytes {
+		return fmt.Errorf("source_config exceeds %d bytes", maxSourceConfigBytes)
+	}
+	if len(req.TriggerConfig) > maxTriggerConfigBytes {
+		return fmt.Errorf("trigger_config exceeds %d bytes", maxTriggerConfigBytes)
+	}
+	if len(req.PublicFaces) > maxPublicFaces {
+		return fmt.Errorf("at most %d public faces per workload", maxPublicFaces)
+	}
+	if req.SourceKind != "" {
+		src, err := plugin.GetSource(req.SourceKind)
+		if err != nil {
+			return err
+		}
+		if err := src.Validate(req.SourceConfig); err != nil {
+			return err
+		}
+	}
+	if req.TriggerKind != "" {
+		trg, err := plugin.GetTrigger(req.TriggerKind)
+		if err != nil {
+			return err
+		}
+		if err := trg.Validate(req.TriggerConfig); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+