@h6s-ai/web — headless Web SDK

브라우저에서 자격증명 등록을 처리하는 vanilla JavaScript SDK입니다. 직접 UI 를 그리는 headless 모드와 관리형 위젯을 제공합니다.

설치

npm i @h6s-ai/web

빠른 시작 — headless (BYO-UI)

import { createRegistration, getCertificateAgentDownloadUrl } from "@h6s-ai/web";

const reg = createRegistration({ sessionToken }); // 백엔드에서 발급받은 1회용 토큰

await reg.load(); // 폼 메타데이터·공개키 로드

// 공동인증서 — 설치된 인증서 에이전트에서 선택
const certs = await reg.certificates.list();
const installUrl = getCertificateAgentDownloadUrl(); // 에이전트 설치 링크가 필요할 때 사용
await reg.certificates.register({ certificateId: certs[0].id, password });

// 공동인증서 — 파일을 직접 업로드 (에이전트 없이)
// PFX 한 파일
await reg.certificates.registerFromFile({
  mode: "pfx",
  pfx: await pfxFile.arrayBuffer(),
  password,
});
// 또는 인증서 + 개인키 두 파일
await reg.certificates.registerFromFile({
  mode: "split",
  cert: await derFile.arrayBuffer(),
  key: await keyFile.arrayBuffer(),
  password,
});

// 기관 아이디
await reg.login.register({
  providerCode: "kb_bank",
  fields: { loginId, loginPw },
});

reg.on("success", ({ credentialId }) => {
  // credentialId 를 파트너 시스템의 사용자와 연결합니다
});
reg.on("error", (error) => {
  // error.code · error.retryable 로 분기합니다
});

인증서 목록·입력칸·버튼은 직접 렌더합니다. SDK 는 필요한 조회와 등록 제출만 처리합니다. 파일 업로드 폼을 그릴 때는 reg.load() 가 돌려준 인증서 옵션의 certSchema.inputModes 로 어떤 모드(pfx/split)와 입력 필드가 있는지 확인할 수 있습니다.

공동인증서 에이전트 설치 URL

import { getCertificateAgentDownloadUrl } from "@h6s-ai/web";

const href = getCertificateAgentDownloadUrl();
const macHref = getCertificateAgentDownloadUrl({ platform: "macos" });

현재 브라우저의 플랫폼을 자동 감지합니다. 모바일·서버 환경처럼 설치 파일이 없는 경우에는 null 을 반환합니다.

관리형 위젯 — @h6s-ai/web/embedded

UI 까지 h6s 가 렌더하는 iframe/모달/hosted 흐름을 쓰려면 서브패스를 가져옵니다.

import { openRegistrationModal } from "@h6s-ai/web/embedded";

openRegistrationModal({
  sessionToken,
  onSuccess: ({ credentialId }) => {},
  onExit: ({ reason }) => {},
});

• 파트너 모달·드로어 안에 iframe 만 임베드 (mountRegistration)
• 호스팅 페이지로 직접 이동 (openHostedRegistration)

CDN <script> 로 로드하면 전역 window.h6s 에 관리형 표면과 에이전트 설치 URL 헬퍼가 노출됩니다 — Vanilla 가이드를 참고하세요.

sessionToken 은 백엔드에서

sessionToken 은 브라우저에서 만들지 않습니다. 파트너 백엔드가 API 키로 발급한 1회용 토큰을 받아 SDK 에 넘깁니다. 발급 호출과 옵션은 SDK 가이드에 정리되어 있습니다.