Provisioning: Move apifmt, loki and safepath to provisioning app (#110226)

* Move apifmt

* Move safepath

* Move Loki package

* Regenerate Loki mock

* Missing file for Loki

apps/provisioning/pkg/apifmt/error.go

@@ -0,0 +1,109 @@
+// apifmt aims to provide a Kubernetes-compatible way to format text.
+package apifmt
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+var (
+	_ error               = (*fmtError)(nil)
+	_ apierrors.APIStatus = (*fmtError)(nil)
+)
+
+type fmtError struct {
+	inner error
+	str   string
+
+	innerStatusErr     apierrors.APIStatus
+	initInnerStatusErr bool
+}
+
+func (e *fmtError) Error() string {
+	return e.str
+}
+
+// Status returns the status that is closest in the tree, in a depth-first search.
+func (e *fmtError) Status() metav1.Status {
+	if !e.initInnerStatusErr {
+		if status, ok := e.inner.(apierrors.APIStatus); ok || errors.As(e.inner, &status) {
+			e.innerStatusErr = status
+		}
+		e.initInnerStatusErr = true
+	}
+
+	status := metav1.Status{
+		Message: e.str,
+		Code:    http.StatusInternalServerError,
+		Reason:  metav1.StatusReasonInternalError,
+		Status:  metav1.StatusFailure,
+	}
+
+	if e.innerStatusErr != nil {
+		s := e.innerStatusErr.Status()
+		status.Code, status.Reason, status.Status, status.Details = s.Code, s.Reason, s.Status, s.Details
+	}
+	return status
+}
+
+func (e *fmtError) Unwrap() error {
+	return e.inner
+}
+
+func (e *fmtError) Is(target error) bool {
+	if e.initInnerStatusErr && e.innerStatusErr != nil {
+		// If we already know the inner status, we can speed up the Is check for apierrors Is functions. These are the most common case.
+		if err, ok := e.innerStatusErr.(error); ok {
+			return errors.Is(err, target)
+		}
+	}
+	return errors.Is(e.inner, target)
+}
+
+// Errorf acts like `fmt.Errorf`. Use `%w` to wrap a specific error.
+// The returned error will propagate the inner `metav1.Status`, if one exists. Otherwise, an HTTP 500 Internal Server Error will be returned.
+// If multiple errors are passed, they will be joined with `errors.Join`, just like `fmt.Errorf`.
+func Errorf(format string, args ...any) *fmtError {
+	// We go via Errorf to only give the %w errors as inner errors.
+	wrapped := fmt.Errorf(format, args...)
+	str := wrapped.Error()
+	err := unwrap(wrapped)
+
+	return &fmtError{
+		inner: err,
+		str:   str,
+	}
+}
+
+// unwrap returns the inner error of an error, if it exists.
+// If multiple errors are present, it will errors.Join them.
+func unwrap(err error) error {
+	type singleUnwrapper interface {
+		Unwrap() error
+	}
+	type multiUnwrapper interface {
+		Unwrap() []error
+	}
+
+	if err == nil {
+		return nil
+	}
+	if e, ok := err.(singleUnwrapper); ok {
+		return e.Unwrap()
+	}
+	if e, ok := err.(multiUnwrapper); ok {
+		errs := e.Unwrap()
+		if len(errs) == 0 {
+			return err
+		}
+		if len(errs) == 1 && errs[0] != nil {
+			return errs[0]
+		}
+		return errors.Join(errs...)
+	}
+	return err
+}

apps/provisioning/pkg/apifmt/error_test.go

@@ -0,0 +1,97 @@
+package apifmt_test
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"testing"
+
+	"github.com/grafana/grafana/apps/provisioning/pkg/apifmt"
+	"github.com/stretchr/testify/assert"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+func TestErrorf(t *testing.T) {
+	t.Parallel()
+
+	for _, fmt := range []string{"1 %v 2 %v", "1 %w 2 %v", "1 %v 2 %w", "1 %w 2 %w"} {
+		t.Run("error string is formatted appropriately with fmt="+fmt, func(t *testing.T) {
+			t.Parallel()
+
+			err1 := errors.New("error1")
+			err2 := errors.New("error2")
+
+			err := apifmt.Errorf(fmt, err1, err2)
+			assert.Equal(t, "1 error1 2 error2", err.Error())
+		})
+	}
+
+	t.Run("no inner error defaults to internal server error", func(t *testing.T) {
+		t.Parallel()
+
+		err := apifmt.Errorf("nothing inside")
+
+		assert.True(t, apierrors.IsInternalError(err), "err is not internal error per apierrors")
+		assert.Equal(t, int32(http.StatusInternalServerError), err.Status().Code, ".Code")
+		assert.Equal(t, metav1.StatusReasonInternalError, err.Status().Reason, ".Reason")
+		assert.Equal(t, metav1.StatusFailure, err.Status().Status, ".Status")
+	})
+
+	t.Run("non-apistatus inner error defaults to internal server error", func(t *testing.T) {
+		t.Parallel()
+
+		inner := errors.New("an inner error")
+		err := apifmt.Errorf("%w", inner)
+
+		assert.True(t, apierrors.IsInternalError(err), "err is not internal error per apierrors")
+		assert.Equal(t, int32(http.StatusInternalServerError), err.Status().Code, ".Code")
+		assert.Equal(t, metav1.StatusReasonInternalError, err.Status().Reason, ".Reason")
+		assert.Equal(t, metav1.StatusFailure, err.Status().Status, ".Status")
+	})
+
+	t.Run("apistatus inner error is used for status", func(t *testing.T) {
+		t.Parallel()
+
+		inner := apierrors.NewBadRequest("bad request")
+		err := apifmt.Errorf("%w", inner)
+
+		assert.Equal(t, inner.Status(), err.Status(), "err.Status()")
+	})
+
+	t.Run("message is used with inner apistatus error", func(t *testing.T) {
+		t.Parallel()
+
+		inner := apierrors.NewBadRequest("bad request")
+		err := apifmt.Errorf("context here: %w", inner)
+
+		status := inner.Status()
+		status.Message = "context here: bad request"
+		assert.Equal(t, status, err.Status(), "err.Status()")
+		assert.Equal(t, "context here: bad request", err.Error(), "err.Error()")
+	})
+
+	t.Run("deep apierror is used", func(t *testing.T) {
+		t.Parallel()
+
+		inner := apierrors.NewBadRequest("bad request")
+		wrapped := fmt.Errorf("%w", inner)
+		wrapped = fmt.Errorf("%w", wrapped)
+		err := apifmt.Errorf("%w", wrapped)
+
+		assert.Equal(t, inner.Status(), err.Status(), "err.Status()")
+	})
+
+	t.Run("deep error in multi-unwrap wrapper's apierror is used", func(t *testing.T) {
+		t.Parallel()
+
+		inner := apierrors.NewBadRequest("bad request")
+		anotherError := errors.New("not an apierror")
+		wrapped := errors.Join(fmt.Errorf("this is cool: %w", anotherError), fmt.Errorf("another one: %w", errors.Join(anotherError, inner, anotherError)))
+		err := apifmt.Errorf("%w", wrapped)
+
+		status := inner.Status()
+		status.Message = "this is cool: not an apierror\nanother one: not an apierror\nbad request\nnot an apierror"
+		assert.Equal(t, status, err.Status(), "err.Status()")
+	})
+}

apps/provisioning/pkg/loki/client.go

@@ -0,0 +1,185 @@
+package loki
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+	"time"
+
+	"github.com/grafana/grafana-app-sdk/logging"
+)
+
+type Config struct {
+	ReadPathURL       *url.URL
+	WritePathURL      *url.URL
+	BasicAuthUser     string
+	BasicAuthPassword string
+	TenantID          string
+	ExternalLabels    map[string]string
+	MaxQuerySize      int
+}
+
+type Stream struct {
+	Stream map[string]string `json:"stream"`
+	Values []Sample          `json:"values"`
+}
+
+type Sample struct {
+	T time.Time
+	V string
+}
+
+func (r Sample) MarshalJSON() ([]byte, error) {
+	return json.Marshal([2]string{
+		fmt.Sprintf("%d", r.T.UnixNano()), r.V,
+	})
+}
+
+func (r *Sample) UnmarshalJSON(b []byte) error {
+	var tuple [2]string
+	if err := json.Unmarshal(b, &tuple); err != nil {
+		return fmt.Errorf("failed to deserialize sample in Loki response: %w", err)
+	}
+	nano, err := strconv.ParseInt(tuple[0], 10, 64)
+	if err != nil {
+		return fmt.Errorf("timestamp in Loki sample not convertible to nanosecond epoch: %v", tuple[0])
+	}
+	r.T = time.Unix(0, nano)
+	r.V = tuple[1]
+	return nil
+}
+
+type QueryRes struct {
+	Data QueryData `json:"data"`
+}
+
+type QueryData struct {
+	Result []Stream `json:"result"`
+}
+
+type PushRequest struct {
+	Streams []Stream `json:"streams"`
+}
+
+type Client struct {
+	cfg    Config
+	client *http.Client
+}
+
+func NewClient(cfg Config) *Client {
+	return &Client{
+		cfg:    cfg,
+		client: &http.Client{Timeout: 30 * time.Second},
+	}
+}
+
+func (c *Client) Push(ctx context.Context, streams []Stream) error {
+	log := logging.FromContext(ctx)
+
+	pushReq := PushRequest{Streams: streams}
+	body, err := json.Marshal(pushReq)
+	if err != nil {
+		return fmt.Errorf("failed to marshal push request: %w", err)
+	}
+
+	uri := c.cfg.WritePathURL.JoinPath("/loki/api/v1/push")
+	req, err := http.NewRequest(http.MethodPost, uri.String(), bytes.NewBuffer(body))
+	if err != nil {
+		return fmt.Errorf("failed to create Loki request: %w", err)
+	}
+
+	c.setAuthAndTenantHeaders(req)
+	req.Header.Set("Content-Type", "application/json")
+
+	req = req.WithContext(ctx)
+	res, err := c.client.Do(req)
+	if res != nil {
+		defer func() {
+			if err := res.Body.Close(); err != nil {
+				log.Warn("Failed to close response body", "err", err)
+			}
+		}()
+	}
+	if err != nil {
+		return fmt.Errorf("error sending request: %w", err)
+	}
+
+	if res.StatusCode < 200 || res.StatusCode >= 300 {
+		body, _ := io.ReadAll(res.Body)
+		log.Error("Error response from Loki", "response", string(body), "status", res.StatusCode)
+		return fmt.Errorf("received a non-200 response from loki, status: %d", res.StatusCode)
+	}
+
+	log.Debug("Successfully pushed streams to Loki", "status", res.StatusCode, "streams", len(streams))
+	return nil
+}
+
+func (c *Client) RangeQuery(ctx context.Context, logQL string, start, end, limit int64) (QueryRes, error) {
+	log := logging.FromContext(ctx)
+
+	uri := c.cfg.ReadPathURL.JoinPath("/loki/api/v1/query_range")
+	req, err := http.NewRequest(http.MethodGet, uri.String(), nil)
+	if err != nil {
+		return QueryRes{}, fmt.Errorf("error creating request: %w", err)
+	}
+
+	q := req.URL.Query()
+	q.Set("query", logQL)
+	q.Set("start", strconv.FormatInt(start, 10))
+	q.Set("end", strconv.FormatInt(end, 10))
+	if limit > 0 {
+		q.Set("limit", strconv.FormatInt(limit, 10))
+	}
+	req.URL.RawQuery = q.Encode()
+
+	c.setAuthAndTenantHeaders(req)
+	req = req.WithContext(ctx)
+
+	res, err := c.client.Do(req)
+	if res != nil {
+		defer func() {
+			if err := res.Body.Close(); err != nil {
+				log.Warn("Failed to close response body", "err", err)
+			}
+		}()
+	}
+	if err != nil {
+		return QueryRes{}, fmt.Errorf("error sending request: %w", err)
+	}
+
+	body, err := io.ReadAll(res.Body)
+	if err != nil {
+		return QueryRes{}, fmt.Errorf("error reading request response: %w", err)
+	}
+
+	if res.StatusCode < 200 || res.StatusCode >= 300 {
+		if len(body) > 0 {
+			log.Error("Error response from Loki", "response", string(body), "status", res.StatusCode)
+		} else {
+			log.Error("Error response from Loki with an empty body", "status", res.StatusCode)
+		}
+		return QueryRes{}, fmt.Errorf("received a non-200 response from loki, status: %d", res.StatusCode)
+	}
+
+	var queryRes QueryRes
+	if err := json.Unmarshal(body, &queryRes); err != nil {
+		return QueryRes{}, fmt.Errorf("error unmarshaling loki response: %w", err)
+	}
+
+	log.Debug("Successfully queried Loki", "status", res.StatusCode, "streams", len(queryRes.Data.Result))
+	return queryRes, nil
+}
+
+func (c *Client) setAuthAndTenantHeaders(req *http.Request) {
+	if c.cfg.BasicAuthUser != "" || c.cfg.BasicAuthPassword != "" {
+		req.SetBasicAuth(c.cfg.BasicAuthUser, c.cfg.BasicAuthPassword)
+	}
+	if c.cfg.TenantID != "" {
+		req.Header.Set("X-Scope-OrgID", c.cfg.TenantID)
+	}
+}

apps/provisioning/pkg/loki/client_test.go

@@ -0,0 +1,314 @@
+package loki
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSample_MarshalJSON(t *testing.T) {
+	sample := Sample{
+		T: time.Unix(0, 1234567890000000000), // 1234567890 seconds in nanoseconds
+		V: "test log line",
+	}
+
+	data, err := json.Marshal(sample)
+	require.NoError(t, err)
+
+	expected := `["1234567890000000000","test log line"]`
+	assert.JSONEq(t, expected, string(data))
+}
+
+func TestSample_UnmarshalJSON(t *testing.T) {
+	t.Run("valid sample", func(t *testing.T) {
+		data := `["1234567890000000000","test log line"]`
+		var sample Sample
+
+		err := json.Unmarshal([]byte(data), &sample)
+		require.NoError(t, err)
+
+		assert.Equal(t, time.Unix(0, 1234567890000000000), sample.T)
+		assert.Equal(t, "test log line", sample.V)
+	})
+
+	t.Run("invalid format", func(t *testing.T) {
+		data := `"invalid"`
+		var sample Sample
+
+		err := json.Unmarshal([]byte(data), &sample)
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "failed to deserialize sample")
+	})
+
+	t.Run("invalid timestamp", func(t *testing.T) {
+		data := `["not-a-number","test log line"]`
+		var sample Sample
+
+		err := json.Unmarshal([]byte(data), &sample)
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "timestamp in Loki sample not convertible")
+	})
+}
+
+func TestClient_Push(t *testing.T) {
+	t.Run("successful push", func(t *testing.T) {
+		var receivedBody PushRequest
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "/loki/api/v1/push", r.URL.Path)
+			assert.Equal(t, http.MethodPost, r.Method)
+			assert.Equal(t, "application/json", r.Header.Get("Content-Type"))
+
+			err := json.NewDecoder(r.Body).Decode(&receivedBody)
+			require.NoError(t, err)
+
+			w.WriteHeader(http.StatusOK)
+		}))
+		defer server.Close()
+
+		client := createTestClient(t, server.URL, server.URL)
+
+		streams := []Stream{
+			{
+				Stream: map[string]string{"job": "test"},
+				Values: []Sample{
+					{T: time.Unix(0, 1234567890000000000), V: "log line 1"},
+					{T: time.Unix(0, 1234567891000000000), V: "log line 2"},
+				},
+			},
+		}
+
+		err := client.Push(context.Background(), streams)
+		assert.NoError(t, err)
+
+		// Verify the request body
+		assert.Len(t, receivedBody.Streams, 1)
+		assert.Equal(t, "test", receivedBody.Streams[0].Stream["job"])
+		assert.Len(t, receivedBody.Streams[0].Values, 2)
+	})
+
+	t.Run("push failure", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusBadRequest)
+			_, _ = w.Write([]byte("Bad request"))
+		}))
+		defer server.Close()
+
+		client := createTestClient(t, server.URL, server.URL)
+
+		streams := []Stream{{Stream: map[string]string{"job": "test"}}}
+		err := client.Push(context.Background(), streams)
+
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "non-200 response")
+	})
+}
+
+func TestClient_RangeQuery(t *testing.T) {
+	t.Run("successful query", func(t *testing.T) {
+		expectedResponse := QueryRes{
+			Data: QueryData{
+				Result: []Stream{
+					{
+						Stream: map[string]string{"job": "test"},
+						Values: []Sample{
+							{T: time.Unix(0, 1234567890000000000), V: "log line 1"},
+							{T: time.Unix(0, 1234567891000000000), V: "log line 2"},
+						},
+					},
+				},
+			},
+		}
+
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			assert.Equal(t, "/loki/api/v1/query_range", r.URL.Path)
+			assert.Equal(t, http.MethodGet, r.Method)
+
+			// Check query parameters
+			params := r.URL.Query()
+			assert.Equal(t, `{job="test"}`, params.Get("query"))
+			assert.Equal(t, "1000000000", params.Get("start"))
+			assert.Equal(t, "2000000000", params.Get("end"))
+			assert.Equal(t, "100", params.Get("limit"))
+
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(expectedResponse)
+		}))
+		defer server.Close()
+
+		client := createTestClient(t, server.URL, server.URL)
+
+		result, err := client.RangeQuery(
+			context.Background(),
+			`{job="test"}`,
+			1000000000, // start
+			2000000000, // end
+			100,        // limit
+		)
+
+		assert.NoError(t, err)
+		assert.Len(t, result.Data.Result, 1)
+		assert.Equal(t, "test", result.Data.Result[0].Stream["job"])
+		assert.Len(t, result.Data.Result[0].Values, 2)
+	})
+
+	t.Run("query without limit", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			params := r.URL.Query()
+			assert.Equal(t, "", params.Get("limit")) // Should not be set
+
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(QueryRes{})
+		}))
+		defer server.Close()
+
+		client := createTestClient(t, server.URL, server.URL)
+
+		_, err := client.RangeQuery(context.Background(), `{job="test"}`, 1000000000, 2000000000, 0)
+		assert.NoError(t, err)
+	})
+
+	t.Run("query failure", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusBadRequest)
+			_, _ = w.Write([]byte("Bad query"))
+		}))
+		defer server.Close()
+
+		client := createTestClient(t, server.URL, server.URL)
+
+		_, err := client.RangeQuery(context.Background(), `{job="test"}`, 1000000000, 2000000000, 100)
+
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "non-200 response")
+	})
+
+	t.Run("invalid JSON response", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte("invalid json"))
+		}))
+		defer server.Close()
+
+		client := createTestClient(t, server.URL, server.URL)
+
+		_, err := client.RangeQuery(context.Background(), `{job="test"}`, 1000000000, 2000000000, 100)
+
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "error unmarshaling loki response")
+	})
+}
+
+func TestClient_setAuthAndTenantHeaders(t *testing.T) {
+	t.Run("with basic auth and tenant", func(t *testing.T) {
+		cfg := createTestConfig(t, "http://localhost", "http://localhost")
+		cfg.BasicAuthUser = "testuser"
+		cfg.BasicAuthPassword = "testpass"
+		cfg.TenantID = "test-tenant"
+
+		client := NewClient(cfg)
+
+		req, _ := http.NewRequest(http.MethodGet, "http://localhost", nil)
+		client.setAuthAndTenantHeaders(req)
+
+		username, password, ok := req.BasicAuth()
+		assert.True(t, ok)
+		assert.Equal(t, "testuser", username)
+		assert.Equal(t, "testpass", password)
+		assert.Equal(t, "test-tenant", req.Header.Get("X-Scope-OrgID"))
+	})
+
+	t.Run("without auth", func(t *testing.T) {
+		cfg := createTestConfig(t, "http://localhost", "http://localhost")
+		client := NewClient(cfg)
+
+		req, _ := http.NewRequest(http.MethodGet, "http://localhost", nil)
+		client.setAuthAndTenantHeaders(req)
+
+		_, _, ok := req.BasicAuth()
+		assert.False(t, ok)
+		assert.Equal(t, "", req.Header.Get("X-Scope-OrgID"))
+	})
+}
+
+func TestStream_JSONRoundtrip(t *testing.T) {
+	original := Stream{
+		Stream: map[string]string{
+			"job":       "test-job",
+			"instance":  "test-instance",
+			"namespace": "test-ns",
+		},
+		Values: []Sample{
+			{T: time.Unix(0, 1234567890000000000), V: "log line 1"},
+			{T: time.Unix(0, 1234567891000000000), V: "log line 2"},
+			{T: time.Unix(0, 1234567892000000000), V: "log line 3"},
+		},
+	}
+
+	// Marshal to JSON
+	data, err := json.Marshal(original)
+	require.NoError(t, err)
+
+	// Unmarshal back
+	var restored Stream
+	err = json.Unmarshal(data, &restored)
+	require.NoError(t, err)
+
+	// Verify all fields match
+	assert.Equal(t, original.Stream, restored.Stream)
+	assert.Len(t, restored.Values, len(original.Values))
+
+	for i, sample := range original.Values {
+		assert.True(t, sample.T.Equal(restored.Values[i].T),
+			fmt.Sprintf("Timestamp mismatch at index %d: expected %v, got %v", i, sample.T, restored.Values[i].T))
+		assert.Equal(t, sample.V, restored.Values[i].V)
+	}
+}
+
+// Helper functions
+
+func createTestClient(t *testing.T, readURL, writeURL string) *Client {
+	cfg := createTestConfig(t, readURL, writeURL)
+	return NewClient(cfg)
+}
+
+func createTestConfig(t *testing.T, readURL, writeURL string) Config {
+	readParsed, err := url.Parse(readURL)
+	require.NoError(t, err)
+
+	writeParsed, err := url.Parse(writeURL)
+	require.NoError(t, err)
+
+	return Config{
+		ReadPathURL:    readParsed,
+		WritePathURL:   writeParsed,
+		ExternalLabels: map[string]string{"source": "test"},
+		MaxQuerySize:   1000,
+	}
+}
+
+func TestClient_ContextCancellation(t *testing.T) {
+	t.Run("push with cancelled context", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			t.Error("Handler should not be called with cancelled context")
+		}))
+		defer server.Close()
+
+		client := createTestClient(t, server.URL, server.URL)
+
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+
+		streams := []Stream{{Stream: map[string]string{"job": "test"}}}
+		err := client.Push(ctx, streams)
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "context canceled")
+	})
+}

apps/provisioning/pkg/safepath/dir.go

@@ -0,0 +1,65 @@
+package safepath
+
+import (
+	"fmt"
+	"path"
+	"strings"
+)
+
+// IsDir returns true if the filePath ends with a slash.
+// Empty string is considered a directory.
+func IsDir(filePath string) bool {
+	if filePath == "" || filePath == "." {
+		return true
+	}
+
+	return strings.HasSuffix(filePath, "/")
+}
+
+// Dir behaves exactly as path.Dir, but returns "" for the root directory.
+// and returns a trailing slash for all other directories.
+func Dir(filePath string) string {
+	if filePath == "" {
+		return ""
+	}
+
+	// Trim trailing slash before getting the directory
+	cleanPath := strings.TrimSuffix(filePath, "/")
+	dir := path.Dir(cleanPath)
+	if dir == "." || dir == "/" {
+		return ""
+	}
+
+	return dir + "/"
+}
+
+// InDir returns true if the filePath is a subdirectory of the given directory.
+func InDir(filePath, dir string) bool {
+	return strings.HasPrefix(filePath, dir)
+}
+
+// RelativeTo returns the relative path of the filePath to the given directory.
+// It handles cases where either filePath or dir have leading or trailing slashes.
+func RelativeTo(filePath, dir string) (string, error) {
+	if dir == "/" || dir == "" {
+		return filePath, nil
+	}
+
+	// Normalize paths by trimming leading and trailing slashes
+	normalizedDir := strings.Trim(dir, "/")
+	if normalizedDir != "" {
+		normalizedDir += "/"
+	}
+
+	normalizedPath := strings.TrimPrefix(filePath, "/")
+
+	// Check if the normalized path is in the normalized directory
+	if !strings.HasPrefix(normalizedPath, normalizedDir) {
+		return "", fmt.Errorf("filePath is not a subdirectory of dir")
+	}
+
+	// Get the relative path by trimming the directory prefix
+	relativePath := strings.TrimPrefix(normalizedPath, normalizedDir)
+
+	return relativePath, nil
+}

apps/provisioning/pkg/safepath/dir_test.go

@@ -0,0 +1,260 @@
+package safepath
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestIsFolderPath(t *testing.T) {
+	tests := []struct {
+		name     string
+		filePath string
+		want     bool
+	}{
+		{
+			name:     "empty path",
+			filePath: "",
+			want:     true,
+		},
+		{
+			name:     "dot path",
+			filePath: ".",
+			want:     true,
+		},
+		{
+			name:     "file path without extension",
+			filePath: "test",
+			want:     false,
+		},
+		{
+			name:     "file path with extension",
+			filePath: "test.json",
+			want:     false,
+		},
+		{
+			name:     "folder path with trailing slash",
+			filePath: "folder/",
+			want:     true,
+		},
+		{
+			name:     "nested folder path with trailing slash",
+			filePath: "folder/subfolder/",
+			want:     true,
+		},
+		{
+			name:     "file path in folder without trailing slash",
+			filePath: "folder/test.json",
+			want:     false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := IsDir(tt.filePath)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestDir(t *testing.T) {
+	tests := []struct {
+		name     string
+		filePath string
+		want     string
+	}{
+		{
+			name:     "empty path",
+			filePath: "",
+			want:     "",
+		},
+		{
+			name:     "root path",
+			filePath: "/",
+			want:     "",
+		},
+		{
+			name:     "single directory",
+			filePath: "folder",
+			want:     "",
+		},
+		{
+			name:     "nested directory",
+			filePath: "folder/subfolder",
+			want:     "folder/",
+		},
+		{
+			name:     "file in directory",
+			filePath: "folder/file.txt",
+			want:     "folder/",
+		},
+		{
+			name:     "multiple nested directories",
+			filePath: "folder/subfolder/subsubfolder",
+			want:     "folder/subfolder/",
+		},
+		{
+			name:     "directory with trailing slash",
+			filePath: "folder/subfolder/",
+			want:     "folder/",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := Dir(tt.filePath)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestInDir(t *testing.T) {
+	tests := []struct {
+		name     string
+		filePath string
+		dir      string
+		want     bool
+	}{
+		{
+			name:     "file in directory",
+			filePath: "folder/file.txt",
+			dir:      "folder/",
+			want:     true,
+		},
+		{
+			name:     "file not in directory",
+			filePath: "other/file.txt",
+			dir:      "folder/",
+			want:     false,
+		},
+		{
+			name:     "subdirectory",
+			filePath: "folder/subfolder/",
+			dir:      "folder/",
+			want:     true,
+		},
+		{
+			name:     "empty directory",
+			filePath: "folder/file.txt",
+			dir:      "",
+			want:     true,
+		},
+		{
+			name:     "exact match",
+			filePath: "folder/",
+			dir:      "folder/",
+			want:     true,
+		},
+		{
+			name:     "partial directory name match",
+			filePath: "folder2/file.txt",
+			dir:      "folder/",
+			want:     false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := InDir(tt.filePath, tt.dir)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestRelativeTo(t *testing.T) {
+	tests := []struct {
+		name        string
+		filePath    string
+		dir         string
+		want        string
+		expectError bool
+	}{
+		{
+			name:     "simple relative path",
+			filePath: "folder/subfolder/file.txt",
+			dir:      "folder",
+			want:     "subfolder/file.txt",
+		},
+		{
+			name:     "relative path with leading slash",
+			filePath: "/prefix/folder/subfolder/file.txt",
+			dir:      "/prefix/folder",
+			want:     "subfolder/file.txt",
+		},
+		{
+			name:     "relative path with leading slash in dir but in filePath",
+			filePath: "prefix/folder/subfolder/file.txt",
+			dir:      "/prefix/folder",
+			want:     "subfolder/file.txt",
+		},
+		{
+			name:     "with trailing slash in dir",
+			filePath: "folder/subfolder/file.txt",
+			dir:      "folder/",
+			want:     "subfolder/file.txt",
+		},
+		{
+			name:     "with trailing slash in both",
+			filePath: "folder/subfolder/",
+			dir:      "folder/",
+			want:     "subfolder/",
+		},
+		{
+			name:     "empty directory",
+			filePath: "file.txt",
+			dir:      "",
+			want:     "file.txt",
+		},
+		{
+			name:     "directory is root",
+			filePath: "folder/file.txt",
+			dir:      "/",
+			want:     "folder/file.txt",
+		},
+		{
+			name:     "nested directories",
+			filePath: "a/b/c/d/file.txt",
+			dir:      "a/b",
+			want:     "c/d/file.txt",
+		},
+		{
+			name:        "file not in directory",
+			filePath:    "other/file.txt",
+			dir:         "folder",
+			want:        "",
+			expectError: true,
+		},
+		{
+			name:        "file path shorter than directory",
+			filePath:    "file.txt",
+			dir:         "folder/subfolder",
+			want:        "",
+			expectError: true,
+		},
+		{
+			name:     "same directory",
+			filePath: "folder/file.txt",
+			dir:      "folder",
+			want:     "file.txt",
+		},
+		{
+			name:        "directory with similar prefix",
+			filePath:    "folder2/file.txt",
+			dir:         "folder",
+			want:        "",
+			expectError: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := RelativeTo(tt.filePath, tt.dir)
+			if tt.expectError {
+				require.Error(t, err)
+			} else {
+				require.NoError(t, err)
+				require.Equal(t, tt.want, got)
+			}
+		})
+	}
+}

apps/provisioning/pkg/safepath/path.go

@@ -0,0 +1,79 @@
+package safepath
+
+import (
+	"os"
+	"path"
+	"strings"
+)
+
+// TODO: explore if we want to use our own type for safepath
+// to make it clearer that this is a safe path and not a regular path
+
+// osSeparator is declared as a var here only to ensure we can change it in tests.
+var osSeparator = os.PathSeparator
+
+// Performs a [path.Clean] on the path, as well as replacing its OS separators.
+//
+// This replaces the OS separator with a slash.
+// All OSes we target (Linux, macOS, and Windows) support forward-slashes in path traversals, as such it's simpler to use the same character everywhere.
+// BSDs do as well (even though they're not a target as of writing).
+//
+// The output of a root path (i.e. absolute root or relative current dir) is always "" (empty string).
+func Clean(p string) string {
+	if osSeparator != '/' {
+		p = strings.ReplaceAll(p, string(osSeparator), "/")
+	}
+
+	cleaned := path.Clean(p)
+	if cleaned == "." || cleaned == "/" {
+		return ""
+	}
+	return cleaned
+}
+
+// Join is like path.Join but preserves trailing slashes from the last element
+func Join(elem ...string) string {
+	if len(elem) == 0 {
+		return ""
+	}
+
+	joined := path.Join(elem...)
+	// Preserve trailing slash if the last element had one
+	if strings.HasSuffix(elem[len(elem)-1], "/") {
+		return joined + "/"
+	}
+
+	return joined
+}
+
+// Base returns the last element of the path.
+func Base(p string) string {
+	b := path.Base(p)
+	if b == "." || b == "/" {
+		return ""
+	}
+
+	return b
+}
+
+// RemoveExt returns the path without the extension.
+// It should not remove the dot if the filename is e.g. `.gitignore`
+func RemoveExt(p string) string {
+	// Special case: if the file starts with a dot and has no other dots,
+	// it's a hidden file and should not have its "extension" removed
+	base := Base(p)
+	if strings.HasPrefix(base, ".") && strings.Count(base, ".") == 1 {
+		return p
+	}
+
+	ext := path.Ext(p)
+	if ext == "" {
+		return p
+	}
+
+	return p[0 : len(p)-len(ext)]
+}
+
+func IsAbs(p string) bool {
+	return path.IsAbs(p)
+}

apps/provisioning/pkg/safepath/path_test.go

@@ -0,0 +1,171 @@
+package safepath
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestPathJoin(t *testing.T) {
+	testCases := []struct {
+		Comment string
+		In      []string
+		Out     any // string or error
+	}{
+		{"Empty elements should not change input", []string{"/test/"}, "/test/"},
+		{"Empty elements without leading slash should not change input", []string{"test/"}, "test/"},
+		{"Single element should be added to path", []string{"/test/", "abc"}, "/test/abc"},
+		{"Single element should be added to path with current dir prefix", []string{"./test/", "abc"}, "test/abc"},
+		{"Single element with leading slash should be added to path", []string{"/test/", "/abc"}, "/test/abc"},
+		{"Many elements are all appended to path", []string{"/test/", "a", "b", "c"}, "/test/a/b/c"},
+		{"Path traversal within same directory should be expanded", []string{"/test/", "a", "..", "b", ".", "..", "c"}, "/test/c"},
+		{"Complex path traversal remaining in prefix should be expanded", []string{"/test/", "a/..///c/", "../../test/d/"}, "/test/d/"},
+	}
+
+	for _, tc := range testCases {
+		tc := tc
+		t.Run(tc.Comment, func(t *testing.T) {
+			path := Join(tc.In...)
+			if str, ok := tc.Out.(string); ok {
+				assert.Equal(t, str, path)
+			} else {
+				panic("expected out was neither string nor error")
+			}
+		})
+	}
+}
+
+func TestPathClean(t *testing.T) {
+	orig := osSeparator
+	osSeparator = '\\' // pretend we're on Windows
+	defer func() { osSeparator = orig }()
+
+	testCases := []struct {
+		Comment string
+		In      string
+		Out     string
+	}{
+		{"Simple path", "/test/", "/test"},
+		{"Simple path with OS separators", "\\test\\here", "/test/here"},
+		{"Simple path with mixed separators", "\\test/here", "/test/here"},
+		{"Path traversal within directory", "/test/abc/../def", "/test/def"},
+		{"Multiple path traversals", "/test/abc/../../def", "/def"},
+		{"Path traversal beyond root", "/test/../../../def", "/def"},
+		{"Complex path traversal with mixed separators", "\\test\\abc\\..\\..\\def/ghi\\..", "/def"},
+		{"Path traversal with multiple slashes", "/test////abc/..//def", "/test/def"},
+		{"Path traversal with current directory", "/test/./abc/../def/./ghi", "/test/def/ghi"},
+		{"Empty path segments with traversal", "//test//abc//..//def", "/test/def"},
+		{"Root path returns empty string", "/", ""},
+		{"Current directory returns empty string", ".", ""},
+		{"Path traversal to root returns empty string", "/test/..", ""},
+	}
+
+	for _, tc := range testCases {
+		tc := tc
+		t.Run(tc.Comment, func(t *testing.T) {
+			assert.Equal(t, tc.Out, Clean(tc.In))
+		})
+	}
+}
+
+func TestBase(t *testing.T) {
+	testCases := []struct {
+		name     string
+		path     string
+		expected string
+	}{
+		{
+			name:     "empty path",
+			path:     "",
+			expected: "",
+		},
+		{
+			name:     "root path",
+			path:     "/",
+			expected: "",
+		},
+		{
+			name:     "current directory",
+			path:     ".",
+			expected: "",
+		},
+		{
+			name:     "simple filename",
+			path:     "file.txt",
+			expected: "file.txt",
+		},
+		{
+			name:     "path with directory",
+			path:     "/path/to/file.txt",
+			expected: "file.txt",
+		},
+		{
+			name:     "path with trailing slash",
+			path:     "/path/to/dir/",
+			expected: "dir",
+		},
+		{
+			name:     "hidden file",
+			path:     ".gitignore",
+			expected: ".gitignore",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			result := Base(tc.path)
+			assert.Equal(t, tc.expected, result)
+		})
+	}
+}
+
+func TestRemoveExt(t *testing.T) {
+	testCases := []struct {
+		name     string
+		path     string
+		expected string
+	}{
+		{
+			name:     "empty path",
+			path:     "",
+			expected: "",
+		},
+		{
+			name:     "no extension",
+			path:     "filename",
+			expected: "filename",
+		},
+		{
+			name:     "simple extension",
+			path:     "file.txt",
+			expected: "file",
+		},
+		{
+			name:     "multiple dots",
+			path:     "file.tar.gz",
+			expected: "file.tar",
+		},
+		{
+			name:     "hidden file",
+			path:     ".gitignore",
+			expected: ".gitignore",
+		},
+		{
+			name:     "path with directory",
+			path:     "/path/to/file.txt",
+			expected: "/path/to/file",
+		},
+		{
+			name:     "path with trailing slash",
+			path:     "/path/to/dir/",
+			expected: "/path/to/dir/",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			result := RemoveExt(tc.path)
+			assert.Equal(t, tc.expected, result)
+		})
+	}
+}

apps/provisioning/pkg/safepath/safe.go

@@ -0,0 +1,116 @@
+package safepath
+
+import (
+	"errors"
+	"regexp"
+	"strings"
+)
+
+var (
+	ErrPathTooLong          = errors.New("path too long")
+	ErrInvalidCharacters    = errors.New("path contains invalid characters")
+	ErrDoubleSlash          = errors.New("path contains double slashes")
+	ErrInvalidFormat        = errors.New("invalid path format")
+	ErrPercentChar          = errors.New("path contains percent character which could be used for URL encoding attacks")
+	ErrHiddenPath           = errors.New("path contains hidden file or directory (starting with dot)")
+	ErrPathTraversalAttempt = errors.New("path contains traversal attempt (./ or ../)")
+)
+
+const (
+	MaxPathLength = 1024 // Maximum allowed path length in characters
+)
+
+// validPathPattern matches valid path characters:
+// - Alphanumeric (a-z, A-Z, 0-9)
+// - Forward slash for path separation
+// - Dots for file extensions and current directory
+// - Underscores and hyphens for file/folder names
+var validPathPattern = regexp.MustCompile(`^[a-zA-Z0-9 /_.-]+$`)
+
+func IsSafe(path string) error {
+	// Check path length
+	if len(path) > MaxPathLength {
+		return ErrPathTooLong
+	}
+
+	// Empty path is valid (represents current directory)
+	if path == "" {
+		return nil
+	}
+
+	// Check specifically for percent character first
+	if strings.Contains(path, "%") {
+		return ErrPercentChar
+	}
+
+	// Check for invalid characters
+	if !validPathPattern.MatchString(path) {
+		return ErrInvalidCharacters
+	}
+
+	// Check for double slashes
+	if strings.Contains(path, "//") {
+		return ErrDoubleSlash
+	}
+
+	parts := Split(path)
+	for _, part := range parts {
+		// Check for path traversal attempts first
+		if part == ".." || part == "." {
+			return ErrPathTraversalAttempt
+		}
+
+		// Check for hidden files/directories in any part of the path
+		if part == "" || strings.HasPrefix(part, ".") {
+			return ErrHiddenPath
+		}
+	}
+
+	// If it's not a directory, it should have a filename component
+	if !IsDir(path) && len(parts) > 0 {
+		filename := parts[len(parts)-1]
+		if filename == "" {
+			return ErrInvalidFormat
+		}
+	}
+
+	return nil
+}
+
+// SafeSegment returns a safe part of the path
+// It ensures the path is free from traversal attempts, hidden files,
+// and other potentially dangerous patterns.
+func SafeSegment(path string) string {
+	if path == "" {
+		return ""
+	}
+
+	parts := Split(path)
+	if len(parts) == 0 {
+		return ""
+	}
+
+	// Build up the path segment by segment, checking safety
+	var safePath string
+	for _, part := range parts {
+		// Check if this segment is safe
+		testPath := Join(safePath, part)
+		if IsSafe(testPath) != nil || part == "" {
+			// If this segment is unsafe, return the path up to but not including this segment
+			// Add trailing slash for directories
+			if safePath != "" {
+				return safePath + "/"
+			}
+			return ""
+		}
+		safePath = testPath
+	}
+
+	// If we made it through all segments, the path is safe
+	// Preserve trailing slash if original path had one
+	if IsDir(path) && safePath != "" {
+		return safePath + "/"
+	}
+
+	return safePath
+}

apps/provisioning/pkg/safepath/safe_test.go

@@ -0,0 +1,303 @@
+package safepath
+
+import (
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestIsSafe(t *testing.T) {
+	tests := []struct {
+		name    string
+		path    string
+		wantErr error
+	}{
+		// Valid paths
+		{
+			name:    "valid simple path",
+			path:    "path/to/resource",
+			wantErr: nil,
+		},
+		{
+			name:    "character space",
+			path:    "path/to/my file.json",
+			wantErr: nil,
+		},
+		{
+			name:    "valid path with extension",
+			path:    "path/to/file.json",
+			wantErr: nil,
+		},
+		{
+			name:    "valid directory path with trailing slash",
+			path:    "path/to/folder/",
+			wantErr: nil,
+		},
+		{
+			name:    "valid path with allowed special chars",
+			path:    "my-path/to_file/resource.json",
+			wantErr: nil,
+		},
+		{
+			name:    "empty path",
+			path:    "",
+			wantErr: nil,
+		},
+		{
+			name:    "path at max length",
+			path:    strings.Repeat("a", MaxPathLength),
+			wantErr: nil,
+		},
+		{
+			name:    "valid directory",
+			path:    "path/to/",
+			wantErr: nil,
+		},
+		{
+			name:    "valid path with dots in filename",
+			path:    "path/to/file.min.js",
+			wantErr: nil,
+		},
+		// Length and depth limits
+		{
+			name:    "path too long",
+			path:    strings.Repeat("a/", 512) + "file", // Creates path > MaxPathLength
+			wantErr: ErrPathTooLong,
+		},
+		// Invalid characters and formats
+		{
+			name:    "invalid special character hash",
+			path:    "path/to/file#.json",
+			wantErr: ErrInvalidCharacters,
+		},
+		{
+			name:    "invalid character backslash",
+			path:    "path\\to\\file.json",
+			wantErr: ErrInvalidCharacters,
+		},
+		{
+			name:    "invalid character question mark",
+			path:    "path/to/file?.json",
+			wantErr: ErrInvalidCharacters,
+		},
+		{
+			name:    "invalid character asterisk",
+			path:    "path/to/*.json",
+			wantErr: ErrInvalidCharacters,
+		},
+
+		// Double slashes
+		{
+			name:    "double slashes in middle",
+			path:    "path//to/file.json",
+			wantErr: ErrDoubleSlash,
+		},
+		{
+			name:    "double slashes at start",
+			path:    "//path/to/file.json",
+			wantErr: ErrDoubleSlash,
+		},
+		{
+			name:    "double slashes at end",
+			path:    "path/to/file//",
+			wantErr: ErrDoubleSlash,
+		},
+
+		// Hidden files and directories
+		{
+			name:    "hidden file",
+			path:    "path/to/.hidden",
+			wantErr: ErrHiddenPath,
+		},
+		{
+			name:    "hidden directory",
+			path:    "path/to/.git/",
+			wantErr: ErrHiddenPath,
+		},
+		{
+			name:    "hidden file with extension",
+			path:    "path/to/.gitignore",
+			wantErr: ErrHiddenPath,
+		},
+		{
+			name:    "hidden path component in middle",
+			path:    "path/.hidden/file.json",
+			wantErr: ErrHiddenPath,
+		},
+		{
+			name:    "hidden path at root",
+			path:    ".env/config.json",
+			wantErr: ErrHiddenPath,
+		},
+
+		// Path traversal attempts
+		{
+			name:    "path traversal with parent directory",
+			path:    "path/to/../file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "path traversal at start",
+			path:    "../path/file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "path traversal with multiple levels",
+			path:    "path/../../file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "path traversal at end",
+			path:    "path/to/folder/../",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "single dot path component",
+			path:    "path/to/./file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "double dot path component",
+			path:    "path/to/../",
+			wantErr: ErrPathTraversalAttempt,
+		},
+
+		// Current directory references
+		{
+			name:    "current directory at start",
+			path:    "./path/file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "current directory in middle",
+			path:    "path/./file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "current directory at end",
+			path:    "path/to/./",
+			wantErr: ErrPathTraversalAttempt,
+		},
+
+		// URL encoding attempts
+		{
+			name:    "percent character in filename",
+			path:    "path/to/%20file.json",
+			wantErr: ErrPercentChar,
+		},
+		{
+			name:    "url encoded slash",
+			path:    "path/to%2Ffile.json",
+			wantErr: ErrPercentChar,
+		},
+		{
+			name:    "url encoded dot",
+			path:    "path/to%2E%2E/file.json",
+			wantErr: ErrPercentChar,
+		},
+		{
+			name:    "url encoded path traversal",
+			path:    "path/to/%2e%2e/file.json",
+			wantErr: ErrPercentChar,
+		},
+		{
+			name:    "url encoded null byte",
+			path:    "path/to/file%00.json",
+			wantErr: ErrPercentChar,
+		},
+
+		// Mixed invalid patterns
+		{
+			name:    "mixed traversal attempts",
+			path:    "./path/../file.json",
+			wantErr: ErrPathTraversalAttempt,
+		},
+		{
+			name:    "mixed special chars and traversal",
+			path:    "../path/#/file.json",
+			wantErr: ErrInvalidCharacters,
+		},
+		{
+			name:    "mixed percent and special chars",
+			path:    "path/%20/#/file.json",
+			wantErr: ErrPercentChar,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := IsSafe(tt.path)
+			if !errors.Is(err, tt.wantErr) {
+				t.Errorf("IsSafe() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestSafeSegment(t *testing.T) {
+	tests := []struct {
+		name     string
+		path     string
+		wantPath string
+	}{
+		{
+			name:     "empty path",
+			path:     "",
+			wantPath: "",
+		},
+		{
+			name:     "simple valid path",
+			path:     "path/to/file.txt",
+			wantPath: "path/to/file.txt",
+		},
+		{
+			name:     "path with valid special characters",
+			path:     "my-path/some_file/test.json",
+			wantPath: "my-path/some_file/test.json",
+		},
+		{
+			name:     "path with trailing slash",
+			path:     "path/to/folder/",
+			wantPath: "path/to/folder/",
+		},
+		{
+			name:     "path with multiple extensions",
+			path:     "path/to/file.min.js",
+			wantPath: "path/to/file.min.js",
+		},
+		{
+			name:     "path with invalid characters",
+			path:     "path/to/file#.txt",
+			wantPath: "path/to/",
+		},
+		{
+			name:     "path with traversal attempt",
+			path:     "path/../file.txt",
+			wantPath: "path/",
+		},
+		{
+			name:     "path with hidden file",
+			path:     "path/to/.hidden",
+			wantPath: "path/to/",
+		},
+		{
+			name:     "path with percent character",
+			path:     "path/to/%20file.txt",
+			wantPath: "path/to/",
+		},
+		{
+			name:     "path with double slashes",
+			path:     "path//to/file.txt",
+			wantPath: "path/",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotPath := SafeSegment(tt.path)
+			if gotPath != tt.wantPath {
+				t.Errorf("SafeSegment() = %v, want %v", gotPath, tt.wantPath)
+			}
+		})
+	}
+}

apps/provisioning/pkg/safepath/trie.go

@@ -0,0 +1,98 @@
+// Package safepath provides utilities for safe path handling and validation
+// through a trie-based implementation.
+package safepath
+
+import (
+	"fmt"
+)
+
+// trieNode represents a single node in the trie data structure.
+type trieNode struct {
+	children map[string]*trieNode
+	isDir    bool // marks if this node represents a directory
+}
+
+// Trie implements a trie data structure for efficient path lookups and validation.
+type Trie struct {
+	root *trieNode
+}
+
+// NewTrie creates and returns a new initialized Trie.
+func NewTrie() *Trie {
+	return &Trie{
+		root: &trieNode{
+			children: make(map[string]*trieNode),
+		},
+	}
+}
+
+// Add inserts a path into the trie. It returns an error if there's a conflict
+// between the path types (file vs directory) or if the path is invalid.
+func (t *Trie) Add(path string) error {
+	if path == "" || path == "/" {
+		return nil
+	}
+
+	current := t.root
+	segments := Split(path)
+
+	var accumulatedPath string
+	for i, segment := range segments {
+		accumulatedPath = Join(accumulatedPath, segment)
+		if current.children == nil {
+			current.children = make(map[string]*trieNode)
+		}
+
+		isLastSegment := i == len(segments)-1
+		node, exists := current.children[segment]
+		if !exists {
+			node = &trieNode{
+				children: make(map[string]*trieNode),
+			}
+			current.children[segment] = node
+		} else {
+			if (!isLastSegment && !node.isDir) || (isLastSegment && !node.isDir && IsDir(path)) {
+				return fmt.Errorf("path %q exists but is not a directory", accumulatedPath)
+			}
+
+			if isLastSegment && node.isDir && !IsDir(path) {
+				return fmt.Errorf("path %q exists but is not a file", accumulatedPath)
+			}
+		}
+
+		current = node
+		current.isDir = !isLastSegment || IsDir(path)
+	}
+
+	return nil
+}
+
+// Exists checks if a path exists in the trie and matches its expected type (file/directory).
+func (t *Trie) Exists(path string) bool {
+	if path == "" || path == "/" {
+		return true
+	}
+
+	current := t.root
+	segments := Split(path)
+
+	for i, segment := range segments {
+		if current.children == nil {
+			return false
+		}
+
+		next, exists := current.children[segment]
+		if !exists {
+			return false
+		}
+
+		current = next
+		isLastSegment := i == len(segments)-1
+
+		if isLastSegment {
+			return current.isDir == IsDir(path)
+		}
+	}
+
+	return false
+}

apps/provisioning/pkg/safepath/trie_test.go

@@ -0,0 +1,125 @@
+package safepath
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestTrie(t *testing.T) {
+	tests := []struct {
+		name          string
+		pathsToAdd    []string
+		pathsToCheck  []string
+		expectedExist []bool
+		expectedError error
+	}{
+		{
+			name:          "empty trie",
+			pathsToAdd:    []string{},
+			pathsToCheck:  []string{"test", "test/"},
+			expectedExist: []bool{false, false},
+			expectedError: nil,
+		},
+		{
+			name:          "single file",
+			pathsToAdd:    []string{"test.json"},
+			pathsToCheck:  []string{"test.json", "test.json/"},
+			expectedExist: []bool{true, false},
+			expectedError: nil,
+		},
+		{
+			name:          "single directory",
+			pathsToAdd:    []string{"test/"},
+			pathsToCheck:  []string{"test", "test/"},
+			expectedExist: []bool{false, true},
+			expectedError: nil,
+		},
+		{
+			name:          "nested structure",
+			pathsToAdd:    []string{"folder/", "folder/file.txt", "folder/subfolder/", "folder/subfolder/test.json"},
+			pathsToCheck:  []string{"folder/", "folder/file.txt", "folder/file.txt/", "folder/subfolder/", "folder/subfolder/test.json", "folder/subfolder/test.json/"},
+			expectedExist: []bool{true, true, false, true, true, false},
+			expectedError: nil,
+		},
+		{
+			name:          "partial paths",
+			pathsToAdd:    []string{"a/b/c/d/"},
+			pathsToCheck:  []string{"a/", "a/b/", "a/b/c/", "a/b/c/d/"},
+			expectedExist: []bool{true, true, true, true},
+			expectedError: nil,
+		},
+		{
+			name:          "file in middle of path",
+			pathsToAdd:    []string{"a/file.txt", "a/file.txt/b/"},
+			pathsToCheck:  []string{},
+			expectedExist: []bool{},
+			expectedError: fmt.Errorf("path %q exists but is not a directory", "a/file.txt"),
+		},
+		{
+			name:          "empty path",
+			pathsToAdd:    []string{""},
+			pathsToCheck:  []string{""},
+			expectedExist: []bool{true},
+			expectedError: nil,
+		},
+		{
+			name:          "root directory",
+			pathsToAdd:    []string{"/"},
+			pathsToCheck:  []string{"/", ""},
+			expectedExist: []bool{true, true},
+			expectedError: nil,
+		},
+		{
+			name:          "duplicate paths",
+			pathsToAdd:    []string{"test/", "test/"},
+			pathsToCheck:  []string{"test/"},
+			expectedExist: []bool{true},
+			expectedError: nil,
+		},
+		{
+			name:          "file to directory conversion not allowed",
+			pathsToAdd:    []string{"test.txt", "test.txt/file.txt"},
+			pathsToCheck:  []string{},
+			expectedExist: []bool{},
+			expectedError: fmt.Errorf("path %q exists but is not a directory", "test.txt"),
+		},
+		{
+			name:          "directory to file conversion not allowed",
+			pathsToAdd:    []string{"test/", "test"},
+			pathsToCheck:  []string{},
+			expectedExist: []bool{},
+			expectedError: fmt.Errorf("path %q exists but is not a file", "test"),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			trie := NewTrie()
+
+			// Add paths
+			var lastErr error
+			for _, path := range tt.pathsToAdd {
+				err := trie.Add(path)
+				if err != nil {
+					lastErr = err
+					break
+				}
+			}
+
+			if tt.expectedError != nil {
+				require.Error(t, lastErr)
+				require.Equal(t, tt.expectedError.Error(), lastErr.Error())
+				return
+			}
+			require.NoError(t, lastErr)
+
+			// Check existence
+			for i, path := range tt.pathsToCheck {
+				exists := trie.Exists(path)
+				require.Equal(t, tt.expectedExist[i], exists, "path: %s", path)
+			}
+		})
+	}
+}

apps/provisioning/pkg/safepath/walk.go

@@ -0,0 +1,65 @@
+package safepath
+
+import (
+	"context"
+	"path"
+	"sort"
+	"strings"
+)
+
+type WalkFunc = func(ctx context.Context, path string) error
+
+// Walk walks the given folder path and calls the given function for each folder.
+func Walk(ctx context.Context, p string, fn WalkFunc) error {
+	if p == "." || p == "/" {
+		return nil
+	}
+
+	var currentPath string
+	for _, folder := range strings.Split(p, "/") {
+		if folder == "" {
+			// Trailing / leading slash?
+			continue
+		}
+
+		currentPath = path.Join(currentPath, folder)
+		if err := fn(ctx, currentPath); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// Depth returns the depth of the given path.
+func Depth(p string) int {
+	return len(Split(p))
+}
+
+// Split splits the given path into segments.
+func Split(p string) []string {
+	trimmed := strings.Trim(p, "/")
+	if trimmed == "" {
+		return []string{}
+	}
+	return strings.Split(trimmed, "/")
+}
+
+// SortByDepth will sort any resource, by its path depth. You must pass in
+// a way to get said path. Ties are alphabetical by default.
+func SortByDepth[T any](items []T, pathExtractor func(T) string, asc bool) {
+	sort.Slice(items, func(i, j int) bool {
+		pathI, pathJ := pathExtractor(items[i]), pathExtractor(items[j])
+		depthI, depthJ := Depth(pathI), Depth(pathJ)
+
+		if depthI == depthJ {
+			// alphabetical by default if depth is the same
+			return pathI < pathJ
+		}
+
+		if asc {
+			return depthI < depthJ
+		}
+		return depthI > depthJ
+	})
+}

apps/provisioning/pkg/safepath/walk_test.go

@@ -0,0 +1,231 @@
+package safepath
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestWalk(t *testing.T) {
+	tests := []struct {
+		name          string
+		path          string
+		expectedPaths []string
+		expectError   bool
+	}{
+		{
+			name: "simple path",
+			path: "a/b/c",
+			expectedPaths: []string{
+				"a",
+				"a/b",
+				"a/b/c",
+			},
+		},
+		{
+			name: "path with leading slash",
+			path: "/a/b/c",
+			expectedPaths: []string{
+				"a",
+				"a/b",
+				"a/b/c",
+			},
+		},
+		{
+			name: "path with trailing slash",
+			path: "a/b/c/",
+			expectedPaths: []string{
+				"a",
+				"a/b",
+				"a/b/c",
+			},
+		},
+		{
+			name:          "root path",
+			path:          "/",
+			expectedPaths: nil,
+		},
+		{
+			name:          "current directory",
+			path:          ".",
+			expectedPaths: nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var paths []string
+			err := Walk(context.Background(), tt.path, func(ctx context.Context, p string) error {
+				paths = append(paths, p)
+				return nil
+			})
+
+			if tt.expectError {
+				require.Error(t, err)
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, tt.expectedPaths, paths)
+			}
+		})
+	}
+}
+
+func TestDepth(t *testing.T) {
+	tests := []struct {
+		name          string
+		path          string
+		expectedDepth int
+	}{
+		{
+			name:          "empty path",
+			path:          "",
+			expectedDepth: 0,
+		},
+		{
+			name:          "root path",
+			path:          "/",
+			expectedDepth: 0,
+		},
+		{
+			name:          "single level",
+			path:          "a",
+			expectedDepth: 1,
+		},
+		{
+			name:          "multiple levels",
+			path:          "a/b/c",
+			expectedDepth: 3,
+		},
+		{
+			name:          "path with leading slash",
+			path:          "/a/b/c",
+			expectedDepth: 3,
+		},
+		{
+			name:          "path with trailing slash",
+			path:          "a/b/c/",
+			expectedDepth: 3,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			depth := Depth(tt.path)
+			assert.Equal(t, tt.expectedDepth, depth)
+		})
+	}
+}
+
+func TestSplit(t *testing.T) {
+	tests := []struct {
+		name             string
+		path             string
+		expectedSegments []string
+	}{
+		{
+			name:             "empty path",
+			path:             "",
+			expectedSegments: []string{},
+		},
+		{
+			name:             "root path",
+			path:             "/",
+			expectedSegments: []string{},
+		},
+		{
+			name:             "single segment",
+			path:             "a",
+			expectedSegments: []string{"a"},
+		},
+		{
+			name:             "multiple segments",
+			path:             "a/b/c",
+			expectedSegments: []string{"a", "b", "c"},
+		},
+		{
+			name:             "path with leading slash",
+			path:             "/a/b/c",
+			expectedSegments: []string{"a", "b", "c"},
+		},
+		{
+			name:             "path with trailing slash",
+			path:             "a/b/c/",
+			expectedSegments: []string{"a", "b", "c"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			segments := Split(tt.path)
+			assert.Equal(t, tt.expectedSegments, segments)
+		})
+	}
+}
+
+func TestWalkError(t *testing.T) {
+	expectedErr := errors.New("test error")
+	err := Walk(context.Background(), "a/b/c", func(ctx context.Context, p string) error {
+		if p == "a/b" {
+			return expectedErr
+		}
+		return nil
+	})
+
+	require.ErrorIs(t, err, expectedErr)
+}
+
+func TestSortByDepth(t *testing.T) {
+	tests := []struct {
+		name     string
+		asc      bool
+		paths    []string
+		expected []string
+	}{
+		{
+			name:     "ascending sort (shallowest first)",
+			paths:    []string{"a/b/c", "a", "a/b", "d/e/f/g"},
+			asc:      true,
+			expected: []string{"a", "a/b", "a/b/c", "d/e/f/g"},
+		},
+		{
+			name:     "descending sort with alphabetical tie-break",
+			paths:    []string{"a/b/c", "a", "a/b", "d/e/f/g", "x/y/z"},
+			asc:      false,
+			expected: []string{"d/e/f/g", "a/b/c", "x/y/z", "a/b", "a"},
+		},
+		{
+			name:     "paths with empty string",
+			paths:    []string{"a/b/c", "", "a", "a/b"},
+			asc:      true,
+			expected: []string{"", "a", "a/b", "a/b/c"},
+		},
+		{
+			name:     "paths with trailing slashes",
+			paths:    []string{"a/b/", "a/b/c", "b/", "a/", "a"},
+			asc:      true,
+			expected: []string{"a", "a/", "b/", "a/b/", "a/b/c"},
+		},
+		{
+			name:     "single path",
+			paths:    []string{"a/b/c"},
+			expected: []string{"a/b/c"},
+		},
+		{
+			name:     "empty paths",
+			paths:    []string{},
+			expected: []string{},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			paths := make([]string, len(tt.paths))
+			copy(paths, tt.paths)
+			SortByDepth(paths, func(s string) string { return s }, tt.asc)
+			assert.Equal(t, tt.expected, paths)
+		})
+	}
+}