refactor(db): migrate all ids to a uniform canonical 128-bit base62 encoding (#5824)

* refactor(model): extract canonical 128-bit base62 id codec

* feat(model): generate random ids as canonical 128-bit base62 values

* feat(scanner): emit legacy PIDs in canonical base62 encoding

* feat(db): add id canonicalization transform for the uniform-ids migration

* feat(db): migrate all ids to canonical 128-bit base62 encoding

* fix(db): canonicalize ids in junction tables and JSON columns

* chore(jellyfin): update id-family notes for uniform canonical ids

* test(ids): harden codec input contract and migration edge coverage

* refactor(model): use log.Fatal for Encode128 contract guard per project convention

* fix(db): force full rescan after id migration for legacy PID configs

* test(db): guard id-column inventory against schema drift

* refactor(ids): compile-time Encode128 contract and unified column rewrite helper

* refactor(db): apply review feedback to id migration

Filter empty strings in collectColumn's SQL, reuse a prepared statement
for rewriteColumn updates, and clarify the legacy ID functions' comment
now that they emit the canonical encoding.

* feat(auth): split session and public-link JWT secrets, rotating sessions on id migration

* test(subsonic): initialize public token secret in helpers suite

The suite sets auth.TokenAuth directly instead of calling auth.Init, so the
new PublicTokenAuth was nil whenever Ginkgo's spec order ran a helpers spec
before any spec that calls auth.Init, panicking in publicurl.ImageURL.

* refactor(db): inline canonicalID into its only consumer, the uniform-ids migration

* refactor(model): rename Encode128/Decode128 to Encode/Decode

With every id now exactly 128 bits, the width suffix is redundant; the
package-qualified id.Encode/id.Decode carries the same information.

* test(db): make the id-columns guard classify JSON columns too

The guard only inspected columns named id/pid/*_id, so it could not see ids
embedded in JSON. Widen it to *_ids and to every JSON column, and drive the
"covered" set from a new embeddedIDColumns list instead of the inline calls
in the migration.

Every JSON column the schema has now carries a verdict. The four denormalized
caches -- media_file/album.participants, media_file/album.tags,
album.folder_ids and artist.similar_artists -- hold only artist, tag and
folder ids. Those all come from id.NewHash, whose 22-char base62 encoding of
a 128-bit MD5 is already in canonical range, so canonicalID is the identity
on them and the migration correctly leaves them alone. A new codec test pins
that invariant, since the exemptions depend on it.

Verified on a copy of a 727MB/96k-track production database: canonicalizing
those four columns changed zero rows, and artist, tag and folder ids were
themselves unchanged by the migration (only media_file ids moved, 95108 of
96666).

model/id/id.go

@@ -2,20 +2,36 @@ package id
 
 import (
 	"crypto/md5"
+	"crypto/rand"
 	"fmt"
 	"math/big"
 	"strings"
-
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/utils/nanoid"
 )
 
 func NewRandom() string {
-	id, err := nanoid.Generate("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz", 22)
-	if err != nil {
-		log.Error("Could not generate new ID", err)
+	var b [16]byte
+	_, _ = rand.Read(b[:])
+	return Encode(b)
+}
+
+// Encode renders a 16-byte value as the canonical 22-char zero-padded base62 id.
+func Encode(b [16]byte) string {
+	return fmt.Sprintf("%022s", new(big.Int).SetBytes(b[:]).Text(62))
+}
+
+// Decode is the exact inverse of Encode.
+func Decode(s string) ([]byte, error) {
+	if len(s) != 22 {
+		return nil, fmt.Errorf("invalid id length %d", len(s))
 	}
-	return id
+	v, ok := new(big.Int).SetString(s, 62)
+	if !ok || v.Sign() < 0 {
+		return nil, fmt.Errorf("invalid base62 id %q", s)
+	}
+	if v.BitLen() > 128 {
+		return nil, fmt.Errorf("id %q overflows 128 bits", s)
+	}
+	return v.FillBytes(make([]byte, 16)), nil
 }
 
 func NewHash(data ...string) string {
@@ -24,11 +40,7 @@ func NewHash(data ...string) string {
 		hash.Write([]byte(d))
 		hash.Write([]byte(string('\u200b')))
 	}
-	h := hash.Sum(nil)
-	bi := big.NewInt(0)
-	bi.SetBytes(h)
-	s := bi.Text(62)
-	return fmt.Sprintf("%022s", s)
+	return Encode([16]byte(hash.Sum(nil)))
 }
 
 func NewTagID(name, value string) string {

model/id/id_suite_test.go

@@ -0,0 +1,17 @@
+package id_test
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestID(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "ID Suite")
+}

model/id/id_test.go

@@ -0,0 +1,64 @@
+package id_test
+
+import (
+	"github.com/navidrome/navidrome/model/id"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Encode/Decode", func() {
+	It("encodes 16 bytes as 22-char zero-padded base62", func() {
+		Expect(id.Encode([16]byte{})).To(Equal("0000000000000000000000"))
+		allFF := [16]byte{0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
+			0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff}
+		Expect(id.Encode(allFF)).To(Equal("7N42dgm5tFLK9N8MT7fHC7"))
+	})
+
+	It("round-trips arbitrary 16-byte values", func() {
+		b := [16]byte{0xe3, 0xb7, 0xfc, 0x2a, 0xe9, 0x44, 0x7b, 0xbe,
+			0xc3, 0x7a, 0x13, 0xbf, 0x91, 0x6e, 0x3c, 0xf6}
+		s := id.Encode(b)
+		Expect(s).To(Equal("6VHl3uR4kss6sUPKA8Cwnk"))
+		Expect(id.Decode(s)).To(Equal(b[:]))
+	})
+
+	It("rejects invalid input", func() {
+		_, err := id.Decode("short")
+		Expect(err).To(HaveOccurred())
+		_, err = id.Decode("!!!!!!!!!!!!!!!!!!!!!!") // 22 chars, not base62
+		Expect(err).To(HaveOccurred())
+		_, err = id.Decode("-000000000000000000001") // sign is not part of the alphabet
+		Expect(err).To(HaveOccurred())
+		_, err = id.Decode("zzzzzzzzzzzzzzzzzzzzzz") // > 2^128
+		Expect(err).To(HaveOccurred())
+	})
+})
+
+var _ = Describe("NewRandom", func() {
+	It("emits 22-char canonical ids that always fit 128 bits", func() {
+		seen := make(map[string]struct{})
+		for range 1000 {
+			s := id.NewRandom()
+			Expect(s).To(HaveLen(22))
+			_, err := id.Decode(s)
+			Expect(err).ToNot(HaveOccurred(), "id %q must decode to 128 bits", s)
+			seen[s] = struct{}{}
+		}
+		Expect(seen).To(HaveLen(1000))
+	})
+})
+
+var _ = Describe("NewHash", func() {
+	It("keeps its historical output byte-for-byte (golden)", func() {
+		Expect(id.NewHash("test")).To(Equal("5cLJPkLA5DK2BADhoeotPk"))
+		Expect(id.NewHash("[unknown artist]")).To(Equal("7lsE5pS09fPS1VuFqwXbia"))
+		Expect(id.NewTagID("genre", "electronic")).To(Equal("7bLYq0Np81m1Wgy5N31nuG"))
+	})
+
+	It("always emits 22 decodable chars", func() {
+		h := id.NewHash("anything", "at", "all")
+		Expect(h).To(HaveLen(22))
+		_, err := id.Decode(h)
+		Expect(err).ToNot(HaveOccurred())
+	})
+})

model/metadata/legacy_ids.go

@@ -9,17 +9,19 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/id"
 )
 
-// These are the legacy ID functions that were used in the original Navidrome ID generation.
-// They are kept here for backwards compatibility with existing databases.
+// These legacy ID functions hash the same inputs as the original Navidrome ID generation,
+// now emitted in the canonical base62 encoding (matching what the uniform-ids migration stores).
 
 func legacyTrackID(mf model.MediaFile, prependLibId bool) string {
-	id := mf.Path
+	key := mf.Path
 	if prependLibId && mf.LibraryID != model.DefaultLibraryID {
-		id = fmt.Sprintf("%d\\%s", mf.LibraryID, id)
+		key = fmt.Sprintf("%d\\%s", mf.LibraryID, key)
 	}
-	return fmt.Sprintf("%x", md5.Sum([]byte(id)))
+	sum := md5.Sum([]byte(key))
+	return id.Encode(sum)
 }
 
 func legacyAlbumID(mf model.MediaFile, md Metadata, prependLibId bool) string {
@@ -33,7 +35,8 @@ func legacyAlbumID(mf model.MediaFile, md Metadata, prependLibId bool) string {
 	if prependLibId && mf.LibraryID != model.DefaultLibraryID {
 		albumPath = fmt.Sprintf("%d\\%s", mf.LibraryID, albumPath)
 	}
-	return fmt.Sprintf("%x", md5.Sum([]byte(albumPath)))
+	sum := md5.Sum([]byte(albumPath))
+	return id.Encode(sum)
 }
 
 func legacyMapAlbumArtistName(md Metadata) string {

model/metadata/persistent_ids_test.go

@@ -218,6 +218,21 @@ var _ = Describe("getPID", func() {
 	})
 
 	Context("legacy specs", func() {
+		It("emits canonical 22-char base62 ids", func() {
+			mf := model.MediaFile{Path: "/music/a.mp3", LibraryID: 1}
+			// md5("/music/a.mp3") = e3b7fc2ae9447bbec37a13bf916e3cf6 re-encoded as base62
+			Expect(legacyTrackID(mf, false)).To(Equal("6VHl3uR4kss6sUPKA8Cwnk"))
+		})
+		It("prepends the library id for a non-default library", func() {
+			mf := model.MediaFile{Path: "/music/a.mp3", LibraryID: 2}
+			// id.Encode(md5.Sum([]byte("2\\/music/a.mp3")))
+			Expect(legacyTrackID(mf, true)).To(Equal("4EK5DHQBMeFuDHw6S3iooO"))
+		})
+		It("emits a canonical album id (golden)", func() {
+			mf := model.MediaFile{LibraryID: 1}
+			// id.Encode(md5.Sum([]byte("[unknown artist]\\[unknown album]")))
+			Expect(legacyAlbumID(mf, Metadata{}, false)).To(Equal("6xBmxSAUFJSQuW7UvwCq8X"))
+		})
 		Context("track_legacy", func() {
 			When("library ID is default (1)", func() {
 				It("should not prepend library ID even when prependLibId is true", func() {