ความปลอดภัยและการดำเนินงานของ NextPDF Connect

ภาพรวมโดยย่อ

NextPDF Connect ใช้ API key bearer token เพื่อพิสูจน์ตัวตนบนการขนส่งผ่านเครือข่าย ปฏิบัติต่อการขนส่ง Model Context Protocol (MCP) ภายในเครื่องในฐานะโพรเซสย่อยที่เชื่อถือได้ และบังคับให้เครื่องมือที่มีความเสี่ยงสูงทุกตัวต้องผ่านการยืนยันโดยมนุษย์อย่างชัดแจ้ง หน้านี้อธิบายแบบจำลองการพิสูจน์ตัวตน ความปลอดภัยของการขนส่ง และแบบจำลองภัยคุกคาม

ติดตั้ง

composer require nextpdf/server

ภาพรวมเชิงแนวคิด

เซิร์ฟเวอร์มีขอบเขตความเชื่อถือสามส่วน โดยแต่ละการขนส่งมีหนึ่งขอบเขต

การขนส่ง MCP stdio เป็นโพรเซสย่อยที่ไคลเอนต์ภายในเครื่องเริ่มทำงาน โดยอ่าน JSON-RPC จาก standard input และเขียนคำตอบไปยัง standard output การขนส่งนี้ไม่มี network listener และไม่มี API key แต่สืบทอดความเชื่อถือจากขอบเขตโพรเซสของระบบปฏิบัติการ ซึ่งเป็นแบบจำลองความเชื่อถือที่ข้อกำหนด MCP นิยามไว้สำหรับ stdio ระบบส่งล็อกไปยัง standard error จึงไม่ทำให้สตรีมของโปรโตคอลเสียหาย

การขนส่ง REST และการขนส่ง gRPC ทำงานผ่านเครือข่าย ทั้งสองต้องใช้ API key bearer token ในทุกคำขอ ยกเว้น health probe ที่ไม่ต้องพิสูจน์ตัวตน ทั้งสองการขนส่งใช้ที่เก็บคีย์ รูปแบบคีย์ และการตรวจสอบแบบเวลาคงที่เดียวกัน การขนส่ง gRPC อ่านโทเคนจาก call metadata ส่วน REST อ่านโทเคนจากเฮดเดอร์ Authorization ของคำขอ

การพิสูจน์ตัวตนที่ไม่ถูกต้องคือความล้มเหลวที่ OWASP Application Programming Interface (API) Security Top 10 ระบุไว้เป็น API2:2023 Broken Authentication ข้อบกพร่องด้านนี้บั่นทอนความสามารถของ API ในการระบุตัวผู้เรียก และส่งผลต่อความปลอดภัยโดยรวมของ API (OWASP API Security Top 10, API2:2023) โทเคนที่อ่อนแอหรือคาดเดาได้ก็ถูกระบุว่าเป็น anti-pattern ของ broken-auth เช่นกัน (แหล่งเดียวกัน รายการช่องโหว่) การออกแบบด้านล่างนี้จัดการความเสี่ยงทั้งสองกรณี

พื้นผิว API

รูปแบบและการตรวจสอบ API key

คีย์มีรูปแบบเป็น npk_live_{kid}_{secret} โดย kid เป็นตัวระบุยาวแปดอักขระสำหรับค้นหาเรกคอร์ดแบบ O(1) และส่วน secret เก็บค่าเอนโทรปี ที่เก็บคีย์ไม่เคยเก็บคีย์ดิบไว้ แต่เก็บ SHA-256 digest ของวัสดุคีย์ทั้งหมด ในแต่ละคำขอ เซิร์ฟเวอร์จะแฮชโทเคนที่ส่งมา แล้วเปรียบเทียบกับ digest ที่เก็บไว้ด้วยการเปรียบเทียบแบบเวลาคงที่ (hash_equals) คีย์ที่ไม่ถูกต้องจึงไม่เปิดเผยข้อมูลผ่านจังหวะเวลา คีย์ที่ปิดใช้งานแล้วหรือหมดอายุจะถูกปฏิเสธหลังการตรวจสอบแฮช ไม่ใช่ก่อนหน้านั้น

ตัวตรวจสอบ REST และ gRPC ใช้ตรรกะนี้ร่วมกัน มิดเดิลแวร์ REST อ่าน Authorization: Bearer npk_live_… ตัวพิสูจน์ตัวตนของ gRPC อ่าน bearer token เดียวกันจาก call metadata authorization ของ gRPC ซึ่งถูกส่งในรูปเฮดเดอร์ HTTP/2 และทำให้การเรียกล้มเหลวด้วยสถานะ UNAUTHENTICATED ของ gRPC

การขนส่งทั้งสองยังใช้การจำกัดอัตราเพื่อต้านระบบอัตโนมัติกับทราฟฟิกก่อนการพิสูจน์ตัวตนด้วย กล่าวคือ ความพยายามที่มากเกินไปจากตัวตนไคลเอนต์เดียวกันจะถูกจำกัดอัตราและปฏิเสธ โดย REST คืน 429 Too Many Requests ส่วน gRPC คืนสถานะ RESOURCE_EXHAUSTED ของ gRPC การควบคุมนี้เปิดใช้เป็นค่าเริ่มต้น จึงปกป้องการนำไปใช้งานที่ยังไม่ได้กำหนดค่าที่เก็บข้อมูลการจำกัดอัตราแยกต่างหาก ไคลเอนต์ควรถอยเป็นจังหวะแทนที่จะลองใหม่ทันที

การตอบสนองเมื่อไม่ได้รับอนุญาต

คำขอ REST ที่ไม่มีคีย์ คีย์ผิดรูปแบบ คีย์ถูกปิดใช้งาน หรือคีย์หมดอายุ จะได้รับ 401 Unauthorized พร้อมเนื้อหาแบบ problem-details และเฮดเดอร์การตอบสนอง WWW-Authenticate: Bearer ลักษณะนี้สอดคล้องกับข้อกำหนดของ HTTP ที่ระบุว่าการตอบสนอง 401 ต้อง (MUST) มีเฮดเดอร์ฟิลด์ WWW-Authenticate พร้อม challenge อย่างน้อยหนึ่งรายการ (RFC 9110 §11.6.1) ข้อกำหนดนี้ต่อเนื่องจากกฎที่ว่าคำขอที่ละเว้นข้อมูลรับรองหรือมีข้อมูลรับรองไม่ถูกต้องควรได้รับ 401 พร้อม challenge WWW-Authenticate (RFC 9110 §11.6)

สิทธิ์การใช้งานของคีย์

เรกคอร์ดคีย์แต่ละรายการมีระดับ tier ผลิตภัณฑ์สูงสุดกำกับอยู่ ไปป์ไลน์ REST จะแนบตัวตนและ tier ของไคลเอนต์ที่ผ่านการพิสูจน์ตัวตนไปกับคำขอ การให้สิทธิ์ในขั้นถัดไปจึงสามารถบังคับใช้เพดานความสามารถและขนาดเพย์โหลดตาม tier ได้ คีย์ระดับ core ไม่สามารถรันการดำเนินงานของ Pro หรือ Enterprise ได้ แม้ว่าจะติดตั้งแพ็กเกจเหล่านั้นไว้แล้วก็ตาม

กรณีขอบและข้อควรระวัง

การขนส่ง MCP ไม่มี API key นี่เป็นพฤติกรรมที่ตั้งใจและถูกต้องสำหรับโพรเซสย่อยภายในเครื่อง อย่าเปิดเผยเซิร์ฟเวอร์ MCP ผ่าน network shim หากเอเจนต์บนเครือข่ายต้องการใช้เครื่องมือเหล่านี้ ให้เปิดผ่านการขนส่ง REST หรือ gRPC ซึ่งมีการพิสูจน์ตัวตน
Health probe ยอมให้เรียกแบบไม่ระบุตัวตนโดยเจตนา /healthz และ /readyz ข้ามการพิสูจน์ตัวตน เพื่อให้ตัวประสานงานตรวจสอบ liveness และ readiness ได้โดยไม่ต้องใช้ข้อมูลรับรอง เอนด์พอยต์เหล่านี้คืนเฉพาะสถานะเท่านั้น และไม่เปิดเผยข้อมูลเครื่องมือหรือข้อมูลเอกสารใด ๆ
โทเคนยืนยันเป็นแบบใช้ครั้งเดียวและมีอายุสั้น ประตู human-in-the-loop ออกโทเคนที่ผูกกับชื่อเครื่องมือ โดยมีอายุ 300 วินาที โทเคนจะถูกใช้ไปเมื่อมีการใช้งานครั้งแรก โทเคนไม่ใช่ข้อมูลรับรองสำหรับการพิสูจน์ตัวตน และใช้แทน API key ไม่ได้

ประสิทธิภาพ

การพิสูจน์ตัวตนมีต้นทุนเพียงการแฮชหนึ่งครั้งและการเปรียบเทียบแบบเวลาคงที่ต่อหนึ่งคำขอ ต้นทุนนี้แทบไม่มีนัยสำคัญเมื่อเทียบกับต้นทุนการเรนเดอร์ ที่เก็บคีย์ซึ่งรองรับ hot-reloading จะอ่านไฟล์คีย์ใหม่เมื่อไฟล์เปลี่ยนแปลง การหมุนคีย์จึงไม่ต้องรีสตาร์ตและไม่เพิ่มต้นทุนต่อคำขอ

หมายเหตุด้านความปลอดภัย

ประตู human-in-the-loop

เครื่องมือทุกตัวประกาศระดับความเสี่ยง เครื่องมือที่อยู่ในระดับสูงสุดคือ ApprovalRequired จะไม่ทำงานในการเรียกครั้งแรก ประตูการยืนยันจะคืน challenge ที่มีโทเคนแบบใช้ครั้งเดียว เอเจนต์ต้องแสดง challenge ต่อมนุษย์ แล้วเรียกเครื่องมือซ้ำพร้อมโทเคน การควบคุมนี้ตั้งใจทำงาน ณ จุดที่การกระทำอัตโนมัติก่อให้เกิดความเสี่ยง ซึ่งสอดคล้องกับจุดที่ IEC 31010 ระบุไว้สำหรับการควบคุมความเสี่ยงที่เกิดจากการกระทำของมนุษย์ (ในที่นี้คือเอเจนต์) ณ จุดที่เกิดความเสี่ยงหรือใกล้จุดนั้น (IEC 31010:2019) การกำหนดค่าไม่สามารถทำให้ประตูอ่อนแอลงได้ การกำหนดค่าทับ (override) ทำได้เพียงยกระดับความเสี่ยงของเครื่องมือ และไม่สามารถลดระดับเครื่องมือ ApprovalRequired ได้ ดู /connect/hitl-risk-tiers/

การกำหนดค่าความปลอดภัยของการขนส่ง

การขนส่งบนเครือข่ายไม่ได้ทำหน้าที่ terminate Transport Layer Security (TLS) ด้วยตนเอง TLS เป็นเรื่องของการนำไปใช้งาน การนำไปใช้งานแบบรวมที่ใช้อ้างอิงรันการขนส่ง gRPC ด้วย mutual TLS โดยจัดเตรียมคีย์ ใบรับรอง และ client CA เป็นความลับของการนำไปใช้งาน ภายใต้ mutual TLS เซิร์ฟเวอร์จะแสดงใบรับรอง และบังคับใช้พร้อมตรวจสอบใบรับรองของไคลเอนต์ ให้รันการขนส่ง REST ไว้หลังตัว terminate TLS (reverse proxy หรือ service mesh) และอย่าเปิดเผย listener แบบ plaintext บนเครือข่ายที่ไม่น่าเชื่อถือเป็นอันขาด รายละเอียดเฉพาะของการกำหนดค่าอยู่ใน /connect/deployment/ ข้อความนี้เป็นการแถลงจุดยืนด้านความปลอดภัย ไม่ใช่การรับประกันแบบสำเร็จรูป และการขนส่งที่ปลอดภัยต้องอาศัยการกำหนดค่าการนำไปใช้งานที่ถูกต้อง

การจำกัดเส้นทางเอาต์พุต

เครื่องมือที่เขียนไฟล์จะ resolve เส้นทางที่ร้องขอเทียบกับไดเรกทอรีฐานที่กำหนดค่าไว้ แปลงเป็น canonical แล้วปฏิเสธ null byte, protocol wrapper และ traversal แบบ .. เครื่องมือเหล่านี้ปฏิเสธทุกเส้นทางที่ resolve แล้วอยู่นอกฐาน ให้เก็บไดเรกทอรีฐานไว้บนวอลุมเฉพาะที่มีสิทธิ์ระบบไฟล์น้อยที่สุดเท่าที่จำเป็น

ถิ่นที่อยู่ของข้อมูลและมาตรการลดความเสี่ยง PII

เซิร์ฟเวอร์เก็บเอกสารไว้เฉพาะในที่เก็บเอกสารในหน่วยความจำตามค่า time to live (TTL) ที่กำหนดค่าไว้ (ค่าเริ่มต้น 1800 วินาที) และตามจำนวนที่จำกัดไว้ (ค่าเริ่มต้น 50) เซิร์ฟเวอร์ไม่คงเนื้อหาเอกสารไว้บนดิสก์ เว้นแต่คุณจะเรียกใช้เครื่องมือเอาต์พุตไฟล์อย่างชัดแจ้งและเส้นทางผ่านการจำกัดแล้ว เซิร์ฟเวอร์ไม่เรียกออกไปยังเครือข่ายภายนอกเพื่อเรนเดอร์หรือตรวจสอบเอกสาร ไบต์ของเอกสารจึงไม่ออกไปนอกการนำไปใช้งาน เว้นแต่จะกำหนดค่าเครื่องมือไว้อย่างชัดแจ้งให้ดึงทรัพยากรจากระยะไกล สำหรับการนำไปใช้งานแบบไร้สถานะที่อ่อนไหวต่อถิ่นที่อยู่ของข้อมูล ให้ปิดเอาต์พุตไฟล์ (allow_file_output: false) และจำกัด enabled_tools ให้เหลือชุดเล็กที่สุด

เทเลเมทรีที่ปลอดภัยและการล้างข้อมูลในล็อก

ล็อกการตรวจสอบ (audit) บันทึกการรันเครื่องมือที่ระดับความเสี่ยง Caution ขึ้นไป รวมถึง challenge สำหรับการยืนยันที่ออกทุกครั้ง เรกคอร์ดการตรวจสอบมีชื่อเครื่องมือ ระดับความเสี่ยง และแฟล็กความสำเร็จ ให้ถือว่าอาร์กิวเมนต์ของเครื่องมืออาจมีข้อมูลอ่อนไหว กล่าวคือ ให้ส่งล็อกไปยังปลายทางที่มีการควบคุมการเข้าถึง และอย่าปรับระดับล็อกโกลบอลให้ละเอียดจนสะท้อนเพย์โหลดของอาร์กิวเมนต์ในสภาพแวดล้อมที่ใช้ร่วมกัน การขนส่ง MCP เขียนล็อกไปยัง standard error เนื้อหาล็อกจึงไม่เข้าไปในสตรีมของโปรโตคอลบน standard output

ความสอดคล้องตามมาตรฐาน

ข้อกล่าวอ้าง	แหล่งที่มา	`reference_id`
การพิสูจน์ตัวตนที่บกพร่องบั่นทอนความปลอดภัยของ API	OWASP API Security Top 10, API2:2023 (มาตรฐานความปลอดภัย API ของ OWASP)
โทเคนที่อ่อนแอ/คาดเดาได้เป็น anti-pattern ของ broken-auth	OWASP API Security Top 10, API2:2023 (มาตรฐานความปลอดภัย API ของ OWASP)
`401` ต้อง (MUST) มี challenge `WWW-Authenticate` แนบมาด้วย	RFC 9110 §11.6.1
ข้อมูลรับรองขาดหาย/ไม่ถูกต้อง → `401` + challenge	RFC 9110 §11.6
ควบคุมความเสี่ยง ณ จุดที่ (มนุษย์) ก่อให้เกิดความเสี่ยง	IEC 31010:2019

แบบจำลองความเชื่อถือของ Model Context Protocol stdio เป็นไปตามข้อกำหนด MCP อย่างเป็นทางการ revision 2025-06-18 URL ของข้อกำหนดนี้บันทึกไว้ที่ /transports/mcp/ เนื่องจากข้อกำหนด MCP ไม่ได้เป็นส่วนหนึ่งของคลังมาตรฐานที่ถูก gate ไว้

บริบทเชิงพาณิชย์

เครื่องมือสำหรับการลงนาม การลบทึบ การปฏิบัติตามข้อกำหนด และการพิสูจน์หลักฐานทางนิติวิทยาศาสตร์จะมีให้ใช้ก็ต่อเมื่อ nextpdf/premium ถูกติดตั้งควบคู่กับเซิร์ฟเวอร์ การมีเครื่องมือเหล่านี้ไม่เปลี่ยนแปลงแบบจำลองการพิสูจน์ตัวตน ระดับความเสี่ยงของเครื่องมือเหล่านี้ยังคงวางเครื่องมือที่ทำลายล้างไว้หลังประตู human-in-the-loop

ดูเพิ่มเติม

/connect/hitl-risk-tiers/ — แบบจำลองความเสี่ยงและรายละเอียดซองการยืนยัน
/connect/deployment/ — TLS, mutual TLS, ความลับ และการปรับแต่ง worker
/transports/rest/ — ไปป์ไลน์มิดเดิลแวร์ของ REST และ security scheme ของ OpenAPI
/transports/grpc/ — การพิสูจน์ตัวตนด้วย metadata ของ gRPC และรหัสสถานะ
/connect/configuration/ — enabled_tools, การเลือกที่เก็บคีย์, การกำหนดค่าทับความเสี่ยง