add /api/auth short-path endpoints (token/session) + swagger group "auth"

- POST /api/auth/token = alias of /api/documents/token (docver access_token,
  both x-api-key and ticket entrances)
- POST /api/auth/session = alias of /api/note/auth/session (exchange e-Court
  link credential for note login token, 8h TTL)
- lib/openapi.ts: new "auth" tag + both paths + SessionExchangeRequest /
  SessionResponse schemas (session endpoint had never been documented)
- tests/lib/openapi.test.ts: guard all $refs resolve + auth paths exist

Co-Authored-By: Claude Code <noreply@anthropic.com>

app/api/auth/token/route.ts

@@ -0,0 +1,113 @@
+// PLAN-DOCVER.md §auth — POST /api/auth/token (path สั้นของ POST /api/documents/token
+// — โค้ดก้อนเดียวกัน copy มา 2026-11-05) ออก access_token ของกลุ่ม docver
+// ทางเข้า 2 ทาง (PLAN-ADDIN-AUTH.md §3 — header x-api-key เป็นตัวตั้ง):
+//  1) e-Court server-to-server: header "x-api-key" เทียบ env DOCVER_API_KEY
+//     (fail closed เมื่อ env ไม่ตั้ง/ว่าง) + body claims ตรง ๆ (เดิมทุกอย่าง)
+//  2) add-in ใน Word: ไม่มี x-api-key + body {ticket_data, HmacSha256} — server
+//     ตรวจ HMAC ด้วย env ฝั่ง server (ADDIN_TICKET_SECRET → SECRET →
+//     "super_secret", lib/addin-ticket.ts) แล้วออก token จาก claims ของ ticket
+//     (secret ตัวเซ็น JWT ไม่มีทางไปอยู่ใน bundle ของ add-in — client ไม่ตรวจ HMAC
+//     เองแล้วตาม PLAN-SSO.md D13) · contract 2026-11-04: 400 = ฟอร์แม็ตพัง
+//     (รวม missing) / 401 = ลายเซ็นไม่ถูก / 403 = ลายเซ็นถูกแต่ ticket หมดอายุ
+//     (client ที่มี JWT เดิมของ fid นี้ใน session ใช้ต่อเอง — ไม่มีการออกซ้ำ
+//     จากหลักฐาน DB อีกต่อไป เลิก requirement ขั้น 7 ฉบับ 2026-10-28)
+// ทั้งสองทางออก JWT HS256 เซ็นด้วย env DOCVER_TOKEN_SECRET อายุตาม env
+// DOCVER_TOKEN_TTL_SECONDS (default 604800 = 7 วัน — token อายุยาวแทนระบบ
+// refresh/renew) แล้วนำไปแนบ Authorization: Bearer กับ endpoint อื่นของกลุ่ม
+// (lib/docver-token.ts) · segment คงที่ "token" ไม่ชน [docId]
+// (Next ให้ static ชนะ) และ middleware ยกเว้น api/documents/* อยู่แล้ว
+import { docverError } from "@/lib/document-versioning";
+import {
+  addinTicketSecret,
+  parseTicketTokenBody,
+  ticketToDocverClaims,
+  verifyAddinTicketHmac,
+} from "@/lib/addin-ticket";
+import { isTicketExpired } from "@/utils/docver-ticket";
+import {
+  issueDocverToken,
+  parseTokenRequestBody,
+  requireDocverApiKey,
+  type DocverTokenClaims,
+} from "@/lib/docver-token";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+/** 401 ของทางเข้า ticket — ข้อความเดียวทุกสาเหตุ (HMAC ผิด/รูปผิด) กัน oracle · หมดอายุแยกเป็น 403 */
+const TICKET_DENIED = "ticket ไม่ถูกต้อง";
+/** 403 ของทางเข้า ticket — ลายเซ็นถูกแต่หมดอายุ (client มี JWT เดิมใน session ก็ใช้ต่อได้) */
+const TICKET_EXPIRED = "ticket ของ e-Court หมดอายุ";
+
+export async function POST(request: Request) {
+  return request.headers.get("x-api-key") !== null
+    ? postWithApiKey(request)
+    : postWithTicket(request);
+}
+
+/** ทางเข้า 1 (เดิม) — e-Court server-to-server */
+async function postWithApiKey(request: Request): Promise<Response> {
+  const apiKeyFail = requireDocverApiKey(request);
+  if (apiKeyFail !== null) return apiKeyFail;
+
+  let raw: unknown;
+  try {
+    raw = await request.json();
+  } catch {
+    return docverError("body ต้องเป็น JSON", 400);
+  }
+  const parsed = parseTokenRequestBody(raw);
+  if (!parsed.ok) return docverError(parsed.error, 400);
+  return issueToken(parsed.claims);
+}
+
+/** ทางเข้า 2 — add-in ส่ง ticket ที่ e-Court stamp มากับไฟล์ */
+async function postWithTicket(request: Request): Promise<Response> {
+  let raw: unknown;
+  try {
+    raw = await request.json();
+  } catch {
+    return docverError("body ต้องเป็น JSON", 400);
+  }
+  const parsed = parseTicketTokenBody(raw);
+  if (!parsed.ok) {
+    // contract 2026-11-04: ฟอร์แม็ตพัง = 400 ทั้ง missing/invalid (เดิม missing เป็น 401)
+    return docverError(parsed.error, 400);
+  }
+  // ตรวจ HMAC ก่อนเสมอ (ตัวตนของผู้ถือไฟล์) — exp ไม่ใช่เกณฑ์ตัดสิทธิ์ ณ จุดนี้
+  const verified = verifyAddinTicketHmac(parsed.ticketData, parsed.hmacHex, addinTicketSecret());
+  if (!verified.ok) return docverError(TICKET_DENIED, 401);
+
+  // ลายเซ็นถูกแต่ ticket หมดอายุ → 403 เสมอ (contract 2026-11-04 — เลิก requirement
+  // ขั้น 7 ฉบับ 2026-10-28: ไม่ตรวจ hasVersionByUser อีกต่อไป เพราะ ticket ฝังอยู่ใน
+  // ไฟล์ ใครได้ไฟล์ก็ได้ ticket การปล่อยให้ ticket เก่าแลก token ใหม่ได้ตลอดไป
+  // เท่ากันคือปล่อยสิทธิ์ตามการครอบครองไฟล์ — ฝั่ง client ที่มี JWT ของ fid นี้
+  // ใน session ที่ยังไม่หมด (7 วัน) ใช้ต่อเอง ไม่มี = ขอไฟล์ใหม่จาก e-Court)
+  if (isTicketExpired(verified.ticket.exp)) {
+    return docverError(TICKET_EXPIRED, 403);
+  }
+  return issueToken(ticketToDocverClaims(verified.ticket));
+}
+
+/** ออก JWT ของ claims ที่ผ่านการยืนยันแล้วจากทั้งสองทาง — ส่วนกลาง */
+async function issueToken(claims: DocverTokenClaims): Promise<Response> {
+  // ความผิด config ฝั่ง server ไม่ใช่ความผิดของผู้เรียก — ไม่ตั้ง = 500 (ห้าม log ค่า secret)
+  const secret = process.env.DOCVER_TOKEN_SECRET?.trim();
+  if (secret === undefined || secret === "") {
+    return docverError("DOCVER_TOKEN_SECRET ยังไม่ถูกตั้งค่า", 500);
+  }
+  const ttlRaw = Number(process.env.DOCVER_TOKEN_TTL_SECONDS);
+  // default 7 วัน (2026-11-04) — token อายุยาวแทนระบบ refresh/renew ของ add-in
+  const ttlSeconds =
+    Number.isFinite(ttlRaw) && ttlRaw > 0 ? Math.floor(ttlRaw) : 604_800;
+
+  const accessToken = issueDocverToken(claims, secret, ttlSeconds);
+  return new Response(
+    JSON.stringify({
+      access_token: accessToken,
+      token_type: "Bearer",
+      expires_in: ttlSeconds,
+    }),
+    { headers: { "content-type": "application/json; charset=utf-8" } },
+  );
+}