Implemented shared S3 audio caching for prepare and restore --include-audio

internal/artifacts/paths.go

@@ -1,6 +1,8 @@
 package artifacts
 
 import (
+	"fmt"
+	"path"
 	"path/filepath"
 	"strings"
 
@@ -89,6 +91,44 @@ func SessionSpoolAudioDir(spoolRoot, campaign, sessionID, runID string) string {
 	return filepath.Join(spoolRoot, campaign, sessionID, runID, config.PathAudioDirSegment)
 }
 
+// SessionSpoolRestoreAudioDir returns the local spool audio path for restore downloads.
+func SessionSpoolRestoreAudioDir(spoolRoot, campaign, sessionID string) string {
+	return filepath.Join(spoolRoot, campaign, sessionID, "restore", config.PathAudioDirSegment)
+}
+
+// S3AudioCachePath returns the durable local cache path for one S3 audio object.
+func S3AudioCachePath(cacheRoot, bucket, key string) (string, error) {
+	root := filepath.Clean(strings.TrimSpace(cacheRoot))
+	if root == "." || root == "" {
+		return "", fmt.Errorf("cache root is required")
+	}
+	bucket = strings.Trim(strings.TrimSpace(bucket), "/")
+	if bucket == "" || bucket == "." || bucket == ".." || strings.Contains(bucket, "/") || strings.Contains(bucket, `\`) {
+		return "", fmt.Errorf("bucket is required and must be a single path segment")
+	}
+	rawKey := strings.ReplaceAll(strings.TrimSpace(key), `\`, "/")
+	if strings.HasPrefix(rawKey, "/") {
+		return "", fmt.Errorf("s3 key must not be absolute")
+	}
+	cleanKey := cleanCacheS3Key(rawKey)
+	if cleanKey == "" {
+		return "", fmt.Errorf("s3 key is required")
+	}
+	if cleanKey == ".." || strings.HasPrefix(cleanKey, "../") || strings.HasPrefix(cleanKey, "/") {
+		return "", fmt.Errorf("s3 key must not escape cache root")
+	}
+	return filepath.Join(root, "s3", bucket, filepath.FromSlash(cleanKey)), nil
+}
+
+func cleanCacheS3Key(key string) string {
+	normalized := strings.ReplaceAll(strings.TrimSpace(key), `\`, "/")
+	normalized = strings.Trim(normalized, "/")
+	if normalized == "" {
+		return ""
+	}
+	return path.Clean(normalized)
+}
+
 // SessionPreviousDir returns the previous-session state directory for already-resolved session paths.
 func SessionPreviousDir(paths SessionPaths) string {
 	return paths.PreviousDir

internal/artifacts/paths_model_test.go

@@ -114,3 +114,46 @@ func TestSessionSpoolAudioDir(t *testing.T) {
 		t.Fatalf("SessionSpoolAudioDir() = %q, want %q", got, want)
 	}
 }
+
+func TestSessionSpoolRestoreAudioDir(t *testing.T) {
+	root := "/var/spool/narratio"
+	got := SessionSpoolRestoreAudioDir(root, "forsaken", "2026-04-19")
+	want := filepath.Join(root, "forsaken", "2026-04-19", "restore", "audio")
+	if got != want {
+		t.Fatalf("SessionSpoolRestoreAudioDir() = %q, want %q", got, want)
+	}
+}
+
+func TestS3AudioCachePath(t *testing.T) {
+	got, err := S3AudioCachePath("/var/cache/narratio", "my-dnd-archive", "dnd/campaigns/forsaken/sessions/2026-04-19/audio/alice.flac")
+	if err != nil {
+		t.Fatalf("S3AudioCachePath() error = %v", err)
+	}
+	want := filepath.Join("/var/cache/narratio", "s3", "my-dnd-archive", "dnd", "campaigns", "forsaken", "sessions", "2026-04-19", "audio", "alice.flac")
+	if got != want {
+		t.Fatalf("S3AudioCachePath() = %q, want %q", got, want)
+	}
+}
+
+func TestS3AudioCachePathRejectsUnsafeInputs(t *testing.T) {
+	tests := []struct {
+		name   string
+		root   string
+		bucket string
+		key    string
+	}{
+		{name: "empty root", root: "", bucket: "bucket", key: "audio/a.flac"},
+		{name: "empty bucket", root: "/cache", bucket: "", key: "audio/a.flac"},
+		{name: "bucket slash", root: "/cache", bucket: "bad/bucket", key: "audio/a.flac"},
+		{name: "empty key", root: "/cache", bucket: "bucket", key: ""},
+		{name: "escaping key", root: "/cache", bucket: "bucket", key: "../audio/a.flac"},
+		{name: "absolute key", root: "/cache", bucket: "bucket", key: "/audio/a.flac"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got, err := S3AudioCachePath(tt.root, tt.bucket, tt.key); err == nil {
+				t.Fatalf("S3AudioCachePath() = %q, want error", got)
+			}
+		})
+	}
+}