Merge branch 'forgejo-dev' into working

Resolve CLAUDE.md: คำอธิบาย lib/document-versioning.ts เอาของ
forgejo-dev (field `fields` ถอดออก 2026-10-30) ส่วน lib/docver-token.ts
เอาของ working (purpose login / verifyDocverLoginToken — โค้ดฝั่ง
forgejo-dev มีครบแล้ว แค่คำอธิบายล้าหลัง)

Verify: npx tsc --noEmit ผ่าน · vitest 23 files / 338 tests ผ่าน

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

app/api/documents/latest/route.ts

@@ -0,0 +1,120 @@
+// PLAN-DOCVER.md §1 — GET /api/documents/latest?type=docx|pdf&ticket_data=<json>
+// คืนไฟล์ของ version ล่าสุดให้ backend e-Court (server-to-server):
+// - type=pdf → ไบต์ pdf ตรง ๆ (version ล่าสุดไม่มี pdf = 404)
+// - type=docx → stamp ticket ใหม่ (exp + HmacSha256 + Ed25519 เมื่อมี private key)
+//   ลงสำเนาในหน่วยความจำก่อนคืน — ไม่เขียนกลับ MinIO (non-destructive)
+// - auth: header x-api-key เทียบ env DOCVER_API_KEY หรือ EXTERNAL_API_KEY
+//   (ต่างจาก /token ที่รับ DOCVER_API_KEY อย่างเดียว) · docId = fid ใน ticket_data
+// - secret ของ HMAC = addinTicketSecret() ให้ตรงฝั่ง verify ของ add-in /
+//   POST /api/documents/token ทาง ticket · TTL = env TICKET_SEC (default 300)
+// carve-out invariant #4: route handler ของกลุ่ม docver — ไม่ publish SSE
+// ไม่ revalidatePath (ไม่มีหน้า note ใดอ่านตารางของกลุ่มนี้)
+import { addinTicketSecret } from "@/lib/addin-ticket";
+import {
+  contentDispositionValue,
+  docverError,
+  DOCX_CONTENT_TYPE,
+  isDocxBytes,
+  isPdfBytes,
+  parseLatestTypeParam,
+  PDF_CONTENT_TYPE,
+} from "@/lib/document-versioning";
+import { requireDocumentApiKey } from "@/lib/docver-token";
+import {
+  findLatestVersionForDoc,
+  getVersionObjectBytes,
+} from "@/lib/docver-store";
+import { buildStampedTicketData, stampTicketProps } from "@/lib/lib-tmpl";
+import { parseTicketDataParam } from "@/utils/docver-ticket";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const GENERIC_500 = "เกิดข้อผิดพลาดของระบบ โปรดลองใหม่อีกครั้ง";
+
+export async function GET(request: Request) {
+  const auth = requireDocumentApiKey(request);
+  if (auth !== null) return auth;
+
+  let searchParams: URLSearchParams;
+  try {
+    searchParams = new URL(request.url).searchParams;
+  } catch {
+    return docverError("URL ของ request ไม่ถูกต้อง", 400);
+  }
+
+  const type = parseLatestTypeParam(searchParams.get("type"));
+  if (!type.ok) return docverError(type.error, 400);
+
+  const ticket = parseTicketDataParam(searchParams.get("ticket_data"));
+  if (!ticket.ok) return docverError(ticket.error, 400);
+
+  // เติม exp + เรียง key + เช็คความยาวก่อนแตะ MinIO — Word ตัดทอนค่า custom
+  // property ที่ 255 ตัวอักษร คืนไฟล์ที่โดนตัด = HMAC เสียเงียบ ๆ ปฏิเสธไปเลยดีกว่า
+  let ticketData: string | null = null;
+  if (type.type === "docx") {
+    const ttl = Number(process.env.TICKET_SEC);
+    const ttlSeconds = Number.isFinite(ttl) && ttl > 0 ? ttl : 300;
+    ticketData = buildStampedTicketData(ticket.ticket, ttlSeconds);
+    if (ticketData.length > 255) {
+      return docverError(
+        "ticket_data ยาวเกิน 255 ตัวอักษร (ข้อจำกัดของ Word custom property)",
+        400,
+      );
+    }
+  }
+
+  let row;
+  try {
+    row = await findLatestVersionForDoc(ticket.ticket.fid);
+  } catch (err) {
+    console.error("docver: ค้น version ล่าสุดล้ม", err);
+    return docverError(GENERIC_500, 500);
+  }
+  if (!row) {
+    return docverError("ไม่พบเอกสารนี้ในระบบ (ยังไม่เคยอัปโหลด version)", 404);
+  }
+  if (type.type === "pdf" && row.pdfObjectKey === null) {
+    return docverError("version นี้ไม่มีสำเนา PDF", 404);
+  }
+
+  let bytes: Buffer;
+  try {
+    bytes = await getVersionObjectBytes(row.id, type.type);
+  } catch (err) {
+    console.error("docver: ดึง object จาก MinIO ล้ม", err);
+    return docverError(GENERIC_500, 500);
+  }
+  // object เขียนผ่านกลุ่มนี้เองตอน upload (ผ่าน magic bytes แล้ว) — ไม่ตรงตอนนี้
+  // = ความผิดปกติของพื้นที่เก็บ ไม่ใช่ความผิดของผู้เรียก จึงเป็น 500
+  if (type.type === "docx" ? !isDocxBytes(bytes) : !isPdfBytes(bytes)) {
+    console.error(`docver: object ของ version ${row.id} magic bytes ไม่ตรงชนิดไฟล์`);
+    return docverError(GENERIC_500, 500);
+  }
+
+  if (type.type === "docx") {
+    // ticketData ถูกตั้งค่าแล้วเสมอเมื่อ type=docx (ด้านบน) — ห้ามกลืน error:
+    // ไฟล์ไม่มี stamp = add-in เปิดไม่ได้ ต้องตอบ 500 ไม่ใช่คืนไฟล์เสียเงียบ ๆ
+    try {
+      bytes = stampTicketProps(bytes, ticketData!, {
+        secret: addinTicketSecret(),
+        privateKeyHex: process.env.PRIVATE_KEY_HEX?.trim() || null,
+      }).buffer;
+    } catch (err) {
+      console.error("docver: stamp ticket ล้ม", err);
+      return docverError(GENERIC_500, 500);
+    }
+  }
+
+  return new Response(
+    // Uint8Array ใหม่ (ก็อปปี้) ตามที่ BodyInit รับ — pattern เดียวกับ route pdf/export
+    new Uint8Array(bytes),
+    {
+      headers: {
+        "content-type": type.type === "docx" ? DOCX_CONTENT_TYPE : PDF_CONTENT_TYPE,
+        "content-disposition": contentDispositionValue(row.fileName, type.type),
+        "cache-control": "no-store, max-age=0",
+      },
+    },
+  );
+}

app/api/documents/versions/route.ts

@@ -6,7 +6,8 @@
 // ไม่รับจาก URL/form อีก (lib/docver-token.ts)
 import { createHash, randomUUID } from "node:crypto";
 
-import { toDocumentVersionDTO } from "@/db/schema";
+import { toDocumentVersionDTO, type DocumentVersionFields } from "@/db/schema";
+import { addinTicketSecret } from "@/lib/addin-ticket";
 import {
   docverError,
   DOCVER_MAX_UPLOAD_BYTES,
@@ -16,7 +17,9 @@ import {
   parseVersionUploadForm,
   sanitizeFilePartName,
 } from "@/lib/document-versioning";
+import { extractContentControls } from "@/lib/lib-tmpl";
 import { requireDocverBearer } from "@/lib/docver-token";
+import { extractDocumentSnapshot } from "@/lib/lib-tmpl";
 import {
   findDocumentByDocId,
   insertVersionRecord,
@@ -31,6 +34,7 @@ export const dynamic = "force-dynamic";
 
 /** POST — อัปโหลด version ใหม่ (เอกสารสร้างแบบ implicit ถ้าเป็น version แรก)
  *  ลำดับ: Bearer token → validate text field ก่อนแตะไฟล์ → cap ขนาดก่อน buffer → magic bytes →
+ *  แกะ fields จากไฟล์ (lib-tmpl เหมือน /api/template/extract) →
  *  putObject MinIO → insert DB (tx) — DB ล้ม = เก็บกวาด object (pattern N4)
  *  response = UploadVersionResult เป๊ะ โดย versionNumber เป็นค่า authoritative
  *  จาก server (client เดา latest+1 แล้วแก้เองเมื่ออัปโหลดชนกัน) */
@@ -92,6 +96,21 @@ export async function POST(request: Request) {
     return docverError("เนื้อไฟล์ .pdf ไม่ถูกต้อง", 400);
   }
 
+  // fields snapshot แกะจากไฟล์เองฝั่ง server — **เก็บทั้งก้อนเหมือน return ของ
+  // /api/template/extract** ({cc, bookmark, properties, verify} ผ่าน extractDocumentSnapshot
+  // ของ lib/lib-tmpl.ts ตัวเดียวกับ route นั้น — 2026-10-30 ถอด form field "fields"
+  // ที่ add-in อ่านผ่าน Office.js ออกจาก contract): มองเห็น CC ทุกชนิดเสมอไม่ขึ้นกับ
+  // เวอร์ชัน WordApi ของ host · verify.HmacSha256 ตรวจด้วย secret ของ add-in ticket
+  // ฝั่ง server (env chain เดียวกับ lib/addin-ticket.ts) · ZIP ไม่มี word/document.xml,
+  // parse ไม่ได้ หรือ ticket_data ไม่ใช่ JSON = 400
+  let fields: DocumentVersionFields;
+  try {
+    fields = extractDocumentSnapshot(docxBytes, { secret: addinTicketSecret() });
+  } catch (err) {
+    console.error("docver: แกะข้อมูลจากไฟล์ไม่สำเร็จ", err);
+    return docverError("เนื้อไฟล์ .docx ไม่ถูกต้อง (แกะข้อมูลไม่สำเร็จ)", 400);
+  }
+
   const contentHash = createHash("sha256").update(docxBytes).digest("hex");
   const versionId = randomUUID();
   // ชื่อแสดงผลตอนดาวน์โหลด: field "fileName" ของผู้เรียก (add-in ส่งมาเอง) →
@@ -119,7 +138,7 @@ export async function POST(request: Request) {
       clientVersionId: parsed.form.clientVersionId,
       contentHash,
       message: parsed.form.message,
-      fields: parsed.form.fields,
+      fields,
       templateId: auth.claims.template,
       fileName: docxDisplayName,
       docxObjectKey: keys.docx,

app/api/template/download-docx/route.ts

@@ -1,46 +1,79 @@
 // ตัวอย่างรองรับค่าจาก Frontend ที่เป็น Vanilla JavaScript และ Classic Framework 
-// โดย ผ่าน Form หรือ การกดลิงค์(GET) เปลี่ยนหน้าเพื่อดาว์นโหลดไฟล์ 
+// โดย ผ่าน Form(POST) หรือ การกดลิงค์(GET) เปลี่ยนหน้าเพื่อดาว์นโหลดไฟล์ 
 // จะมีข้อมูล info.ticket_data ที่สมบูรณ์แล้ว({fid,tid,uid,uname})แล้วเเรียก /api/template/generate เพื่อสร้างเอกสาร docx
+
+// import { headers } from "next/headers";
 import { NextRequest, NextResponse } from 'next/server';
+
 import path from 'path';
 import fs from 'fs/promises';
-
-const DOCEDIT_BASE_URL = process.env.DOCEDIT_BASE_URL??""; 
-const EXTERNAL_API_KEY  = process.env.EXTERNAL_API_KEY??"";
-const TMPL_PATH        = process.env.TMPL_PATH??"";
-if (!DOCEDIT_BASE_URL||!EXTERNAL_API_KEY||!TMPL_PATH) {
-  console.error('Missing variable DOCEDIT_BASE_URL, EXTERNAL_API_KEY or TMPL_PATH')
-}
-
-// console.log("download-docx env",DOCEDIT_BASE_URL,EXTERNAL_API_KEY,TMPL_PATH)
+const EXTERNAL_API_KEY  = process.env.EXTERNAL_API_KEY||'';
+const TMPL_PATH        = process.env.TMPL_PATH || "./public/tmpl";
+const DOCEDIT_BASE_URL = process.env.DOCEDIT_BASE_URL || ''; 
 
 async function processRequest(fid: string,tid:string,uid:string,uname:string):Promise<NextResponse<unknown>>
 {
-  // console.log("processRequest get:",fid,tid,uid,uname)
-  // console.log(process.cwd())
-  const filePath = path.join(TMPL_PATH,`${fid}.json`);
-  try {
-    if (!fid||!tid||!uid||!uname) {
-      return NextResponse.json({ error: 'Missing fid, tid, uid or uname' }, { status: 400 });
-    }
+  //กัน path traversal attack
+  const TID = path.basename(tid)
+  const FID = path.basename(fid)
+  const ticketObj = {fid:FID,tid:TID,uid,uname}
+  const ticket_data = JSON.stringify({fid:FID,tid:TID,uid,uname})
+  const filePath = path.join(TMPL_PATH,`${FID}.json`);
+  // สำหรับการ demo ในแอปเดียวเท่านั้น สามารถคำนวนหา base path ได้ด้วยวิธีนี้
+  // const host = headers().get("host"); // e.g., localhost:3000
+  // const proto = headers().get("x-forwarded-proto") || "http"; 
+  // const baseUrl = process.env.NEXT_PUBLIC_BASE_PATH || ""
+  // const fullUrl = `${proto}://${host}${baseUrl}`;
+  // const DOCEDIT_BASE_URL = process.env.DOCEDIT_BASE_URL || fullUrl; 
+  if(!DOCEDIT_BASE_URL || !EXTERNAL_API_KEY) {
+    return NextResponse.json({ error: 'Server must set Environment variable DOCEDIT_BASE_URL or EXTERNAL_API_KEY' }, { status: 500 });
+  }
+  if (!FID||!TID||!uid||!uname) {
+    return NextResponse.json({ error: 'Missing fid, tid, uid or uname' }, { status: 400 });
+  }
 
-    // อ่านไฟล์ JSON จำลองการอ่านจากฐานข้อมูล
+
+  try { //ตรวจสอบ docx เวอร์ชั่นล่าสุดก่อนถ้าไม่พบค่อยเอาจากฐานข้อมูลมาสร้าง raw Json
+    const params = new URLSearchParams({type:'docx',ticket_data});
+    const lastestDocxResponse = await fetch(`${DOCEDIT_BASE_URL}/api/document/latest?${params.toString()}`, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': EXTERNAL_API_KEY,
+      }
+    });
+   
+    if(!lastestDocxResponse.ok && lastestDocxResponse.status !== 404){//เกิดปัญหาที่ไม่ใช่ Not Found
+      const errorText = await lastestDocxResponse.text();
+      console.error('download-docx:Invalid latest docx Response:', errorText);
+      return NextResponse.json(
+        {error:`Error from docedit latest: Expected docx stream but received ${lastestDocxResponse.status} ${lastestDocxResponse.statusText}`},
+        { status: 502 }
+      );
+    }
+  } catch (error) {
+    console.error(error)
+    return NextResponse.json({error:'Internal Server Error'}, { status: 500 });
+  }  
+  console.log('No version found, generating docx from template and JSON data...');
+
+  try { // ไม่พบเวอร์ชั้นให้สร้าง docx จาก template และ json(ฐานข้อมูล)
+    // อ่านไฟล์ JSON จำลองการอ่านจากฐานข้อมูล 
     const rawJson = await fs.readFile(filePath, 'utf-8');
     const jsonData = JSON.parse(rawJson);
     if (!jsonData || typeof jsonData !== 'object' ) {
       return NextResponse.json({error:'Invalid data format'}, { status: 400 });
     }
+    /////// !! ตรวจสอบสิทธิ์ผู้ใช้ uid ว่ามีสิทธิ์เข้าถึงไฟล์ fid หรือไม่เพื่อกันการการยิง API ตรงๆ ไม่ผ่าน Frontend !!// 
+    ///////  ไม่มี session return 401, ถ้าเจอแต่ไม่มีสิทธิ์ให้ return 403 , อ่านจากฐานข้อมูล ถ้าไม่พบข้อมูลให้ return 404, 
 
-    //!! ตรวจสอบสิทธิ์ผู้ใช้ uid ว่ามีสิทธิ์เข้าถึงไฟล์ fid หรือไม่เพื่อกันการการยิง API ตรงๆ ไม่ผ่าน Frontend!!
-
-    // ข้อมูลจำเป็นต้องมี prop นี้เสมอถ้าไม่มีให้สร้าง jsonData.info.ticket_data 
+    // ข้อมูลจำเป็นต้องมี jsonData.info.ticket_data ถ้าไม่มีให้สร้างขึ้นมาเอง
     if(!Object.hasOwn(jsonData, 'info'))
       jsonData['info']={}
-    jsonData.info['ticket_data'] = JSON.stringify({fid,tid,uid,uname})
+    jsonData.info['ticket_data'] = JSON.stringify(ticketObj)
     // sign เองตรงนี้ให้อยู่ในรูปแบบ data.info={ticket_data,HmacSha256,Ed25519} หรือว่างไว้ให้ docedit สร้างให้ 
 
     //ยิงไปหาระบบ Docedit เพื่อเอา Stream
-    // console.log(`fetch ${DOCEDIT_BASE_URL}/api/template/generate`)
     const docxResponse = await fetch(`${DOCEDIT_BASE_URL}/api/template/generate`, {
       method: 'POST',
       headers: {
@@ -52,7 +85,6 @@ async function processRequest(fid: string,tid:string,uid:string,uname:string):Pr
 
     // เช็ค Content-Type และ Status  ก่อน
     const contentType = docxResponse.headers.get('content-type') || '';
-
     if (!docxResponse.ok || contentType.includes('text/html')) {
       const errorText = await docxResponse.text();
       console.error('download-docx:Invalid docx Response:', errorText);
@@ -65,9 +97,8 @@ async function processRequest(fid: string,tid:string,uid:string,uname:string):Pr
 
     // 2. ดึง ReadableStream โดยตรงจาก Response ของระบบ
     const stream = docxResponse.body;
-
     // 3. ส่ง Binary Stream กลับไปยัง Browser พร้อม Header กำหนดประเภทไฟล์
-    const download_file = `${fid}_${uid}_xxx`
+    const download_file = `${FID}_${uid}_xxx`
     return new NextResponse(stream as unknown as BodyInit, {
       status: 200,
       headers: {
@@ -78,7 +109,7 @@ async function processRequest(fid: string,tid:string,uid:string,uname:string):Pr
       },
     });
   } catch (error:any) {
-    if ( error.code === 'ENOENT') {
+    if ( error.code === 'ENOENT') {// ไฟล์ JSON ไม่พบ ถ้าใช้ฐานข้อมูลจริงให้ return 404 แทน
       return NextResponse.json(
         { error: `Data not found: ${filePath}`},
         { status: 404 }

app/api/template/extract/route.ts

@@ -1,6 +1,5 @@
 import { NextResponse } from "next/server";
-import { extractContentControls, extractBookmark, templateContentControls, setCustomDocProps, getDocProps,templateDynamicContents } from "@/lib/lib-tmpl";
-import { verifyEd25519, verifyHmacSha256 } from "@/lib/lib-utils";
+import { extractDocumentSnapshot } from "@/lib/lib-tmpl";
 // export const runtime = "nodejs";
 
 const DOCX_CONTENT_TYPE =
@@ -40,32 +39,13 @@ export async function POST(request: Request) {
     // File → Buffer
     const buffer = Buffer.from(await file.arrayBuffer());
 
-    // ใช้ lib-tmpl.ts เดิม
-    // const data = extractContentControls(buffer);
-
-    const cc = extractContentControls(buffer);
-    const bookmark = extractBookmark(buffer)
-    const properties = getDocProps(buffer)
-    let verify: Record<string, unknown> ={}
-    const ticket_data = properties?.custom?.ticket_data
-    const HmacSha256 = String(properties?.custom?.HmacSha256)
-    const Ed25519 = String(properties?.custom?.Ed25519)
-    
-    if(ticket_data && typeof ticket_data === 'string'){
-      const ticketDataObj= JSON.parse(ticket_data)
-      const unix_timestamp = Number(ticketDataObj.exp)*1000
-      if(unix_timestamp){
-        verify['exp'] = new Date(unix_timestamp).toLocaleString("th-TH", { timeZone: "Asia/Bangkok" })
-      }
-      if(TEST_SECRET && HmacSha256){
-        verify['HmacSha256'] = verifyHmacSha256(ticket_data,TEST_SECRET,HmacSha256)
-      }
-      if(TEST_PUBLIC_KEY_HEX&& Ed25519){
-        verify["Ed25519"]=verifyEd25519(ticket_data,Ed25519,TEST_PUBLIC_KEY_HEX)
-      }
-    }
-    
-    let returnData : Record<string, unknown> = {cc,bookmark,properties,verify}
+    // ชุดแกะข้อมูล `{cc, bookmark, properties, verify}` จาก lib-tmpl.ts — ตัวเดียวกับที่
+    // ใช้เก็บเป็น fields ของ version ตอน POST /api/documents/versions (2026-10-30) ·
+    // secret/public_key เป็นของผู้เรียกเพื่อ "ทดสอบ verify" เฉพาะฝั่งนี้
+    const returnData = extractDocumentSnapshot(buffer, {
+      secret: TEST_SECRET || undefined,
+      publicKeyHex: TEST_PUBLIC_KEY_HEX || undefined,
+    });
     return NextResponse.json(returnData);
   } catch (error) {
     console.error(error);

app/api/template/generate/route.ts

@@ -6,25 +6,25 @@ import { NextRequest, NextResponse } from 'next/server';
 import {readFile} from 'fs/promises';
 import path from 'path';
 import {DocumentTemplate,applyTemplate} from "@/lib/lib-tmpl";
+
 const EXTERNAL_API_KEY = process.env.EXTERNAL_API_KEY || 'secret-api-key-1234';
-const TMPL_PATH = process.env.TMPL_PATH || ''
 const PRIVATE_KEY_HEX = process.env.PRIVATE_KEY_HEX ||''
-const SECRET = process.env.SECRET || ''
-const TICKET_SEC = Number(process.env.TICKET_SEC||'300')
-
-if (!EXTERNAL_API_KEY || !TMPL_PATH || !PRIVATE_KEY_HEX || !SECRET)
-  console.log("api/template/generate: require EXTERNAL_API_KEY, TMPL_PATH and PRIVATE_KEY_HEX")
-
-// console.log("generate env:",EXTERNAL_API_KEY,TMPL_PATH,PRIVATE_KEY_HEX,SECRET)
-
+const SECRET = process.env.SECRET || 'super_secret'
+const TMPL_PATH        = process.env.TMPL_PATH || "./public/tmpl";
+const TICKET_SEC = Number(process.env.TICKET_SEC||'120')
 
 export async function POST(request: NextRequest) {
+  if (!EXTERNAL_API_KEY || !PRIVATE_KEY_HEX || !SECRET){
+    return NextResponse.json(
+      { error: 'Server Error: require EXTERNAL_API_KEY PRIVATE_KEY_HEX and SECRET' },
+      { status: 500 }
+    );
+  }
   // 1. ตรวจสอบ API Key จาก HTTP Header (x-api-key)
-  const apiKey = request.headers.get('x-api-key');
-
+  const apiKey = request.headers.get('x-api-key')||'';
   if (!apiKey || apiKey !== EXTERNAL_API_KEY) {
     return NextResponse.json(
-      { error: 'Unauthorized: Invalid API Key' },
+      { error: 'Unauthorized: Invalid API Key ' },
       { status: 401 }
     );
   }
@@ -61,7 +61,7 @@ export async function POST(request: NextRequest) {
     
     
       //เปิดไฟล์ template
-    const tmplPath = path.join(TMPL_PATH, `${tid}.docx`);
+    const tmplPath = path.join(TMPL_PATH, `${path.basename(tid)}.docx`);
     let templateBuffer: Buffer = await readFile(tmplPath)
 
     const output = await applyTemplate(templateBuffer, templateData, SECRET, PRIVATE_KEY_HEX, TICKET_SEC);