Merge pull request #201 from synapseq-foundation/feature/custom-remote-validation

feat: support validated custom remote catalogs

Author: ruanklein

README.md

@@ -256,6 +256,19 @@ listing, searching, downloading, or generating a remote sequence:
 synapseq -sync
 ```
 
+To sync a self-hosted catalog, pass its base URL. Custom catalogs serve their
+index at `/index.json`, unlike the official catalog's `/free/index.json`:
+
+```bash
+synapseq -sync-url https://my-sequences.com
+```
+
+Set `SYNAPSEQ_REMOTE_BASE_URL` to use that catalog with `-list`, `-search`,
+`-info`, `-download`, and `-get` in later commands. Custom URLs must be a root
+HTTP(S) URL, without a path, credentials, query, or fragment. SynapSeq stores
+each custom catalog in its own cache directory and validates the catalog JSON
+and every downloaded SPSQ file before use.
+
 List all available sequences:
 
 ```bash

cmd/synapseq/dispatch.go

@@ -33,7 +33,7 @@ func dispatchSpecialCommand(opts *cli.CLIOptions, args []string) (bool, error) {
 		cli.ShowVersion()
 		return true, nil
 	case cli.SpecialCommandSync:
-		return true, remoteRunSync(opts.Quiet)
+		return true, remoteRunSync(opts.RemoteSyncURL, opts.Quiet)
 	case cli.SpecialCommandClean:
 		return true, remoteRunClean(opts.Quiet)
 	case cli.SpecialCommandGet:

cmd/synapseq/remote.go

@@ -21,11 +21,22 @@ import (
 const remoteIndexMissingError = "remote index not found. Please run 'synapseq -sync' to fetch the latest Remote index"
 
 // remoteRunSync updates the local Remote index.
-func remoteRunSync(quiet bool) error {
-	if err := remote.RemoteSync(); err != nil {
+func remoteRunSync(baseURL string, quiet bool) error {
+	var err error
+	if baseURL == "" {
+		err = remote.RemoteSync()
+	} else {
+		err = remote.RemoteSyncURL(baseURL)
+	}
+	if err != nil {
 		return fmt.Errorf("failed to sync remote. Error\n  %v", err)
 	}
-	index, err := loadRemoteIndex()
+	var index *t.RemoteIndex
+	if baseURL == "" {
+		index, err = loadRemoteIndex()
+	} else {
+		index, err = remote.GetIndexURL(baseURL)
+	}
 	if err != nil {
 		return fmt.Errorf("failed to get remote index. Error\n  %v", err)
 	}
@@ -180,6 +191,9 @@ func remoteRunInfo(sequenceID string) error {
 	if entry == nil {
 		return fmt.Errorf("sequence not found: %s", sequenceID)
 	}
+	if _, err := remote.RemoteDownload(entry); err != nil {
+		return fmt.Errorf("failed to download and validate sequence from remote. Error\n  %v", err)
+	}
 
 	printRemoteInfoSummary(entry)
 	fmt.Print(formatRemoteDescription(entry.Description))

cmd/synapseq/remote_integration_test.go

@@ -0,0 +1,83 @@
+// Copyright (C) 2026 SynapSeq Contributors
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"github.com/synapseq-foundation/synapseq/v4/internal/cli"
+	"github.com/synapseq-foundation/synapseq/v4/internal/remote"
+)
+
+const invalidRemoteSequenceIndex = `{
+  "version": "3.0.0",
+  "lastUpdated": "2026-05-13T22:30:42Z",
+  "entries": [{
+    "id": "calm-state",
+    "name": "Calm State",
+    "description": "A test sequence.",
+    "durationMinutes": 15,
+    "sequence": "free/relaxation/calm-state/calm-state.spsq",
+    "artwork": "free/relaxation/calm-state/calm-state.webp",
+    "category": "Relaxation",
+    "createdAt": "2026-03-21T00:00:00Z"
+  }]
+}`
+
+func TestRemoteCommandsRejectInvalidDownloadedSequence(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		switch request.URL.Path {
+		case "/index.json":
+			writer.Header().Set("Content-Type", "application/json")
+			_, _ = writer.Write([]byte(invalidRemoteSequenceIndex))
+		case "/free/relaxation/calm-state/calm-state.spsq":
+			_, _ = writer.Write([]byte("not valid SPSQ"))
+		default:
+			http.NotFound(writer, request)
+		}
+	}))
+	defer server.Close()
+
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("SYNAPSEQ_REMOTE_BASE_URL", server.URL)
+	if err := remote.RemoteSync(); err != nil {
+		t.Fatalf("RemoteSync error: %v", err)
+	}
+
+	tests := []struct {
+		name string
+		run  func() error
+	}{
+		{
+			name: "download",
+			run: func() error {
+				return remoteRunDownload("calm-state", t.TempDir(), true)
+			},
+		},
+		{
+			name: "get",
+			run: func() error {
+				return remoteRunGet("calm-state", filepath.Join(t.TempDir(), "calm-state.wav"), &cli.CLIOptions{Quiet: true, Test: true})
+			},
+		},
+		{
+			name: "info",
+			run: func() error {
+				return remoteRunInfo("calm-state")
+			},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if err := test.run(); err == nil {
+				t.Fatal("expected invalid downloaded SPSQ to be rejected")
+			}
+		})
+	}
+}

internal/cli/cli.go

@@ -54,6 +54,8 @@ type CLIOptions struct {
 	Play bool
 	// Remote sync index of available sequences
 	RemoteSync bool
+	// Remote sync index from a custom base URL
+	RemoteSyncURL string
 	// Remote clean up local cache
 	RemoteClean bool
 	// Remote list available sequences

internal/cli/cli_test.go

@@ -118,6 +118,12 @@ func TestParseFlags(ts *testing.T) {
 			expectedArgs: []string{},
 			expectError:  false,
 		},
+		{
+			args:         []string{"cmd", "-sync-url", "https://my-sequences.com"},
+			expected:     &CLIOptions{RemoteSyncURL: "https://my-sequences.com"},
+			expectedArgs: []string{},
+			expectError:  false,
+		},
 		{
 			args:         []string{"cmd", "-clean"},
 			expected:     &CLIOptions{RemoteClean: true},
@@ -251,6 +257,9 @@ func TestParseFlags(ts *testing.T) {
 		if opts.RemoteSync != test.expected.RemoteSync {
 			ts.Errorf("For args %v, RemoteSync: expected %v but got %v", test.args, test.expected.RemoteSync, opts.RemoteSync)
 		}
+		if opts.RemoteSyncURL != test.expected.RemoteSyncURL {
+			ts.Errorf("For args %v, RemoteSyncURL: expected %q but got %q", test.args, test.expected.RemoteSyncURL, opts.RemoteSyncURL)
+		}
 		if opts.RemoteClean != test.expected.RemoteClean {
 			ts.Errorf("For args %v, RemoteClean: expected %v but got %v", test.args, test.expected.RemoteClean, opts.RemoteClean)
 		}

internal/cli/flags.go

@@ -151,6 +151,7 @@ func flagBindings() []flagBinding {
 		{Name: "test", Usage: "Validate syntax without generating output", ValueKind: flagValueBool, BindBool: func(opts *CLIOptions) *bool { return &opts.Test }},
 		{Name: "help", Usage: "Show help", ValueKind: flagValueBool, BindBool: func(opts *CLIOptions) *bool { return &opts.ShowHelp }},
 		{Name: "sync", Usage: "Sync index of available sequences", ValueKind: flagValueBool, BindBool: func(opts *CLIOptions) *bool { return &opts.RemoteSync }, SpecialCommand: SpecialCommandSync},
+		{Name: "sync-url", Usage: "Sync index from a custom Remote base URL", ValueKind: flagValueString, BindString: func(opts *CLIOptions) *string { return &opts.RemoteSyncURL }, SpecialCommand: SpecialCommandSync},
 		{Name: "clean", Usage: "Clean up local cache", ValueKind: flagValueBool, BindBool: func(opts *CLIOptions) *bool { return &opts.RemoteClean }, SpecialCommand: SpecialCommandClean},
 		{Name: "get", Usage: "Get remote sequence", ValueKind: flagValueString, BindString: func(opts *CLIOptions) *string { return &opts.RemoteGet }, SpecialCommand: SpecialCommandGet},
 		{Name: "list", Usage: "List remote sequences", ValueKind: flagValueBool, BindBool: func(opts *CLIOptions) *bool { return &opts.RemoteList }, SpecialCommand: SpecialCommandList},

internal/cli/help.go

@@ -35,9 +35,7 @@ func Help() {
 	writeOutputSection(writer)
 	writeOptionsSection(writer, "Most common options:", commonHelpOptions())
 	writeAISection(writer)
-	writeMutedLeadSection(writer, "Remote:", "Run -sync first to initialize the local Remote index.")
-	writeOptionsList(writer, remoteHelpOptions())
-	fmt.Fprintln(writer)
+	writeRemoteSection(writer)
 	writeOptionsSection(writer, "Advanced:", advancedHelpOptions())
 
 	if runtime.GOOS == "windows" {
@@ -125,18 +123,24 @@ func writeIndentedOptionsList(writer io.Writer, indent string, options []helpOpt
 func writeAISection(writer io.Writer) {
 	fmt.Fprintf(writer, "%s\n", Section("AI:"))
 	fmt.Fprintf(writer, "  %s\n\n", Muted("Requires SYNAPSEQ_AI_API_KEY."))
-	writeAISubsection(writer, "Command:", aiCommandHelpOptions())
-	writeAISubsection(writer, "Options:", aiConfigurationHelpOptions())
-	writeAISubsection(writer, "Environment:", aiEnvironmentHelpOptions())
+	writeHelpSubsection(writer, "Command:", aiCommandHelpOptions())
+	writeHelpSubsection(writer, "Options:", aiConfigurationHelpOptions())
+	writeHelpSubsection(writer, "Environment:", aiEnvironmentHelpOptions())
 	fmt.Fprintf(writer, "  %s %s\n\n", Label("Priority:"), Muted("-ai-* option > SYNAPSEQ_AI_* environment variable > CLI default"))
 }
 
-func writeAISubsection(writer io.Writer, label string, options []helpOption) {
+func writeHelpSubsection(writer io.Writer, label string, options []helpOption) {
 	fmt.Fprintf(writer, "  %s\n", Label(label))
 	writeIndentedOptionsList(writer, "    ", options)
 	fmt.Fprintln(writer)
 }
 
+func writeRemoteSection(writer io.Writer) {
+	writeMutedLeadSection(writer, "Remote:", "Run -sync first to initialize the local Remote index.")
+	writeHelpSubsection(writer, "Commands:", remoteHelpOptions())
+	writeHelpSubsection(writer, "Environment:", remoteEnvironmentHelpOptions())
+}
+
 func quickStartExamples() []helpExample {
 	return []helpExample{
 		{Label: "1. Render audio", CommandText: "synapseq session.spsq", Description: "Generate session.wav in the current folder"},
@@ -192,6 +196,7 @@ func aiEnvironmentHelpOptions() []helpOption {
 func remoteHelpOptions() []helpOption {
 	return []helpOption{
 		{FlagText: "-sync", ColumnWidth: 28, Description: "Sync the local Remote index"},
+		{FlagText: "-sync-url URL", ColumnWidth: 28, Description: "Sync a custom Remote base URL"},
 		{FlagText: "-list", ColumnWidth: 28, Description: "List available remote sequences"},
 		{FlagText: "-search WORD", ColumnWidth: 28, Description: "Search remote sequences"},
 		{FlagText: "-info NAME", ColumnWidth: 28, Description: "Show information about a remote sequence"},
@@ -201,6 +206,12 @@ func remoteHelpOptions() []helpOption {
 	}
 }
 
+func remoteEnvironmentHelpOptions() []helpOption {
+	return []helpOption{
+		{FlagText: "SYNAPSEQ_REMOTE_BASE_URL", ColumnWidth: 28, Description: "Custom Remote base URL"},
+	}
+}
+
 func advancedHelpOptions() []helpOption {
 	return []helpOption{
 		{FlagText: "-ffmpeg-path PATH", ColumnWidth: 22, Description: "Path to ffmpeg executable"},

internal/remote/cache.go

@@ -12,6 +12,15 @@ import (
 
 // GetCacheDir returns the path to the cache directory for storing Remote data.
 func GetCacheDir() (string, error) {
+	source, err := defaultRemoteSource()
+	if err != nil {
+		return "", err
+	}
+
+	return getCacheDir(source)
+}
+
+func getCacheDir(source remoteSource) (string, error) {
 	var base string
 
 	switch runtime.GOOS {
@@ -30,6 +39,9 @@ func GetCacheDir() (string, error) {
 			base = filepath.Join(os.Getenv("HOME"), ".cache", "synapseq")
 		}
 	}
+	if source.custom {
+		base = filepath.Join(base, "custom", source.cacheKey)
+	}
 
 	if err := os.MkdirAll(base, 0755); err != nil {
 		return "", err

internal/remote/get.go

@@ -6,13 +6,12 @@ package remote
 
 import (
 	"fmt"
-	"strings"
+	"os"
 
+	"github.com/synapseq-foundation/synapseq/v4/internal/sequence"
 	t "github.com/synapseq-foundation/synapseq/v4/internal/types"
 )
 
-const remoteSequenceRootURL = "https://sequence.synapseq.org"
-
 // RemoteGet retrieves a sequence by its ID from the Remote index.
 func RemoteGet(sequenceID string) (*t.RemoteEntry, error) {
 	catalog, err := loadIndexCatalog()
@@ -44,10 +43,13 @@ func RemoteDownload(entry *t.RemoteEntry) (string, error) {
 		return "", err
 	}
 	if cached {
+		if err := validateCachedSequence(entryCache); err != nil {
+			return "", err
+		}
 		return entryCache.sequencePath(), nil
 	}
 
-	if err := downloadEntrySequence(entryCache, entry); err != nil {
+	if err := downloadEntrySequence(cache, entryCache, entry); err != nil {
 		return "", err
 	}
 
@@ -63,14 +65,31 @@ func prepareEntryDownload(cache *remoteCache, entry *t.RemoteEntry) (entryCache,
 	return entryCache, nil
 }
 
-func downloadEntrySequence(cache entryCache, entry *t.RemoteEntry) error {
-	if err := downloadFile(remoteSequenceURL(entry.Sequence), cache.sequencePath()); err != nil {
+func downloadEntrySequence(remoteCache *remoteCache, cache entryCache, entry *t.RemoteEntry) error {
+	data, _, err := downloadURL(remoteCache.source.sequenceURL(entry.Sequence))
+	if err != nil {
+		return fmt.Errorf("error downloading sequence %s: %v", entry.ID, err)
+	}
+	if err := validateRemoteSequence(data, cache.sequencePath(), cache.dir); err != nil {
+		return fmt.Errorf("invalid remote sequence %s: %w", entry.ID, err)
+	}
+	if err := os.WriteFile(cache.sequencePath(), data, 0644); err != nil {
 		return fmt.Errorf("error saving sequence %s: %v", entry.ID, err)
 	}
 
 	return nil
 }
 
-func remoteSequenceURL(sequencePath string) string {
-	return remoteSequenceRootURL + "/" + strings.TrimPrefix(sequencePath, "/")
+func validateCachedSequence(cache entryCache) error {
+	data, err := os.ReadFile(cache.sequencePath())
+	if err != nil {
+		return err
+	}
+
+	return validateRemoteSequence(data, cache.sequencePath(), cache.dir)
+}
+
+func validateRemoteSequence(data []byte, sourceFile, baseRef string) error {
+	_, err := sequence.LoadTextSequence(data, sourceFile, baseRef)
+	return err
 }