Add player account linking + roster/vendor reads (phase 3)

Ties an in-game account to a website user and gates reads on ownership.

- schema: shard_account_links (account PK → user_id, char_name, linked_at;
  FK users ON DELETE CASCADE) — the site-side mirror of the sidecar's
  authoritative link.
- model/shardLinks: upsert/list/ownership-check/getByAccount/unlink.
- player/shard.controller.js:
  - POST /player/shard/link — confirm a one-time [link code via
    uoLinkClient.confirmLink(code, req.user.id); on link.ok mirror the link and
    activity.log it; bad/expired codes → 400, shard down → 503.
  - GET /player/shard/accounts — the caller's linked accounts.
  - GET /player/shard/roster/:account and /vendors/:account — live round-trips,
    ownership-checked against the mirror (403 otherwise), 503 on shard restart.
- player.routes.js: mounted under the existing requireRole('player') gate with
  express-validator guards + #swagger annotations; new "Player · Shard" tag and
  ShardLinkRequest/ShardLinkResult/ShardLink schemas; spec regenerated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011qPmpmVH1xGCiZoz9m9vW3

server/src/router/v1/player/player.routes.js

@@ -10,6 +10,7 @@ const express = require('express')
 const { body, param } = require('express-validator')
 
 const account = require('../admin/account.controller')
+const shard = require('./shard.controller')
 const { requireAuth, requireRole } = require('../../../auth/session.middleware')
 const noindex = require('../../../middleware/noindex')
 const validate = require('../../../middleware/validate')
@@ -129,4 +130,57 @@ playerRouter.delete(
   account.unlinkIdentity,
 )
 
+// ── Game account linking (uo-link) ─────────────────────────────────────────
+// Link an in-game account with a one-time code from [link, then read the
+// account's roster / vendors (ownership-checked against the local link mirror).
+const ACCOUNT_RE = /^[A-Za-z0-9_.-]{1,120}$/
+playerRouter.post(
+  '/shard/link',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'Link an in-game account with a one-time code'
+  // #swagger.description = 'The player runs [link in game to get a code, then submits it here. The server confirms it with the sidecar and mirrors the link.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Linked', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkResult" } } } } */
+  /* #swagger.responses[400] = { description: 'Unknown or expired code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  body('code').isString().trim().isLength({ min: 4, max: 32 }),
+  validate,
+  shard.link,
+)
+playerRouter.get(
+  '/shard/accounts',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'List the caller’s linked game accounts'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Linked accounts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardLink" } } } } } */
+  shard.listAccounts,
+)
+playerRouter.get(
+  '/shard/roster/:account',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'Character roster for a linked account'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' }
+  /* #swagger.responses[200] = { description: 'Account roster', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('account').matches(ACCOUNT_RE),
+  validate,
+  shard.roster,
+)
+playerRouter.get(
+  '/shard/vendors/:account',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'Player vendors for a linked account'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' }
+  /* #swagger.responses[200] = { description: 'Vendor snapshot', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('account').matches(ACCOUNT_RE),
+  validate,
+  shard.vendors,
+)
+
 module.exports = playerRouter