@jhb0430/kcb-pass

KCB PASS 휴대폰 본인인증의 요청, 콜백 해석, 결과 조회, 암복호화를 담당합니다. 사이트 코드와 시크릿은 호출하는 쪽이 넣습니다. 이 패키지는 그 값을 보관하지 않습니다.

가맹 신청, 대표자명 대조 같은 서비스 정책은 포함하지 않습니다.

설치

npm install @jhb0430/kcb-pass

인증 이력 테이블을 쓸 때만 drizzle-orm을 같이 설치합니다.

npm install drizzle-orm

클라이언트

import {
  createKcbPassClient,
  KCB_ENC_ALGO_CD,
  KCB_MODULE_TOKEN_PATH,
  KCB_RESULT_PATH,
  KCB_SUCCESS_CODE,
  resolveKcbApiBaseUrl,
} from '@jhb0430/kcb-pass'

const client = createKcbPassClient({
  provider: 'official', // 개발 중에는 'mock'
  siteCd: process.env.KCB_SITE_CD!,
  clientId: process.env.KCB_CLIENT_ID!,
  clientSecret: process.env.KCB_CLIENT_SECRET!,
  siteName: '내 서비스',
  siteUrl: 'https://example.com',
  apiBaseUrl: resolveKcbApiBaseUrl('PROD', 'public'),
  moduleTokenPath: KCB_MODULE_TOKEN_PATH,
  resultPath: KCB_RESULT_PATH,
  encAlgoCd: KCB_ENC_ALGO_CD,
})

const started = await client.createRequest({
  returnUrl: 'https://example.com/kcb/callback',
  rqstCausCd: '00',
})

if (started.resultCd !== KCB_SUCCESS_CODE) {
  throw new Error(started.resultMsg)
}

createRequest가 성공하면 mdlTkn과 encKey가 옵니다. encKey는 결과 조회에 필요하므로 콜백이 돌아올 때까지 서버에 보관합니다.

팝업은 resolveKcbPopupActionUrl('PROD') 주소로 POST합니다. 필드는 tc(값은 KCB_POPUP_TC), cp_cd(사이트 코드), mdl_tkn, svc_tkn입니다. 두 토큰 필드에는 같은 mdlTkn을 넣습니다.

콜백과 결과 조회

import { KCB_SUCCESS_CODE, readKcbCallback } from '@jhb0430/kcb-pass'

const callback = readKcbCallback(req.body)

const result = await client.inquireResult({
  mdlTkn: callback.mdlTkn!,
  encKey: savedEncKey,
})

if (result.resultCd === KCB_SUCCESS_CODE && result.identity) {
  const { name, telNo, ci, di } = result.identity
}

provider: 'mock'이면 KCB에 접속하지 않고 성공, 실패, 만료를 재현합니다. mockOutcome은 'VERIFIED' | 'FAILED' | 'EXPIRED'입니다.

인증 이력 테이블

import { passVerification } from '@jhb0430/kcb-pass/schema'

subject_id에는 이 인증이 속한 자기 레코드 번호를 넣습니다. 회원 id, 주문 id처럼 호출하는 서비스가 정합니다. 누가 인증했는지는 같은 행의 name, tel_no, ci_hash, di_hash입니다. CI, DI 원문은 저장하지 않습니다.