ETDA Verifier SDK

ชุดพัฒนาซอฟต์แวร์ (SDK) สำหรับ React และ TypeScript ที่ใช้ตรวจสอบการนำเสนอข้อมูลประจำตัว แบบ Verifiable Presentation ตามมาตรฐาน OpenID4VC กับระบบ ETDA VC Wallet โดย SDK ทำหน้าที่สร้างรหัส QR สำหรับการร้องขอ (presentation request) รอรับการนำเสนอจากกระเป๋าเงิน ดิจิทัล (wallet) และรายงานผลการตรวจสอบที่ดำเนินการโดยเซิร์ฟเวอร์ ผ่านรูปแบบการจัดการ ข้อผิดพลาดที่คาดการณ์ได้ (never-throw) และ React hook เพียงตัวเดียวสำหรับกระบวนการ "แสดง QR แล้วรอผลลัพธ์"

คุณสมบัติหลัก

• ใช้งานง่าย — ครอบคลุมทั้งกระบวนการด้วย hook เดียว (usePresentation) ตั้งแต่สร้าง QR ไปจนถึงอ่านค่าที่ตรวจสอบแล้ว
• ปลอดภัยโดยการออกแบบ — ค่า claims จะเข้าถึงได้ต่อเมื่อเซิร์ฟเวอร์ยืนยันผลสำเร็จ เท่านั้น ไม่มีการเก็บข้อมูลอ่อนไหวลงหน่วยความจำถาวร และไม่บันทึกความลับลงในบันทึก (log)
• ไม่ทำให้แอปพลิเคชันหยุดทำงาน — ทุกเมธอดที่เรียกผ่านเครือข่ายคืนค่าเป็น SdkResult แบบ never-throw พร้อมรหัสข้อผิดพลาดมาตรฐาน
• รองรับทั้ง React และ TypeScript ล้วน — เลเยอร์แกนกลาง (core) เป็น TypeScript บริสุทธิ์ ใช้งานได้โดยไม่ต้องพึ่งพา React

สถาปัตยกรรมและโมเดลความเชื่อถือ

SDK นี้ทำงานตามรูปแบบ direct_post ของ OpenID4VP โดยการตรวจสอบเชิงเข้ารหัสทั้งหมด ดำเนินการที่ เซิร์ฟเวอร์ฝั่งผู้ตรวจสอบ (verifier) ได้แก่ การตรวจลายเซ็นของผู้ออก เอกสาร (issuer) การค้นหา DID การตรวจสอบสถานะการเพิกถอน และการผูกค่า nonce/วันหมดอายุ

ตัว SDK ทำหน้าที่เพียงสร้างคำร้องขอการนำเสนอและเรียกผลลัพธ์ (poll) — ไม่ได้ดำเนินการ เข้ารหัสฝั่งไคลเอนต์ สัญญาณความเชื่อถือที่ใช้อ้างอิงคือ PresentationResult.responseCode มีค่าเท่ากับ "200" ซึ่งเปิดเผยผ่านค่า verified และฟังก์ชัน isVerified(result)

รายละเอียดโมเดลความปลอดภัยฉบับเต็ม โปรดดูหัวข้อ ความปลอดภัยและความเชื่อถือ

การติดตั้ง

npm install etda_sdk_verifier react

โดย react (เวอร์ชัน 16.8 ขึ้นไป) เป็น peer dependency

การเริ่มต้นใช้งาน

ครอบแอปพลิเคชัน (หรือส่วนที่ต้องการตรวจสอบ) ด้วย Provider แล้วควบคุมกระบวนการด้วย usePresentation โดยกำหนด basePath ให้ชี้ไปยังเซิร์ฟเวอร์ Verifier ที่ท่านติดตั้ง

import { VerifierWalletProvider, usePresentation } from "etda_sdk_verifier";

export function App() {
  return (
    <VerifierWalletProvider config={{ basePath: "https://verifier.example.com" }}>
      <AgeGate />
    </VerifierWalletProvider>
  );
}

function AgeGate() {
  const { status, qr, claims, error, start, reset } = usePresentation();

  if (status === "idle") {
    return <button onClick={() => start("IDCard")}>ยืนยันตัวตนด้วยกระเป๋าเงินดิจิทัล</button>;
  }

  if (status === "generating" || status === "pending") {
    return (
      <div>
        {qr && <img src={`data:image/png;base64,${qr.qrImageBase64}`} alt="สแกนเพื่อนำเสนอ" />}
        <p>กำลังรอการนำเสนอจากกระเป๋าเงินดิจิทัล…</p>
      </div>
    );
  }

  if (status === "verified") {
    return <pre>{JSON.stringify(claims, null, 2)}</pre>;
  }

  // สถานะ "failed" หรือ "expired"
  return (
    <div>
      <p>การตรวจสอบไม่สำเร็จ ({status}) {error?.message}</p>
      <button onClick={reset}>ลองใหม่อีกครั้ง</button>
    </div>
  );
}

กระบวนการทั้งหมดสรุปได้ว่า เรียก start(documentType) เพื่อแสดง qr.qrImageBase64 จากนั้นค่า status จะเปลี่ยนเป็น verified failed หรือ expired โดยค่า claims จะมีข้อมูล เฉพาะเมื่อการตรวจสอบผ่านแล้วเท่านั้น

ลำดับการทำงาน

start(documentType)
      │  POST /generate-vp-qr           → { qrImageBase64, state (รหัส session), nonce }
      ▼
  status: "generating" → "pending"      แสดง QR และรอกระเป๋าเงินดิจิทัลนำเสนอ
      │  poll GET /openid4vc/vp/{id}     (สถานะ 404 หมายถึงยังไม่มีการนำเสนอ ให้เรียกซ้ำ)
      ▼
  status: "verified" | "failed" | "expired"
           verified ⇒ มีค่า claims ให้ใช้งาน (เซิร์ฟเวอร์ตอบ responseCode 200)

ชนิดเอกสารที่รองรับ

Transcript · IDCard · DriverLicense (กำหนดผ่านชนิด DocumentType)

รายการ claims ที่ร้องขอถูกกำหนดไว้ ที่ฝั่งเซิร์ฟเวอร์ ตามชนิดเอกสาร โดย SDK ไม่สามารถปรับลดรายการ claims ได้ด้วยตนเอง

โครงสร้าง API สาธารณะ

| สัญลักษณ์ | คำอธิบาย | | --- | --- | | VerifierWalletProvider | ตัวกำหนดค่า SDK ทุก hook อ่านค่าการตั้งค่าจากที่นี่ | | usePresentation() | กระบวนการหลัก: สร้าง QR → เรียกผลอัตโนมัติ → { status, qr, claims, verified, error, isLoading, start, reset } | | useVerifier() | เมธอดระดับล่างสำหรับสร้างกระบวนการแบบกำหนดเอง | | VerifierService | แกนกลาง TypeScript บริสุทธิ์ สำหรับการใช้งานที่ไม่ผ่าน React | | SdkErrorCode / SdkResult | สัญญาการจัดการข้อผิดพลาดแบบ never-throw | | parsePresentedClaims / isVerified / isTerminal | ฟังก์ชันช่วยเหลือสำหรับประมวลผลผลลัพธ์ |

เอกสารอ้างอิง API ฉบับสมบูรณ์ (สร้างอัตโนมัติ) สามารถสร้างได้ด้วยคำสั่ง npm run docs:api ซึ่งจะสร้างไฟล์ไว้ที่ docs/api/

การทดลองใช้งาน (Demo)

โครงการนี้มีแอปพลิเคชันตัวอย่าง (playground) ที่สาธิตการทำงานครบวงจร พร้อมคู่มือ ทีละขั้นตอนสำหรับการติดตั้งและใช้งาน โปรดดู คู่มือการทดลองใช้งาน

เอกสารประกอบ

| เอกสาร | เนื้อหา | | --- | --- | | คู่มือเริ่มต้นใช้งาน | การตั้งค่า กระบวนการทำงานฉบับเต็ม การแสดง QR การอ่าน claims และความปลอดภัย | | การจัดการข้อผิดพลาด | ตารางรหัส SdkErrorCode และแนวทางการจัดการ | | สถาปัตยกรรมระบบ | โครงสร้างภายในสำหรับผู้พัฒนาต่อยอด | | แนวทางการมีส่วนร่วม | การติดตั้งสภาพแวดล้อม คำสั่ง และแนวปฏิบัติ |

สัญญาอนุญาต

อยู่ระหว่างการกำหนดโดยหน่วยงาน (โปรดดู PUBLISHING.md)