fix(guest): add playCollection permission so guests can Play All playlist/album (#103)

- New guest flag playCollection (default OFF), gates play-playlist/play-album
- Keeps playNow's non-destructive semantics intact (Play All clears the queue)
- Admin-toggleable in Settings → 游客模式; default-off, backward-compatible
- Frontend: gate the 播放全部 button on the flag + surface 403 as a toast
  instead of failing silently (the silent-failure half of the issue)

src/data/config.test.ts

@@ -115,6 +115,7 @@ describe("guestMode config", () => {
     expect(c.guestMode.permissions).toEqual({
       addToQueue: true, playNext: false, playNow: false,
       skip: false, transport: false, removeClear: false, playMode: false,
+      playCollection: false,
     });
   });
 
@@ -167,10 +168,11 @@ describe("guestMode config", () => {
     });
     it("a string permissions value yields defaults with no numeric index keys", () => {
       const gm = loadGuestMode({ guestMode: { permissions: "hacked" } });
-      // 7 known flags present at their defaults
+      // all known flags present at their defaults
       expect(gm.permissions).toEqual({
         addToQueue: true, playNext: false, playNow: false,
         skip: false, transport: false, removeClear: false, playMode: false,
+        playCollection: false,
       });
       // no garbage index keys leaked from spreading a string
       expect((gm.permissions as unknown as Record<string, unknown>)["0"]).toBeUndefined();

src/data/config.ts

@@ -63,6 +63,7 @@ export function getDefaultConfig(): BotConfig {
         transport: false,
         removeClear: false,
         playMode: false,
+        playCollection: false,
       },
     },
   };

src/data/permissions.test.ts

@@ -105,6 +105,7 @@ describe("resolvePermissionContext guest branch", () => {
       permissions: {
         addToQueue: true, playNext: false, playNow: false,
         skip: true, transport: false, removeClear: false, playMode: false,
+        playCollection: false,
       },
     });
     expect([...ctx.capabilities]).toEqual([]);
@@ -120,14 +121,15 @@ describe("resolvePermissionContext guest branch", () => {
       permissions: {
         addToQueue: true, playNext: false, playNow: false,
         skip: false, transport: false, removeClear: false, playMode: false,
+        playCollection: false,
       },
     });
     expect(ctx.bots).toBe("all");
   });
 
-  it("exposes the 7 canonical flags", () => {
+  it("exposes the 8 canonical flags", () => {
     expect([...GUEST_PERMISSION_FLAGS].sort()).toEqual(
-      ["addToQueue", "playMode", "playNext", "playNow", "removeClear", "skip", "transport"].sort()
+      ["addToQueue", "playCollection", "playMode", "playNext", "playNow", "removeClear", "skip", "transport"].sort()
     );
   });
 });

src/data/permissions.ts

@@ -29,6 +29,8 @@ export interface GuestPermissions {
   transport: boolean;
   removeClear: boolean;
   playMode: boolean;
+  /** Load + play an entire playlist/album (clears the queue). Issue #103. */
+  playCollection: boolean;
 }
 
 export const GUEST_PERMISSION_FLAGS = [
@@ -39,6 +41,7 @@ export const GUEST_PERMISSION_FLAGS = [
   "transport",
   "removeClear",
   "playMode",
+  "playCollection",
 ] as const;
 export type GuestFlag = (typeof GUEST_PERMISSION_FLAGS)[number];
 

src/web/api/permissions-enforcement.test.ts

@@ -301,6 +301,7 @@ const guest = (perms: Partial<Record<string, boolean>> = {}) => ({
     transport: false,
     removeClear: false,
     playMode: false,
+    playCollection: false,
     ...perms,
   },
 });
@@ -373,7 +374,19 @@ describe("guest enforcement on player routes", () => {
     expect((await request(mountGuest({ transport: true })).post(`/api/player/${ALLOWED_BOT}/add-song`).send({ song: SONG })).status).toBe(403);
   });
 
-  it("guests are always denied /play, /prev, /stop, /play-song, /play-at, /play-playlist, /play-album, /playlist, /profile even with ALL flags on", async () => {
+  it("playCollection flag gates /play-playlist, /play-album (issue #103)", async () => {
+    const allow = mountGuest({ playCollection: true });
+    const deny = mountGuest({ playCollection: false });
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/play-playlist`).send({ playlistId: "1" })).status).not.toBe(403);
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/play-album`).send({ albumId: "1" })).status).not.toBe(403);
+    expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/play-playlist`).send({ playlistId: "1" })).status).toBe(403);
+    expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/play-album`).send({ albumId: "1" })).status).toBe(403);
+    // playCollection does NOT leak into the destructive single-song / queue ops.
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/play`).send({ query: "x" })).status).toBe(403);
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/play-song`).send({ song: SONG })).status).toBe(403);
+  });
+
+  it("guests are always denied /play, /prev, /stop, /play-song, /play-at, /playlist, /profile even with ALL flags on", async () => {
     const all = mountGuest({
       addToQueue: true,
       playNext: true,
@@ -382,14 +395,13 @@ describe("guest enforcement on player routes", () => {
       transport: true,
       removeClear: true,
       playMode: true,
+      playCollection: true,
     });
     expect((await request(all).post(`/api/player/${ALLOWED_BOT}/play`).send({ query: "x" })).status).toBe(403);
     expect((await request(all).post(`/api/player/${ALLOWED_BOT}/prev`)).status).toBe(403);
     expect((await request(all).post(`/api/player/${ALLOWED_BOT}/stop`)).status).toBe(403);
     expect((await request(all).post(`/api/player/${ALLOWED_BOT}/play-song`).send({ song: SONG })).status).toBe(403);
     expect((await request(all).post(`/api/player/${ALLOWED_BOT}/play-at`).send({ index: 0 })).status).toBe(403);
-    expect((await request(all).post(`/api/player/${ALLOWED_BOT}/play-playlist`).send({ playlistId: "1" })).status).toBe(403);
-    expect((await request(all).post(`/api/player/${ALLOWED_BOT}/play-album`).send({ albumId: "1" })).status).toBe(403);
     expect((await request(all).post(`/api/player/${ALLOWED_BOT}/playlist`).send({ playlistId: "1" })).status).toBe(403);
     expect((await request(all).put(`/api/player/${ALLOWED_BOT}/profile`).send({})).status).toBe(403);
   });

src/web/api/player.ts

@@ -265,7 +265,7 @@ export function createPlayerRouter(
 
   // Play a playlist by ID — stores metadata only, resolves URL for first song
   // Respects current play mode (random = pick random first song)
-  router.post("/:botId/play-playlist", authorize({ capability: "player.control" }), async (req, res) => {
+  router.post("/:botId/play-playlist", authorize({ capability: "player.control", guestFlag: "playCollection" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const { playlistId, platform } = req.body;
@@ -352,7 +352,7 @@ export function createPlayerRouter(
   });
 
   // Play an album by ID — mirrors play-playlist but calls getAlbumSongs
-  router.post("/:botId/play-album", authorize({ capability: "player.control" }), async (req, res) => {
+  router.post("/:botId/play-album", authorize({ capability: "player.control", guestFlag: "playCollection" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const { albumId, platform } = req.body;

src/web/api/session.test.ts

@@ -217,6 +217,7 @@ describe("session router — guest mode", () => {
         transport: false,
         removeClear: false,
         playMode: false,
+        playCollection: false,
       },
       guestBots: "all",
     });

src/web/middleware/requireAuth.test.ts

@@ -36,6 +36,7 @@ describe("requireAuth middleware", () => {
           transport: true,
           removeClear: true,
           playMode: true,
+          playCollection: true,
         },
       }))
     );
@@ -100,7 +101,7 @@ describe("requireAuth middleware", () => {
   it("attaches guest permissions when guest mode is enabled", () => {
     const sessions: any = { validateAndTouch: () => ({ userId: "__guest__", username: "游客", role: "guest" }) };
     const permissions: any = { getCapabilities: () => [], getBotAccess: () => [] };
-    const perms = { addToQueue: true, playNext: false, playNow: false, skip: false, transport: false, removeClear: false, playMode: false };
+    const perms = { addToQueue: true, playNext: false, playNow: false, skip: false, transport: false, removeClear: false, playMode: false, playCollection: false };
     const getGuestConfig = () => ({ enabled: true, bots: ["bot1"], permissions: perms });
     const mw = createRequireAuth(sessions, permissions, getGuestConfig);
     const req: any = { headers: { cookie: "tsmb_session=x" }, secure: false };