feat(playlists): permalink-only access to private playlists (#843)

## Summary

- Allow unauthenticated callers to view a **private playlist** when they
have the permalink, while keeping it hidden from search/browse and
bare-ID lookups. This mirrors the existing `is_unlisted` model for
tracks.
- A new `is_private` filter is added to `get_playlists.sql` with an
`@include_private` bypass flag. Permalink-driven entry points (the
`by_permalink` route, the bulk `/v1/full/playlists?permalink=…`
endpoint, and the `/v1/resolve` redirect target) set `IncludePrivate:
true`; bare ID lookups do not.
- The bulk endpoint keeps caller-supplied IDs and permalink-derived IDs
in **separate** `Playlists()` calls so a request mixing
`?id=PRIVATE_ID&permalink=any_public` cannot leak a private playlist by
piggy-backing on the permalink trust.
- `v1_playlist_by_permalink` now accepts both `/playlist/` and `/album/`
URL variants, so `/v1/resolve` can redirect album URLs there.
- Tracks already allow anonymous permalink access (every direct-fetch
handler sets `IncludeUnlisted: true`); no code change there, just a
regression test.

## Behavior change

Anonymous (and non-owner) requests to `/v1/full/playlists/:id` or
`/v1/full/playlists?id=…` for a **private** playlist will now return 404
/ empty. Owners (myID == owner_id) and any callers using the permalink
continue to see the playlist.

## Test plan

- [ ] `TestV1PlaylistByPermalink` and `TestV1AlbumByPermalink` still
pass
- [ ] `TestV1PrivatePlaylistByPermalinkAnonymous` — anon caller gets
private playlist via permalink
- [ ] `TestV1PrivateAlbumByPermalinkAnonymous` — anon caller gets
private album via permalink
- [ ] `TestPlaylistsEndpointPrivatePermalinkAnonymous` — same via bulk
endpoint
- [ ] `TestPlaylistsEndpointPrivateByIdHiddenFromAnonymous` — `?id=`
does **not** leak private
- [ ] `TestGetPlaylistPrivateAnonymous404` — `/playlists/:id` returns
404 for anon on private
- [ ] `TestGetPlaylistPrivateOwnerAllowed` — owner can still fetch their
private playlist by ID
- [ ] `TestGetUnlistedTrackByPermalinkAnonymous` — regression lock-in
for track permalink behavior
- [ ] Resolve tests (`TestResolvePlaylistURL`) still 302 (redirect
target changed to `by_permalink`, still ok)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

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

Author: dylanjeffers

api/dbv1/get_playlists.sql.go

@@ -129,4 +129,5 @@ JOIN aggregate_playlist using (playlist_id)
 LEFT JOIN playlist_routes on p.playlist_id = playlist_routes.playlist_id and playlist_routes.is_current = true
 WHERE is_delete = false
   and p.playlist_id = ANY(@ids::int[])
+  and (p.is_private = false OR p.playlist_owner_id = @my_id OR @include_private::bool = TRUE)
 ;

api/dbv1/queries/get_playlists.sql

@@ -20,18 +20,22 @@ func (app *ApiServer) v1PlaylistByPermalink(c *fiber.Ctx) error {
 	}
 
 	ids, err := app.queries.GetPlaylistIdsByPermalink(c.Context(), dbv1.GetPlaylistIdsByPermalinkParams{
-		Handles:    []string{params.Handle},
-		Slugs:      []string{params.Slug},
-		Permalinks: []string{"/" + params.Handle + "/playlist/" + params.Slug},
+		Handles: []string{params.Handle},
+		Slugs:   []string{params.Slug},
+		Permalinks: []string{
+			"/" + params.Handle + "/playlist/" + params.Slug,
+			"/" + params.Handle + "/album/" + params.Slug,
+		},
 	})
 	if err != nil {
 		return err
 	}
 
 	playlists, err := app.queries.Playlists(c.Context(), dbv1.PlaylistsParams{
 		GetPlaylistsParams: dbv1.GetPlaylistsParams{
-			MyID: myId,
-			Ids:  ids,
+			MyID:           myId,
+			Ids:            ids,
+			IncludePrivate: true,
 		},
 		AuthedWallet: app.tryGetAuthedWallet(c),
 	})

api/v1_playlist_by_permalink.go

@@ -1,9 +1,11 @@
 package api
 
 import (
+	"context"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestV1PlaylistByPermalink(t *testing.T) {
@@ -16,3 +18,53 @@ func TestV1PlaylistByPermalink(t *testing.T) {
 		"data.0.playlist_name": "playlist by permalink",
 	})
 }
+
+func TestV1AlbumByPermalink(t *testing.T) {
+	app := testAppWithFixtures(t)
+	status, body := testGet(t, app, "/v1/full/playlists/by_permalink/AlbumsByPermalink/album-by-permalink")
+	assert.Equal(t, 200, status)
+
+	jsonAssert(t, body, map[string]any{
+		"data.0.id":            "ePVXL",
+		"data.0.playlist_name": "album by permalink",
+	})
+}
+
+// A private playlist should be returned to anonymous callers when fetched via
+// permalink — "has the link" is sufficient permission.
+func TestV1PrivatePlaylistByPermalinkAnonymous(t *testing.T) {
+	app := testAppWithFixtures(t)
+	ctx := context.Background()
+	require.NotNil(t, app.writePool, "test requires write pool")
+
+	_, err := app.writePool.Exec(ctx, `UPDATE playlists SET is_private = true WHERE playlist_id = 500 AND is_current = true`)
+	require.NoError(t, err)
+
+	status, body := testGet(t, app, "/v1/full/playlists/by_permalink/PlaylistsByPermalink/playlist-by-permalink")
+	assert.Equal(t, 200, status)
+
+	jsonAssert(t, body, map[string]any{
+		"data.0.id":            "eYake",
+		"data.0.playlist_name": "playlist by permalink",
+		"data.0.is_private":    true,
+	})
+}
+
+// Same for albums.
+func TestV1PrivateAlbumByPermalinkAnonymous(t *testing.T) {
+	app := testAppWithFixtures(t)
+	ctx := context.Background()
+	require.NotNil(t, app.writePool, "test requires write pool")
+
+	_, err := app.writePool.Exec(ctx, `UPDATE playlists SET is_private = true WHERE playlist_id = 501 AND is_current = true`)
+	require.NoError(t, err)
+
+	status, body := testGet(t, app, "/v1/full/playlists/by_permalink/AlbumsByPermalink/album-by-permalink")
+	assert.Equal(t, 200, status)
+
+	jsonAssert(t, body, map[string]any{
+		"data.0.id":            "ePVXL",
+		"data.0.playlist_name": "album by permalink",
+		"data.0.is_private":    true,
+	})
+}

api/v1_playlist_by_permalink_test.go

@@ -15,7 +15,13 @@ func (app *ApiServer) v1Playlists(c *fiber.Ctx) error {
 	// unless client explicitly does ?with_tracks=true
 	withTracks, _ := strconv.ParseBool(c.Query("with_tracks", "false"))
 
-	// Add permalink ID mappings
+	authedWallet := app.tryGetAuthedWallet(c)
+
+	// Permalink-matched IDs are kept separate from caller-supplied IDs. Possession
+	// of a valid permalink is treated as proof of access, so private playlists
+	// matched by permalink are returned without auth. We must not extend that
+	// trust to user-supplied IDs in the same request.
+	var permalinkIds []int32
 	permalinks := queryMulti(c, "permalink")
 	if len(permalinks) > 0 {
 		handles := make([]string, len(permalinks))
@@ -29,15 +35,15 @@ func (app *ApiServer) v1Playlists(c *fiber.Ctx) error {
 				return fiber.NewError(fiber.StatusBadRequest, "Invalid permalink: "+permalinks[i])
 			}
 		}
-		newIds, err := app.queries.GetPlaylistIdsByPermalink(c.Context(), dbv1.GetPlaylistIdsByPermalinkParams{
+		var err error
+		permalinkIds, err = app.queries.GetPlaylistIdsByPermalink(c.Context(), dbv1.GetPlaylistIdsByPermalinkParams{
 			Handles:    handles,
 			Slugs:      slugs,
 			Permalinks: permalinks,
 		})
 		if err != nil {
 			return err
 		}
-		ids = append(ids, newIds...)
 	}
 
 	upcs := queryMulti(c, "upc")
@@ -49,17 +55,38 @@ func (app *ApiServer) v1Playlists(c *fiber.Ctx) error {
 		ids = append(ids, newIds...)
 	}
 
-	playlists, err := app.queries.Playlists(c.Context(), dbv1.PlaylistsParams{
-		GetPlaylistsParams: dbv1.GetPlaylistsParams{
-			MyID: myId,
-			Ids:  ids,
-		},
-		OmitTracks:   !withTracks,
-		AuthedWallet: app.tryGetAuthedWallet(c),
-	})
-	if err != nil {
-		return err
+	out := make([]dbv1.Playlist, 0, len(ids)+len(permalinkIds))
+
+	if len(ids) > 0 {
+		playlists, err := app.queries.Playlists(c.Context(), dbv1.PlaylistsParams{
+			GetPlaylistsParams: dbv1.GetPlaylistsParams{
+				MyID: myId,
+				Ids:  ids,
+			},
+			OmitTracks:   !withTracks,
+			AuthedWallet: authedWallet,
+		})
+		if err != nil {
+			return err
+		}
+		out = append(out, playlists...)
+	}
+
+	if len(permalinkIds) > 0 {
+		playlists, err := app.queries.Playlists(c.Context(), dbv1.PlaylistsParams{
+			GetPlaylistsParams: dbv1.GetPlaylistsParams{
+				MyID:           myId,
+				Ids:            permalinkIds,
+				IncludePrivate: true,
+			},
+			OmitTracks:   !withTracks,
+			AuthedWallet: authedWallet,
+		})
+		if err != nil {
+			return err
+		}
+		out = append(out, playlists...)
 	}
 
-	return v1PlaylistsResponse(c, playlists)
+	return v1PlaylistsResponse(c, out)
 }

api/v1_playlists.go

@@ -1,10 +1,13 @@
 package api
 
 import (
+	"context"
 	"testing"
 
 	"api.audius.co/api/dbv1"
+	"api.audius.co/trashid"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestPlaylistsEndpoint(t *testing.T) {
@@ -60,3 +63,79 @@ func TestPlaylistsEndpointWithAlbumPermalink(t *testing.T) {
 		"data.0.playlist_name": "album by permalink",
 	})
 }
+
+// A permalink-based lookup of a private playlist works for anonymous callers.
+func TestPlaylistsEndpointPrivatePermalinkAnonymous(t *testing.T) {
+	app := testAppWithFixtures(t)
+	ctx := context.Background()
+	require.NotNil(t, app.writePool, "test requires write pool")
+
+	_, err := app.writePool.Exec(ctx, `UPDATE playlists SET is_private = true WHERE playlist_id = 500 AND is_current = true`)
+	require.NoError(t, err)
+
+	var resp struct {
+		Data []dbv1.Playlist
+	}
+	status, body := testGet(t, app, "/v1/full/playlists?permalink=/PlaylistsByPermalink/playlist/playlist-by-permalink", &resp)
+	assert.Equal(t, 200, status)
+	assert.Len(t, resp.Data, 1, "permalink lookup must return private playlist even without auth")
+
+	jsonAssert(t, body, map[string]any{
+		"data.0.id":            "eYake",
+		"data.0.playlist_name": "playlist by permalink",
+		"data.0.is_private":    true,
+	})
+}
+
+// An ID-based lookup must NOT return private playlists to anonymous callers.
+func TestPlaylistsEndpointPrivateByIdHiddenFromAnonymous(t *testing.T) {
+	app := testAppWithFixtures(t)
+	ctx := context.Background()
+	require.NotNil(t, app.writePool, "test requires write pool")
+
+	_, err := app.writePool.Exec(ctx, `UPDATE playlists SET is_private = true WHERE playlist_id = 500 AND is_current = true`)
+	require.NoError(t, err)
+
+	var resp struct {
+		Data []dbv1.Playlist
+	}
+	status, _ := testGet(t, app, "/v1/full/playlists?id=eYake", &resp)
+	assert.Equal(t, 200, status)
+	assert.Len(t, resp.Data, 0, "private playlist must not be returned for ID-based anonymous lookup")
+}
+
+// The single playlist endpoint must also hide private playlists from anonymous callers.
+func TestGetPlaylistPrivateAnonymous404(t *testing.T) {
+	app := testAppWithFixtures(t)
+	ctx := context.Background()
+	require.NotNil(t, app.writePool, "test requires write pool")
+
+	_, err := app.writePool.Exec(ctx, `UPDATE playlists SET is_private = true WHERE playlist_id = 500 AND is_current = true`)
+	require.NoError(t, err)
+
+	status, _ := testGet(t, app, "/v1/full/playlists/eYake")
+	assert.Equal(t, 404, status, "private playlist must 404 for anonymous ID-based fetch")
+}
+
+// The single playlist endpoint must return private playlists to their owner.
+func TestGetPlaylistPrivateOwnerAllowed(t *testing.T) {
+	app := testAppWithFixtures(t)
+	// user 7's fixture wallet has no test signature, so bypass the auth
+	// middleware and let user_id alone identify the owner for this test.
+	app.skipAuthCheck = true
+	ctx := context.Background()
+	require.NotNil(t, app.writePool, "test requires write pool")
+
+	// playlist 500 is owned by user 7
+	_, err := app.writePool.Exec(ctx, `UPDATE playlists SET is_private = true WHERE playlist_id = 500 AND is_current = true`)
+	require.NoError(t, err)
+
+	ownerId := trashid.MustEncodeHashID(7)
+	status, body := testGet(t, app, "/v1/full/playlists/eYake?user_id="+ownerId)
+	assert.Equal(t, 200, status, "owner must be able to view their own private playlist by ID")
+	jsonAssert(t, body, map[string]any{
+		"data.0.id":            "eYake",
+		"data.0.playlist_name": "playlist by permalink",
+		"data.0.is_private":    true,
+	})
+}

api/v1_playlists_test.go

@@ -90,15 +90,12 @@ func (app *ApiServer) v1Resolve(c *fiber.Ctx) error {
 			return fiber.NewError(fiber.StatusNotFound, "Playlist not found")
 		}
 
-		playlistId, err := trashid.EncodeHashId(int(playlistIds[0]))
-		if err != nil {
-			return err
-		}
-
+		// Redirect to the by_permalink route so the destination handler can
+		// honor "has the link" as access to private playlists/albums.
 		if isFull {
-			return app.redirectWithPreservedParams(c, "/v1/full/playlists/"+playlistId, fiber.StatusFound)
+			return app.redirectWithPreservedParams(c, "/v1/full/playlists/by_permalink/"+handle+"/"+slug, fiber.StatusFound)
 		}
-		return app.redirectWithPreservedParams(c, "/v1/playlists/"+playlistId, fiber.StatusFound)
+		return app.redirectWithPreservedParams(c, "/v1/playlists/by_permalink/"+handle+"/"+slug, fiber.StatusFound)
 	}
 
 	// Try to match user URL

api/v1_resolve.go

@@ -78,6 +78,25 @@ func TestGetTracksByISRC(t *testing.T) {
 	}
 }
 
+func TestGetUnlistedTrackByPermalinkAnonymous(t *testing.T) {
+	app := testAppWithFixtures(t)
+	ctx := context.Background()
+	require.NotNil(t, app.writePool, "test requires write pool")
+
+	// Mark the permalink fixture track (track_id=500) as unlisted.
+	_, err := app.writePool.Exec(ctx, `UPDATE tracks SET is_unlisted = true WHERE track_id = 500 AND is_current = true`)
+	require.NoError(t, err)
+
+	// Anonymous request via permalink returns the unlisted track.
+	var resp struct {
+		Data []dbv1.Track
+	}
+	status, _ := testGet(t, app, "/v1/full/tracks?permalink=/TracksByPermalink/track-by-permalink", &resp)
+	assert.Equal(t, 200, status)
+	assert.Len(t, resp.Data, 1, "permalink lookup must return the unlisted track even without auth")
+	assert.Equal(t, "track by permalink", resp.Data[0].Title.String)
+}
+
 func TestGetTracksExcludesAccessAuthorities(t *testing.T) {
 	app := testAppWithFixtures(t)
 	ctx := context.Background()

api/v1_tracks_test.go

@@ -82,10 +82,14 @@ func (app *ApiServer) v1UserAlbums(c *fiber.Ctx) error {
 		return err
 	}
 
+	// Privacy was already enforced by the outer query via albumFilter, so
+	// allow Playlists() to hydrate private albums when the caller has
+	// authorization (e.g. filter_albums=private for the owner).
 	albums, err := app.queries.Playlists(c.Context(), dbv1.PlaylistsParams{
 		GetPlaylistsParams: dbv1.GetPlaylistsParams{
-			Ids:  ids,
-			MyID: myId,
+			Ids:            ids,
+			MyID:           myId,
+			IncludePrivate: true,
 		},
 		OmitTracks:   true,
 		AuthedWallet: app.tryGetAuthedWallet(c),

api/v1_users_albums.go

@@ -82,10 +82,14 @@ func (app *ApiServer) v1UserPlaylists(c *fiber.Ctx) error {
 		return err
 	}
 
+	// Privacy was already enforced by the outer query via playlistFilter, so
+	// allow Playlists() to hydrate private playlists when the caller has
+	// authorization (e.g. filter_playlists=private for the owner).
 	playlists, err := app.queries.Playlists(c.Context(), dbv1.PlaylistsParams{
 		GetPlaylistsParams: dbv1.GetPlaylistsParams{
-			Ids:  ids,
-			MyID: myId,
+			Ids:            ids,
+			MyID:           myId,
+			IncludePrivate: true,
 		},
 		OmitTracks:   true,
 		AuthedWallet: app.tryGetAuthedWallet(c),