From dc29424d489d6f70d67793db3424f0b0098dd02d Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Wed, 18 Nov 2026 09:27:45 -0500 Subject: [PATCH 1/2] Expose bounded player configuration capabilities --- .../players/registerGetReleasePlayerTool.ts | 3 +- .../__tests__/getPlayerCapabilities.test.ts | 22 ++++++ .../__tests__/processPlayerOperation.test.ts | 71 +++++++++++++++++ lib/players/__tests__/publicPlayer.test.ts | 76 ++++++++++++++++++- lib/players/getPlayerCapabilities.ts | 16 ++++ lib/players/getPublicPlayer.ts | 2 + lib/players/processPlayerOperation.ts | 8 +- 7 files changed, 195 insertions(+), 3 deletions(-) create mode 100644 lib/players/__tests__/getPlayerCapabilities.test.ts create mode 100644 lib/players/getPlayerCapabilities.ts diff --git a/lib/mcp/tools/players/registerGetReleasePlayerTool.ts b/lib/mcp/tools/players/registerGetReleasePlayerTool.ts index 001d840a6..09878498c 100644 --- a/lib/mcp/tools/players/registerGetReleasePlayerTool.ts +++ b/lib/mcp/tools/players/registerGetReleasePlayerTool.ts @@ -5,7 +5,8 @@ export function registerGetReleasePlayerTool(server: McpServer) { server.registerTool( "get_release_player", { - description: "Read release player configuration, current revision and share/embed links.", + description: + "Read release player configuration, current revision and share/embed links. Capabilities v1 reports Spotify client/destination configuration; fan eligibility, token, scope and playback observations remain unknown.", inputSchema: playerOperationSchemas.get, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, }, diff --git a/lib/players/__tests__/getPlayerCapabilities.test.ts b/lib/players/__tests__/getPlayerCapabilities.test.ts new file mode 100644 index 000000000..65285d6c1 --- /dev/null +++ b/lib/players/__tests__/getPlayerCapabilities.test.ts @@ -0,0 +1,22 @@ +import { afterEach, expect, it, vi } from "vitest"; +import { getPlayerCapabilities } from "../getPlayerCapabilities"; +afterEach(() => vi.unstubAllEnvs()); +it.each([ + ["", null], + ["", "https://open.spotify.com/track/abc"], + ["public-client-id", null], + ["public-client-id", "https://open.spotify.com/track/abc"], +])("projects only configuration, never fan observations (%s, %s)", (client, release) => { + vi.stubEnv("SITES_SPOTIFY_CLIENT_ID", client as string); + expect(getPlayerCapabilities(release)).toEqual({ + version: 1, + spotify: { + clientConfiguration: client ? "configured" : "unconfigured", + releaseConfigured: !!release, + premiumEligibility: "unknown", + tokenStatus: "unknown", + scopeStatus: "unknown", + playbackSupport: "unknown", + }, + }); +}); diff --git a/lib/players/__tests__/processPlayerOperation.test.ts b/lib/players/__tests__/processPlayerOperation.test.ts index dbf9616cf..e8ae08f48 100644 --- a/lib/players/__tests__/processPlayerOperation.test.ts +++ b/lib/players/__tests__/processPlayerOperation.test.ts @@ -1,5 +1,17 @@ import { beforeEach, expect, it, vi } from "vitest"; import { processPlayerOperation } from "../processPlayerOperation"; +import { afterEach } from "vitest"; +import { NextRequest, NextResponse } from "next/server"; +import { playerOperationHandler } from "../playerOperationHandler"; +import { getPlayerToolHandler } from "@/lib/mcp/tools/players/getPlayerToolHandler"; +import { getToolResultSuccess } from "@/lib/mcp/getToolResultSuccess"; +import { SiteError } from "@/lib/sites/SiteError"; +const auth = vi.hoisted(() => ({ http: vi.fn(), mcp: vi.fn() })); +vi.mock("@/lib/auth/validateAuthContext", () => ({ validateAuthContext: auth.http })); +vi.mock("@/lib/mcp/resolveAccountId", () => ({ resolveAccountId: auth.mcp })); +vi.mock("../readPlayerReport", () => ({ readPlayerReport: vi.fn() })); +vi.mock("../readPlayerFans", () => ({ readPlayerFans: vi.fn() })); +vi.mock("../readWorkspacePlayerFans", () => ({ readWorkspacePlayerFans: vi.fn() })); vi.mock("@/lib/sites/activity/limitSiteRequest", () => ({ limitSiteRequest: vi.fn() })); const mocks = vi.hoisted(() => ({ access: vi.fn(), @@ -55,6 +67,7 @@ it("derives ownership and creates a disabled reusable release player", async () created_by: owner, }), ); + expect(result).not.toHaveProperty("capabilities"); expect(result).toHaveProperty("listenUrl", `https://app.recoupable.dev/listen/${artist}`); }); it("blocks an artist outside the workspace", async () => { @@ -138,6 +151,7 @@ it("paginates the workspace catalog instead of silently truncating it", async () const result = await processPlayerOperation(owner, "list", { offset: 100, limit: 1 }); expect(mocks.list).toHaveBeenCalledWith(owner, 100, 1); expect(result).toMatchObject({ offset: 100, limit: 1, nextOffset: 101 }); + expect(result).not.toHaveProperty("capabilities"); }); it("stores the owner-selected fallback and rejects non-owned audio before creating", async () => { @@ -215,3 +229,60 @@ it("can unpublish or change a title without rechecking unchanged audio", async ( processPlayerOperation(owner, "update", { id: artist, revision: 1, enabled: true }), ).rejects.toThrow("Storage unavailable"); }); + +it("returns the same capabilities through real HTTP and MCP get domains", async () => { + vi.stubEnv("SITES_SPOTIFY_CLIENT_ID", ""); + vi.stubEnv("PLAYER_APP_ORIGIN", "not-an-origin"); + mocks.select.mockResolvedValue({ + id: artist, + owner_id: owner, + enabled: false, + spotify_url: "https://open.spotify.com/track/abc", + }); + auth.http.mockResolvedValue({ accountId: owner }); + auth.mcp.mockResolvedValue({ accountId: owner }); + const response = await playerOperationHandler( + new NextRequest("https://api.example/api/players/" + artist), + "get", + { id: artist }, + ); + expect(response.status).toBe(200); + expect(response.headers.get("Cache-Control")).toBe("private, no-store"); + const body = await response.json(); + expect(body.capabilities).toEqual({ + version: 1, + spotify: { + clientConfiguration: "unconfigured", + releaseConfigured: true, + premiumEligibility: "unknown", + tokenStatus: "unknown", + scopeStatus: "unknown", + playbackSupport: "unknown", + }, + }); + const tool = await getPlayerToolHandler("get")({ id: artist }, { authInfo: {} }); + expect(tool).toEqual(getToolResultSuccess(body)); + expect(body.player.enabled).toBe(false); +}); +it("preserves HTTP/MCP authentication and ownership denial before player read results", async () => { + auth.http.mockResolvedValue(NextResponse.json({ error: "Unauthorized" }, { status: 401 })); + auth.mcp.mockResolvedValue({ accountId: null }); + expect( + (await playerOperationHandler(new NextRequest("https://api.example"), "get", { id: artist })) + .status, + ).toBe(401); + expect(await getPlayerToolHandler("get")({ id: artist }, {})).toMatchObject({ isError: true }); + expect(mocks.select).not.toHaveBeenCalled(); + auth.http.mockResolvedValue({ accountId: owner }); + mocks.select.mockResolvedValue({ owner_id: "another-owner" }); + expect( + (await playerOperationHandler(new NextRequest("https://api.example"), "get", { id: artist })) + .status, + ).toBe(404); + mocks.access.mockRejectedValueOnce(new SiteError(403, "Workspace denied")); + expect( + (await playerOperationHandler(new NextRequest("https://api.example"), "get", { id: artist })) + .status, + ).toBe(403); +}); +afterEach(() => vi.unstubAllEnvs()); diff --git a/lib/players/__tests__/publicPlayer.test.ts b/lib/players/__tests__/publicPlayer.test.ts index b9621c5d8..9b94c3e4d 100644 --- a/lib/players/__tests__/publicPlayer.test.ts +++ b/lib/players/__tests__/publicPlayer.test.ts @@ -1,4 +1,5 @@ -import { beforeEach, expect, it, vi } from "vitest"; +import { GET as publicGet } from "@/app/api/players/public/[id]/route"; +import { afterEach, beforeEach, expect, it, vi } from "vitest"; import { getPublicPlayer } from "../getPublicPlayer"; const m = vi.hoisted(() => ({ select: vi.fn(), @@ -101,3 +102,76 @@ it("exposes configured audio only to Spotify provider sessions, not the chooser await getPublicPlayer(id, { provider: "apple_music", parent: "https://artist.example" }, true), ).toMatchObject({ audioUrl: null }); }); + +it.each(["", "public-client-id"])( + "exposes credential-free capabilities without creating a session (%s)", + async client => { + vi.stubEnv("SITES_SPOTIFY_CLIENT_ID", client); + vi.stubEnv("PLAYER_APP_ORIGIN", "https://app.recoupable.dev"); + const result = await getPublicPlayer(id, {}); + expect(result).toMatchObject({ + capabilities: { + version: 1, + spotify: { + clientConfiguration: client ? "configured" : "unconfigured", + releaseConfigured: true, + premiumEligibility: "unknown", + tokenStatus: "unknown", + scopeStatus: "unknown", + playbackSupport: "unknown", + }, + }, + }); + expect(result).not.toHaveProperty("spotify"); + expect(result).not.toHaveProperty("flow"); + expect(m.insert).not.toHaveBeenCalled(); + }, +); +it("retains capability unknowns on fresh and resumed provider sessions", async () => { + vi.stubEnv("SITES_SPOTIFY_CLIENT_ID", ""); + const first = await getPublicPlayer( + id, + { provider: "spotify", parent: "https://artist.example" }, + true, + ); + expect(first).toMatchObject({ + spotify: { configured: false }, + capabilities: { spotify: { clientConfiguration: "unconfigured", tokenStatus: "unknown" } }, + }); + expect(m.insert).toHaveBeenCalledTimes(1); + if (!("flow" in first)) throw new Error("Expected session"); + m.session.mockResolvedValue({ ...m.insert.mock.calls[0][0], provider: "spotify" }); + const resumed = await getPublicPlayer( + id, + { provider: "spotify", parent: "https://artist.example", flow: first.flow }, + true, + ); + expect(resumed).toMatchObject({ flow: first.flow, capabilities: first.capabilities }); + expect(m.insert).toHaveBeenCalledTimes(1); +}); + +afterEach(() => { + vi.unstubAllEnvs(); + vi.unstubAllGlobals(); +}); + +it("keeps metadata GET credential-free, no-store and free of provider/session work", async () => { + const fetch = vi.fn(); + vi.stubGlobal("fetch", fetch); + const response = await publicGet(new Request("https://api.example/api/players/public/" + id), { + params: Promise.resolve({ id }), + }); + expect(response.status).toBe(200); + expect(response.headers.get("Cache-Control")).toBe("no-store"); + const body = await response.json(); + expect(body.capabilities.version).toBe(1); + expect(body).not.toHaveProperty("spotify"); + expect(body).not.toHaveProperty("flow"); + expect(m.insert).not.toHaveBeenCalled(); + expect(fetch).not.toHaveBeenCalled(); +}); +it("preserves invalid public origin configuration failure", async () => { + vi.stubEnv("PLAYER_APP_ORIGIN", "invalid"); + await expect(getPublicPlayer(id, {})).rejects.toThrow(); + expect(m.insert).not.toHaveBeenCalled(); +}); diff --git a/lib/players/getPlayerCapabilities.ts b/lib/players/getPlayerCapabilities.ts new file mode 100644 index 000000000..53dd5f994 --- /dev/null +++ b/lib/players/getPlayerCapabilities.ts @@ -0,0 +1,16 @@ +/** Configuration observations only; never proof of fan eligibility or playback authority. */ +export function getPlayerCapabilities(spotifyUrl: string | null) { + return { + version: 1 as const, + spotify: { + clientConfiguration: process.env.SITES_SPOTIFY_CLIENT_ID + ? ("configured" as const) + : ("unconfigured" as const), + releaseConfigured: !!spotifyUrl, + premiumEligibility: "unknown" as const, + tokenStatus: "unknown" as const, + scopeStatus: "unknown" as const, + playbackSupport: "unknown" as const, + }, + }; +} diff --git a/lib/players/getPublicPlayer.ts b/lib/players/getPublicPlayer.ts index 0a1ac7a44..4a81ca6c8 100644 --- a/lib/players/getPublicPlayer.ts +++ b/lib/players/getPublicPlayer.ts @@ -1,3 +1,4 @@ +import { getPlayerCapabilities } from "./getPlayerCapabilities"; import { randomUUID } from "node:crypto"; import { z } from "zod"; import { selectReleasePlayer } from "@/lib/supabase/release_players/selectReleasePlayer"; @@ -43,6 +44,7 @@ export async function getPublicPlayer(id: string, input: unknown, createSession appleUrl: player.apple_url, revision: player.revision, freePlayback: player.free_playback ?? "spotify", + capabilities: getPlayerCapabilities(player.spotify_url), }; if (!query.provider) return result; const release = query.provider === "spotify" ? player.spotify_url : player.apple_url; diff --git a/lib/players/processPlayerOperation.ts b/lib/players/processPlayerOperation.ts index a0531c37c..a743e5350 100644 --- a/lib/players/processPlayerOperation.ts +++ b/lib/players/processPlayerOperation.ts @@ -1,3 +1,4 @@ +import { getPlayerCapabilities } from "./getPlayerCapabilities"; import { requirePlayerAudio } from "./requirePlayerAudio"; import { limitSiteRequest } from "@/lib/sites/activity/limitSiteRequest"; import { z } from "zod"; @@ -60,7 +61,12 @@ export async function processPlayerOperation( const id = z.object({ id: z.string().uuid() }).parse(input).id; const player = await selectReleasePlayer(id); if (!player || player.owner_id !== owner) throw new SiteError(404, "Player not found"); - if (operation === "get") return { player, ...getPlayerLinks(player.id) }; + if (operation === "get") + return { + player, + ...getPlayerLinks(player.id), + capabilities: getPlayerCapabilities(player.spotify_url), + }; const update = playerOperationSchemas.update.parse(input); if (player.revision !== update.revision) throw new SiteError(409, "Player changed; read the latest revision"); From 18fc2c4afef71dcd0a323c819fbce412db41e835 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Wed, 18 Nov 2026 09:37:33 -0500 Subject: [PATCH 2/2] Refine player read projection and capability wording --- .../tools/players/registerGetReleasePlayerTool.ts | 2 +- lib/players/getPlayerReadResponse.ts | 12 ++++++++++++ lib/players/processPlayerOperation.ts | 9 ++------- 3 files changed, 15 insertions(+), 8 deletions(-) create mode 100644 lib/players/getPlayerReadResponse.ts diff --git a/lib/mcp/tools/players/registerGetReleasePlayerTool.ts b/lib/mcp/tools/players/registerGetReleasePlayerTool.ts index 09878498c..69be569d2 100644 --- a/lib/mcp/tools/players/registerGetReleasePlayerTool.ts +++ b/lib/mcp/tools/players/registerGetReleasePlayerTool.ts @@ -6,7 +6,7 @@ export function registerGetReleasePlayerTool(server: McpServer) { "get_release_player", { description: - "Read release player configuration, current revision and share/embed links. Capabilities v1 reports Spotify client/destination configuration; fan eligibility, token, scope and playback observations remain unknown.", + "Read release player configuration, current revision and share/embed links. Capabilities v1 reports Spotify client/destination configuration; premium eligibility, token, scope and playback observations remain unknown.", inputSchema: playerOperationSchemas.get, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, }, diff --git a/lib/players/getPlayerReadResponse.ts b/lib/players/getPlayerReadResponse.ts new file mode 100644 index 000000000..8b45ff0d5 --- /dev/null +++ b/lib/players/getPlayerReadResponse.ts @@ -0,0 +1,12 @@ +import { getPlayerCapabilities } from "./getPlayerCapabilities"; +import { getPlayerLinks } from "./getPlayerLinks"; +import type { ReleasePlayer } from "./schema"; + +/** Project the player only after the caller has verified workspace ownership. */ +export function getPlayerReadResponse(player: ReleasePlayer) { + return { + player, + ...getPlayerLinks(player.id), + capabilities: getPlayerCapabilities(player.spotify_url), + }; +} diff --git a/lib/players/processPlayerOperation.ts b/lib/players/processPlayerOperation.ts index a743e5350..0a0dddee8 100644 --- a/lib/players/processPlayerOperation.ts +++ b/lib/players/processPlayerOperation.ts @@ -1,4 +1,4 @@ -import { getPlayerCapabilities } from "./getPlayerCapabilities"; +import { getPlayerReadResponse } from "./getPlayerReadResponse"; import { requirePlayerAudio } from "./requirePlayerAudio"; import { limitSiteRequest } from "@/lib/sites/activity/limitSiteRequest"; import { z } from "zod"; @@ -61,12 +61,7 @@ export async function processPlayerOperation( const id = z.object({ id: z.string().uuid() }).parse(input).id; const player = await selectReleasePlayer(id); if (!player || player.owner_id !== owner) throw new SiteError(404, "Player not found"); - if (operation === "get") - return { - player, - ...getPlayerLinks(player.id), - capabilities: getPlayerCapabilities(player.spotify_url), - }; + if (operation === "get") return getPlayerReadResponse(player); const update = playerOperationSchemas.update.parse(input); if (player.revision !== update.revision) throw new SiteError(409, "Player changed; read the latest revision");