ETDA Issuer SDK

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

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

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

ภาพรวมกระบวนการ

SDK นี้ดำเนินการตามรูปแบบ pre-authorized_code ของ OpenID4VCI

generate(documentType)
      │  POST /credential-offer          → คำเสนอ + รหัส QR (+ PIN ถ้ามี)
      ▼
  แสดง QR ให้ผู้ถือสแกนด้วยกระเป๋าเงินดิจิทัล
      │  (ฝั่งกระเป๋าเงิน) POST /token → /credential
      ▼
  ผู้ถือได้รับข้อมูลประจำตัว (SD-JWT) เข้าเครื่อง พร้อมนำไปนำเสนอต่อผู้ตรวจสอบ

การตรวจสอบข้อมูลประจำตัวที่ออกไป ดำเนินการโดย ETDA Verifier SDK

การติดตั้ง

npm install etda_sdk_issuer react

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

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

ครอบแอปพลิเคชันด้วย Provider แล้วสร้างคำเสนอข้อมูลประจำตัวด้วย useCredentialOffer โดยกำหนด basePath ให้ชี้ไปยังเซิร์ฟเวอร์ Issuer ที่ท่านติดตั้ง

import { IssuerWalletProvider, useCredentialOffer } from "etda_sdk_issuer";

export function App() {
  return (
    <IssuerWalletProvider config={{ basePath: "https://issuer.example.com", accessToken: getToken }}>
      <IssueButton />
    </IssuerWalletProvider>
  );
}

function IssueButton() {
  const { status, qr, txCode, error, generate } = useCredentialOffer();

  if (status === "idle") {
    return <button onClick={() => generate("IdCard")}>ออกข้อมูลประจำตัว</button>;
  }

  if (status === "ready" && qr) {
    return (
      <div>
        <img src={`data:image/png;base64,${qr}`} alt="สแกนเพื่อรับข้อมูลประจำตัว" />
        {txCode && <p>รหัส PIN สำหรับกรอกในกระเป๋าเงินดิจิทัล: {txCode}</p>}
      </div>
    );
  }

  if (status === "error") {
    return <p>เกิดข้อผิดพลาด: {error?.message}</p>;
  }

  return <p>กำลังสร้างคำเสนอ…</p>;
}

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

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

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

| สัญลักษณ์ | คำอธิบาย | | --- | --- | | IssuerWalletProvider | ตัวกำหนดค่า SDK ทุก hook อ่านค่าการตั้งค่าจากที่นี่ | | useCredentialOffer() | กระบวนการหลัก: สร้างคำเสนอ → { status, qr, txCode, offerId, error, isLoading, generate, reset } | | useCredentialConfig() | จัดการโครงสร้าง claim ของชนิดข้อมูลประจำตัว | | useIssuer() | เมธอดระดับล่างสำหรับสร้างกระบวนการแบบกำหนดเอง | | IssuerService | แกนกลาง TypeScript บริสุทธิ์ สำหรับการใช้งานที่ไม่ผ่าน React | | SdkErrorCode / SdkResult | สัญญาการจัดการข้อผิดพลาดแบบ never-throw |

การรับรองสิทธิ์ (Authentication)

Issuer API กำหนดให้ใช้ Bearer token สำหรับการเข้าถึง กำหนดค่าผ่านฟิลด์ accessToken ในการตั้งค่า Provider ซึ่งรองรับทั้งค่าสตริงและฟังก์ชันแบบ async ที่คืนค่า token ที่ยังไม่หมดอายุ ทั้งนี้ SDK จะไม่จัดเก็บ token ลงในที่เก็บถาวรใด ๆ

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

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

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

| เอกสาร | เนื้อหา | | --- | --- | | เริ่มต้นใช้งาน | คู่มือผู้บริโภค (consumer): ตั้งค่า Provider, flow การออกข้อมูลประจำตัว, การ render QR, การจัดการ PIN และโมเดลความปลอดภัย | | การจัดการ error | สัญญา never-throw, ตาราง SdkErrorCode และการ branch บนผลลัพธ์ | | สถาปัตยกรรม | ภายในระบบสำหรับผู้พัฒนาต่อ: แพตเทิร์น 2 เลเยอร์, โมเดลความเชื่อถือ, contract ที่ยืนยันกับ API จริง | | แนวทางการมีส่วนร่วม | สำหรับนักพัฒนาที่จะพัฒนาต่อยอด SDK นี้: การติดตั้งสภาพแวดล้อม คำสั่ง สถาปัตยกรรม 2 เลเยอร์ ธรรมเนียมปฏิบัติ และความปลอดภัย |

สัญญาอนุญาต

อยู่ระหว่างการกำหนดโดยหน่วยงาน