@nexus-cross/kyc 1.3.4-beta.10

package/README.md

@@ -0,0 +1,273 @@
+# @nexus-cross/kyc
+
+KYC integration for **cross-auth**. A framework-agnostic core plus a thin React
+adapter that wrap the cross-auth `/kyc` endpoints:
+
+- **`GET /kyc`** — read-only. Returns the caller's identity (SIWE or social) and
+  the identity-core-api KYC status. No side effects.
+- **`POST /kyc`** — links the caller's wallets to the project (idempotent) and,
+  when KYC isn't yet approved, starts/resumes verification (idempotent) and
+  surfaces either a hosted `verification_url` (preferred) or a Sumsub SDK token.
+  The package enters the flow accordingly — see [Launching verification](#launching-verification).
+
+The package follows the same hexagonal shape and env-resolution style as
+[`@nexus-cross/onramp`](../onramp): pure `core` (ports/types/use cases) →
+`adapters` (HTTP repository + env-based endpoints) → `react` (Provider + hooks),
+with a `createKyc()` facade on top.
+
+## Install
+
+```sh
+pnpm add @nexus-cross/kyc
+# React Provider/hooks (the "./react" entry) additionally need:
+pnpm add react react-dom
+```
+
+`react` is an **optional** peer — only the `@nexus-cross/kyc/react` sub-entry
+requires it. The main entry (`createKyc`, `HttpKycRepository`, …) is React-free
+and works in any framework or vanilla JS.
+
+## Environment / base URL
+
+Base URL resolution mirrors `@nexus-cross/onramp`. You normally don't set
+anything — it picks the cross-auth host from the environment identifier:
+
+| Environment | Base URL |
+|---|---|
+| `production` (default) | `https://cross-auth.crosstoken.io/cross-auth` |
+| `stage` | `https://stg-cross-auth.crosstoken.io/cross-auth` |
+| `dev` | `https://dev-cross-auth.crosstoken.io/cross-auth` |
+
+Resolution priority:
+
+1. Explicit `baseUrl` option passed to `createKyc` / `HttpKycRepository`.
+2. `VITE_CROSSX_AUTH_BASE_URL` (Vite) or `NEXT_PUBLIC_CROSSX_AUTH_BASE_URL` (Next.js).
+3. Environment identifier `VITE_CROSSX_ENVIRONMENT` / `NEXT_PUBLIC_CROSSX_ENVIRONMENT`
+   / `CROSSX_ENVIRONMENT` (`dev` | `stage` | `production`) → the table above.
+
+Non-`https` URLs are rejected (except `http://localhost` for local dev).
+
+## Authentication
+
+The `/kyc` endpoints require auth. Two ways, used together:
+
+- **Bearer token** — pass `getAccessToken`; the repository sends
+  `Authorization: Bearer <token>`. It's called on every request, so a token
+  refresh is picked up automatically without re-creating the client (don't bake
+  a stale token in). A `Bearer ` prefix in the returned value is de-duplicated.
+- **Cookie session** — every request is sent with `credentials: 'include'`, so an
+  HttpOnly cross-auth session cookie is attached automatically. If you rely only
+  on cookies, you can omit `getAccessToken`.
+
+### Social login extra headers
+
+For **social** logins the backend additionally requires `X-Project-Id` **plus a
+client identifier**, otherwise it returns **401**:
+
+- **Web** — the client identifier is the `Origin` header, which the browser sends
+  automatically on cross-origin requests (it's a forbidden header, so this
+  package never sets it). Just make sure `projectId` is set.
+- **Native SDK** — pass `appId` (`X-App-Id`) and `appType` (`X-App-Type`) instead.
+
+`projectId` is sent as `X-Project-Id`. Use your embedded project id (falling back
+to the cross project id), the same value connect-kit uses for the embedded wallet.
+SIWE logins are authenticated by the token/cookie alone and don't need the
+client identifier.
+
+## Quick start — with connect-kit (recommended)
+
+If you use `@nexus-cross/connect-kit-react`, KYC is auto-wired. Set
+`kycEnabled: true` in the kit config; connect-kit mounts the provider and injects
+the access token from the connected **crossx 2.0 SDK** session — **no token
+plumbing, no `KycProvider`**:
+
+```ts
+// config
+createConnectKitConfig({ crossProjectId, kycEnabled: true /* … */ });
+```
+
+```tsx
+import { useKyc } from '@nexus-cross/connect-kit-react';
+
+function KycButton() {
+  const { verified, status, isLoading, isStarting, refresh, startVerification } =
+    useKyc();
+  if (verified) return <span>KYC verified ✓</span>;
+  return (
+    <>
+      <button onClick={() => void refresh()} disabled={isLoading}>Check KYC</button>
+      <button onClick={() => void startVerification()} disabled={isStarting}>
+        Start KYC
+      </button>
+      <p>status: {status ?? '—'}</p>
+    </>
+  );
+}
+```
+
+`X-Project-Id` uses `embeddedProjectId` (falling back to `crossProjectId`). The
+token is read per request, so refreshes are picked up automatically.
+
+## Quick start — standalone (without connect-kit)
+
+Mount `<KycProvider>` yourself and supply `getAccessToken`:
+
+```tsx
+// App.tsx
+import { KycProvider } from '@nexus-cross/kyc/react';
+
+export function App() {
+  return (
+    <KycProvider
+      config={{
+        projectId: EMBEDDED_PROJECT_ID,
+        getAccessToken: () => accessToken, // read latest token here
+      }}
+    >
+      <KycButton />
+    </KycProvider>
+  );
+}
+```
+
+```tsx
+// KycButton.tsx
+import { useKyc } from '@nexus-cross/kyc/react';
+
+function KycButton() {
+  const { status, verified, isLoading, isStarting, error, refresh, startVerification } =
+    useKyc(); // autoFetch: true → GET /kyc on mount
+
+  if (verified) return <span>KYC verified ✓</span>;
+
+  return (
+    <div>
+      <button onClick={() => void refresh()} disabled={isLoading}>
+        {isLoading ? 'Checking…' : 'Check KYC'}
+      </button>
+      <button onClick={() => void startVerification()} disabled={isStarting}>
+        {isStarting ? 'Starting…' : 'Start KYC'}
+      </button>
+      <p>status: {status ?? '—'}</p>
+      {error && <p>error: {error.message}</p>}
+    </div>
+  );
+}
+```
+
+`startVerification()` runs `POST /kyc` and then enters the verification flow
+automatically (see [Launching verification](#launching-verification)). Use the
+lower-level `start()` if you want the raw `KycIdentity` back without launching.
+
+Pass `useKyc({ autoFetch: false })` to skip the on-mount `GET /kyc` and trigger
+it manually via `refresh()`. `useOptionalKyc()` returns the facade or `null`
+outside a Provider (for "enable only if mounted" UIs).
+
+## Launching verification
+
+`POST /kyc` (via `start()` / `startVerification()`) returns a `KycIdentity`. How
+the verification flow is entered depends on what the backend put in it, and the
+package picks the right path automatically:
+
+| Response field | Behavior | Notes |
+|---|---|---|
+| `verificationUrl` (`verification_url`) | **default** — opens the hosted URL in a new tab (`window.open`) | vendor-neutral; no CDN/CSP. This is the [recommended backend contract](../../docs/kyc/01-verification-link-proposal.md). |
+| `sdkToken` (`kyc_token`), no URL | **fallback** — loads the Sumsub WebSDK and launches it in a fullscreen modal | Sumsub CDN coupling is isolated to the browser adapter; token refresh re-calls `POST /kyc`. |
+| neither | throws `KycError('LAUNCH_FAILED')` | — |
+
+- **New tab vs current window**: pass `target` (URL mode only).
+  `'newWindow'` (default) opens the URL in a new tab; `'currentWindow'`
+  navigates the current tab via `location.assign` (rely on the backend
+  `redirect` to return). The WebSDK fallback always renders as a modal in the
+  current window.
+  ```ts
+  await startVerification({ target: 'currentWindow' });
+  ```
+- React: `useKyc().startVerification(opts?)` = `start()` + launch. Returns
+  `{ identity, handle }`; `handle.close()` dismisses the WebSDK modal (no-op in
+  URL mode).
+- Framework-agnostic: `launchKycVerification(identity, opts)` from
+  `@nexus-cross/kyc`.
+- Completion is authoritative via **webhook**; poll `GET /kyc` (`refresh()`) for
+  the final status regardless of which path was taken.
+
+## Quick start — framework-agnostic
+
+```ts
+import { createKyc, launchKycVerification } from '@nexus-cross/kyc';
+
+const kyc = createKyc({
+  projectId: EMBEDDED_PROJECT_ID,
+  getAccessToken: () => accessToken,
+});
+
+const me = await kyc.getStatus();      // GET /kyc
+if (!me.verified) {
+  const started = await kyc.start();    // POST /kyc
+  // verificationUrl → new tab, else sdkToken → Sumsub WebSDK modal
+  await launchKycVerification(started);
+}
+```
+
+## API
+
+### `createKyc(options): Kyc`
+
+`options` (`CreateKycOptions`):
+
+| Option | Type | Notes |
+|---|---|---|
+| `projectId` | `string?` | Sent as `X-Project-Id`. Required for social login. |
+| `getAccessToken` | `() => string \| null \| undefined \| Promise<…>` | Bearer token getter, called per request. |
+| `appId` | `string?` | Native SDK flow only → `X-App-Id`. |
+| `appType` | `string?` | `'android' \| 'ios' \| 'windows'` → `X-App-Type`. |
+| `baseUrl` | `string?` | Override the resolved cross-auth base URL. |
+| `repository` | `KycRepository?` | Inject a custom/mock transport. |
+
+Returns `{ port, getStatus(), start() }`.
+
+### `KycIdentity`
+
+Normalized (camelCase) form of cross-auth `KYCResp`:
+
+| Field | Type | Source |
+|---|---|---|
+| `status` | `'none' \| 'pending' \| 'approved' \| 'rejected_retry' \| 'rejected_final' \| 'wallet_required'` | `status` |
+| `verified` | `boolean` | `kyc_verified` |
+| `loginType` | `'siwe' \| 'social' \| undefined` | `login_type` |
+| `walletAddress` | `string?` | `wallet_address` |
+| `rejectType` | `'RETRY' \| 'FINAL' \| undefined` | `reject_type` (rejected states) |
+| `provider` | `string?` | `provider` (e.g. `"sumsub"`) |
+| `verificationUrl` | `string?` | `verification_url` (hosted link → opened directly) |
+| `sdkToken` | `string?` | `kyc_token` (Sumsub SDK token, WebSDK fallback) |
+| `sdkTokenExpiresAt` | `string?` | `kyc_expires_at` (ISO) |
+| `email` / `nickname` / `sub` / `uuid` | `string?` | social only |
+
+### Errors
+
+Failures throw a `KycError` with a `code`: `MISSING_PROJECT_ID`,
+`UNAUTHORIZED` (401/403), `STATUS_FAILED`, `START_FAILED`, `INVALID_RESPONSE`,
+`NETWORK_ERROR`, `LAUNCH_FAILED` (verification could not be opened — popup
+blocked, SSR, or neither `verificationUrl` nor `sdkToken` present). In React, the
+last error is surfaced via `useKyc().error` (reads/`refresh()` capture it;
+`start()`/`startVerification()` also throw so you can `try/catch`).
+
+## Advanced — custom transport
+
+Implement `KycRepository` to talk to a different gateway or to mock in tests,
+then inject it:
+
+```ts
+import { createKyc, type KycRepository } from '@nexus-cross/kyc';
+
+const mock: KycRepository = {
+  fetchStatus: async () => ({ status: 'approved', verified: true }),
+  initVerification: async () => ({ status: 'approved', verified: true }),
+};
+
+const kyc = createKyc({ repository: mock });
+```
+
+## License
+
+MIT

package/dist/chunk-2477RDFG.js

@@ -0,0 +1 @@
+var s=class extends Error{constructor(e,n,r){super(n),this.name="KycError",this.code=e,this.details=r}},I=["none","pending","approved","rejected_retry","rejected_final","wallet_required"];function g(t){return I.includes(t)?t:"none"}function m(t){return t==="siwe"||t==="social"?t:void 0}function S(t){let e=typeof t=="string"?t.toUpperCase():"";return e==="RETRY"||e==="FINAL"?e:void 0}var d=class{constructor(e){this.port=e}execute(){return this.port.getStatus()}};var p=class{constructor(e){this.port=e}execute(){return this.port.startVerification()}};var b={dev:"https://dev-cross-auth.crosstoken.io/cross-auth",stage:"https://stg-cross-auth.crosstoken.io/cross-auth",production:"https://cross-auth.crosstoken.io/cross-auth"},h={kyc:"/kyc"};function w(t){try{return import.meta.env?.[t]}catch{return}}function f(t){if(!(typeof process>"u"||!process.env))switch(t){case"NEXT_PUBLIC_CROSSX_ENVIRONMENT":return process.env.NEXT_PUBLIC_CROSSX_ENVIRONMENT;case"CROSSX_ENVIRONMENT":return process.env.CROSSX_ENVIRONMENT;case"NEXT_PUBLIC_CROSSX_AUTH_BASE_URL":return process.env.NEXT_PUBLIC_CROSSX_AUTH_BASE_URL;default:return}}function R(){switch((w("VITE_CROSSX_ENVIRONMENT")??f("NEXT_PUBLIC_CROSSX_ENVIRONMENT")??f("CROSSX_ENVIRONMENT"))?.toLowerCase()){case"dev":case"development":return"dev";case"stage":case"staging":case"stg":return"stage";default:return"production"}}function T(){let t=w("VITE_CROSSX_AUTH_BASE_URL")??f("NEXT_PUBLIC_CROSSX_AUTH_BASE_URL"),e=R(),n=t??b[e];return _(n),n}function _(t){let e;try{e=new URL(t)}catch{throw new Error(`[kyc] Invalid base URL: ${t}`)}if(e.protocol==="https:")return;let n=e.hostname==="localhost"||e.hostname==="127.0.0.1"||e.hostname.endsWith(".local");if(!(e.protocol==="http:"&&n))throw new Error(`[kyc] base URL must be https (or http://localhost for dev). Got: ${t}`)}var A=1e4,y=class{constructor(e={}){this.projectId=e.projectId?.trim()||void 0,this.getAccessToken=e.getAccessToken,this.appId=e.appId,this.appType=e.appType,this.baseUrl=(e.baseUrl??T()).replace(/\/+$/,""),this.paths={kyc:e.paths?.kyc??h.kyc},this.timeoutMs=e.timeoutMs??A}fetchStatus(){return this.request("GET","STATUS_FAILED")}initVerification(){return this.request("POST","START_FAILED")}async request(e,n){let r=this.baseUrl+this.paths.kyc,o=new AbortController,a=setTimeout(()=>o.abort(),this.timeoutMs),i;try{i=await fetch(r,{method:e,signal:o.signal,headers:await this.buildHeaders(),credentials:"include"})}catch(l){throw new s("NETWORK_ERROR",l instanceof Error?l.message:`KYC ${e} request failed`,{cause:String(l)})}finally{clearTimeout(a)}if(i.status===401||i.status===403)throw new s("UNAUTHORIZED",`KYC ${e} returned ${i.status}`);if(!i.ok)throw new s(n,`KYC ${e} returned ${i.status}`);let c;try{c=await i.json()}catch{throw new s("INVALID_RESPONSE",`KYC ${e} response was not JSON`)}return this.parseIdentity(c)}async buildHeaders(){let e={Accept:"application/json"};if(this.projectId&&(e["X-Project-Id"]=this.projectId),this.appId&&(e["X-App-Id"]=this.appId),this.appType&&(e["X-App-Type"]=this.appType),this.getAccessToken){let n=await this.getAccessToken();n&&n.trim()&&(e.Authorization=/^bearer\s/i.test(n)?n:`Bearer ${n}`)}return e}parseIdentity(e){if(!e||typeof e!="object")throw new s("INVALID_RESPONSE","KYC response was not an object");let n=e,r=n.data&&typeof n.data=="object"?n.data:n,o=i=>typeof i=="string"&&i.trim()?i:void 0;return{status:g(r.status),verified:r.kyc_verified===!0,loginType:m(r.login_type),walletAddress:o(r.wallet_address),rejectType:S(r.reject_type),provider:o(r.provider),verificationUrl:o(r.verification_url),sdkToken:o(r.kyc_token),sdkTokenExpiresAt:o(r.kyc_expires_at),email:o(r.email),nickname:o(r.nickname),sub:o(r.sub),uuid:o(r.uuid)}}};var u=class{constructor(e={}){this.repository=e.repository??new y({projectId:e.projectId,getAccessToken:e.getAccessToken,appId:e.appId,appType:e.appType})}getStatus(){return this.repository.fetchStatus()}startVerification(){return this.repository.initVerification()}};function F(t={}){let e=new u(t),n=new d(e),r=new p(e);return{port:e,getStatus:()=>n.execute(),start:()=>r.execute()}}var E="https://static.sumsub.com/idensic/static/sns-websdk-builder.js";function v(){return new Promise((t,e)=>{if(typeof document>"u"){e(new Error("[kyc/sumsub] document is not available (SSR)"));return}if(window.snsWebSdk){t();return}let n=document.querySelector(`script[src="${E}"]`);if(n){n.addEventListener("load",()=>t()),n.addEventListener("error",()=>e(new Error("[kyc/sumsub] script failed to load")));return}let r=document.createElement("script");r.src=E,r.async=!0,r.onload=()=>t(),r.onerror=()=>e(new Error("[kyc/sumsub] script failed to load (CSP/network?)")),document.head.appendChild(r)})}async function k(t){if(await v(),!window.snsWebSdk)throw new Error("[kyc/sumsub] snsWebSdk global is not available");window.snsWebSdk.init(t.token,t.getNewToken).withConf({lang:t.lang??"ko"}).withOptions({addViewportTag:!1,adaptIosWebView:!0}).on("idCheck.onError",n=>t.onError?.(n)).on("idCheck.onApplicantStatusChanged",n=>t.onStatusChange?.(n)).build().launch(t.container)}var K={mode:"url",close:()=>{}};async function z(t,e={}){if(typeof window>"u")throw new s("LAUNCH_FAILED","window is not available (SSR)");if(t.verificationUrl){if((e.target??"newWindow")==="currentWindow")return window.location.assign(t.verificationUrl),K;if(!window.open(t.verificationUrl,"_blank",e.windowFeatures??"noopener,noreferrer"))throw new s("LAUNCH_FAILED","Popup blocked opening verification URL");return K}if(t.sdkToken)return C(t.sdkToken,e);throw new s("LAUNCH_FAILED","KYC response has neither verificationUrl nor sdkToken")}async function C(t,e){let n=document.createElement("div");n.setAttribute("role","dialog"),n.setAttribute("aria-modal","true"),Object.assign(n.style,{position:"fixed",inset:"0",zIndex:"2147483000",background:"#0b0d14",display:"flex",flexDirection:"column"});let r=document.createElement("div");Object.assign(r.style,{display:"flex",alignItems:"center",justifyContent:"flex-end",padding:"10px 14px",borderBottom:"1px solid rgba(255,255,255,0.12)"});let o=document.createElement("button");o.type="button",o.textContent="\u2715",Object.assign(o.style,{border:"none",background:"transparent",color:"#fff",fontSize:"18px",cursor:"pointer",lineHeight:"1"});let a=document.createElement("div");Object.assign(a.style,{flex:"1",overflow:"auto",background:"#fff"});let i=()=>{n.remove()};o.addEventListener("click",i),r.appendChild(o),n.appendChild(r),n.appendChild(a),document.body.appendChild(n);try{await k({token:t,container:a,lang:e.lang,getNewToken:e.getFreshToken??(async()=>t),onError:e.onError,onStatusChange:e.onStatusChange})}catch(c){throw i(),new s("LAUNCH_FAILED",c instanceof Error?c.message:"Sumsub WebSDK launch failed",{cause:String(c)})}return{mode:"websdk",close:i}}export{s as a,g as b,m as c,S as d,d as e,p as f,h as g,T as h,y as i,u as j,F as k,z as l};

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { K as KycPort, a as KycIdentity } from './launchVerification-oM0NtTLd.js';
+export { A as AccessTokenGetter, B as BrowserKycAdapter, b as BrowserKycAdapterOptions, C as CreateKycOptions, D as DEFAULT_KYC_PATHS, H as HttpKycRepository, c as HttpKycRepositoryOptions, d as Kyc, e as KycEndpointPaths, f as KycEnvironment, g as KycError, h as KycErrorCode, i as KycLaunchTarget, j as KycLoginType, k as KycRejectType, l as KycRepository, m as KycStatus, n as KycVerificationHandle, o as KycVerificationMode, L as LaunchKycVerificationOptions, U as Unsubscribe, p as createKyc, q as getKycBaseUrl, r as launchKycVerification, s as normalizeKycStatus, t as normalizeLoginType, u as normalizeRejectType } from './launchVerification-oM0NtTLd.js';
+
+/**
+ * Port 위임 + 향후 정책(캐시 무효화, 파생 상태 계산 등)이 들어갈 자리.
+ * 현 1차에서는 얇은 래퍼지만, react 훅이 use case에 의존하도록 두면 추후 확장 무중단.
+ */
+declare class GetKycStatusUseCase {
+    private readonly port;
+    constructor(port: KycPort);
+    execute(): Promise<KycIdentity>;
+}
+
+/**
+ * 지갑 링크 + KYC 검증 시작/재개. POST /kyc는 idempotent하므로 이미 진행 중/
+ * 승인 상태에서 다시 호출해도 안전하다.
+ */
+declare class StartKycUseCase {
+    private readonly port;
+    constructor(port: KycPort);
+    execute(): Promise<KycIdentity>;
+}
+
+export { GetKycStatusUseCase, KycIdentity, KycPort, StartKycUseCase };

package/dist/index.js

@@ -0,0 +1 @@
+import{a as e,b as r,c as t,d as o,e as c,f as p,g as y,h as s,i,j as a,k as K,l as n}from"./chunk-2477RDFG.js";export{a as BrowserKycAdapter,y as DEFAULT_KYC_PATHS,c as GetKycStatusUseCase,i as HttpKycRepository,e as KycError,p as StartKycUseCase,K as createKyc,s as getKycBaseUrl,n as launchKycVerification,r as normalizeKycStatus,t as normalizeLoginType,o as normalizeRejectType};

package/dist/launchVerification-oM0NtTLd.d.ts

@@ -0,0 +1,292 @@
+/** 구독 해제 함수. core(connect-kit) 의존을 피하려고 kyc 안에 자체 정의. */
+type Unsubscribe = () => void;
+/**
+ * 백엔드 KYC 진행 상태 (cross-auth `KYCResp.status`).
+ *  - none            : 아직 시작 전
+ *  - pending         : 심사 진행 중
+ *  - approved        : 승인 완료 (kyc_verified=true)
+ *  - rejected_retry  : 거절됐지만 재시도 가능 (reject_type=RETRY)
+ *  - rejected_final  : 최종 거절 (reject_type=FINAL)
+ *  - wallet_required : 검증 전 지갑 링크가 필요
+ */
+type KycStatus = 'none' | 'pending' | 'approved' | 'rejected_retry' | 'rejected_final' | 'wallet_required';
+/** 로그인 방식 (cross-auth `KYCResp.login_type`). */
+type KycLoginType = 'siwe' | 'social';
+/** 거절 사유 종류 (rejected_* 상태에서만 존재, `KYCResp.reject_type`). */
+type KycRejectType = 'RETRY' | 'FINAL';
+/**
+ * 호출자 신원 + KYC 상태. cross-auth `KYCResp`를 도메인 친화(camelCase)로
+ * 정규화한 형태. 외부 스키마(snake_case)는 어댑터가 이 타입으로 변환한다.
+ */
+interface KycIdentity {
+    /** none|pending|approved|rejected_retry|rejected_final|wallet_required */
+    readonly status: KycStatus;
+    /** identity-core-api 기준 승인 여부 (`kyc_verified`). */
+    readonly verified: boolean;
+    /** "siwe" | "social". 미상이면 undefined. */
+    readonly loginType?: KycLoginType;
+    /** 액세스 토큰에서 파생된 지갑 주소 (`wallet_address`). */
+    readonly walletAddress?: string;
+    /** rejected_* 상태에서만 존재 (`reject_type`). */
+    readonly rejectType?: KycRejectType;
+    /** KYC 공급자 식별자 (`provider`). 예: "sumsub". 멀티 벤더 대비. */
+    readonly provider?: string;
+    /**
+     * 호스티드 검증 URL (`verification_url`). 백엔드가 Sumsub websdkLink 등으로
+     * 생성해 내려주면, 프론트는 이 URL을 새 창으로 열어 검증을 진행한다(기본 경로).
+     */
+    readonly verificationUrl?: string;
+    /** Sumsub SDK 토큰 (`kyc_token`). POST /kyc의 InitKYC 발급 시에만 존재. */
+    readonly sdkToken?: string;
+    /** Sumsub SDK 토큰 만료 시각 ISO 문자열 (`kyc_expires_at`). */
+    readonly sdkTokenExpiresAt?: string;
+    /** social 로그인 전용 — 이메일. */
+    readonly email?: string;
+    /** social 로그인 전용 — 닉네임. */
+    readonly nickname?: string;
+    /** social 로그인 전용 — IdP subject (`sub`). */
+    readonly sub?: string;
+    /** social 로그인 전용 — 내부 uuid. */
+    readonly uuid?: string;
+}
+type KycErrorCode = 'MISSING_PROJECT_ID' | 'UNAUTHORIZED' | 'STATUS_FAILED' | 'START_FAILED' | 'INVALID_RESPONSE' | 'NETWORK_ERROR' | 'LAUNCH_FAILED';
+declare class KycError extends Error {
+    readonly code: KycErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: KycErrorCode, message: string, details?: Record<string, unknown>);
+}
+/** 알 수 없는 status 문자열은 'none'으로 폴백. */
+declare function normalizeKycStatus(value: unknown): KycStatus;
+/** "siwe" | "social" 외 값은 undefined. */
+declare function normalizeLoginType(value: unknown): KycLoginType | undefined;
+/** "RETRY" | "FINAL" 외 값은 undefined. 대소문자 무관. */
+declare function normalizeRejectType(value: unknown): KycRejectType | undefined;
+
+/**
+ * cross-auth KYC 추상화. 호출자 신원 + KYC 상태 조회와 검증 시작을 담당한다.
+ *
+ * 구현체는 어댑터 레이어가 담당 — 이 Port는 도메인 계약만 가진다.
+ */
+interface KycPort {
+    /**
+     * GET /kyc — 읽기 전용. 호출자의 신원(SIWE/social) + KYC 상태를 반환한다.
+     * 부수효과 없음: 지갑 링크나 검증 시작을 하지 않는다 (그건 startVerification).
+     */
+    getStatus(): Promise<KycIdentity>;
+    /**
+     * POST /kyc — 호출자의 지갑을 프로젝트에 링크(idempotent)하고, KYC가 아직
+     * 승인되지 않았다면 검증을 시작/재개(idempotent)하며 Sumsub SDK 토큰
+     * (`sdkToken`)을 surfacing 한다. 이미 승인된 경우 토큰 없이 상태만 반환.
+     */
+    startVerification(): Promise<KycIdentity>;
+}
+
+/**
+ * cross-auth 백엔드 엔드포인트 — 패키지 내부 상수. DApp 개발자는 이 파일을
+ * 보지도, 수정할 일도 없다. 환경별 base URL은 빌드 시 환경변수로 override
+ * 가능하다 (env 처리 방식은 `@nexus-cross/onramp`의 endpoints와 동일).
+ *
+ * 우선순위 (override):
+ *   1) `VITE_CROSSX_AUTH_BASE_URL` (Vite 빌드)
+ *   2) `NEXT_PUBLIC_CROSSX_AUTH_BASE_URL` (Next.js)
+ *   3) 환경 식별(`VITE_CROSSX_ENVIRONMENT` / `NEXT_PUBLIC_CROSSX_ENVIRONMENT`)
+ *      에 따라 DEFAULT_BASE_URL의 dev/stage/production
+ */
+type KycEnvironment = 'dev' | 'stage' | 'production';
+interface KycEndpointPaths {
+    /**
+     * 신원/KYC 상태 — GET은 읽기 전용 조회, POST는 지갑 링크 + 검증 시작.
+     * cross-auth는 같은 경로(`/kyc`)에 두 메서드를 둔다.
+     */
+    kyc: string;
+}
+declare const DEFAULT_KYC_PATHS: KycEndpointPaths;
+declare function getKycBaseUrl(): string;
+
+/**
+ * 외부 통신을 추상화한 리포지토리. BrowserKycAdapter는 fetch를 직접 호출하지
+ * 않고 이 인터페이스를 통한다.
+ *
+ * 구현체:
+ *  - HttpKycRepository: cross-auth `/kyc` 호출 (GET 상태 / POST 시작)
+ *
+ * DApp이 직접 구현해서 주입할 수도 있다 (자체 게이트웨이가 다른 응답 스키마를
+ * 쓰는 경우, 테스트 mock 등). 식별자(projectId, accessToken getter 등)는 구현체
+ * 생성자에서 주입하므로 메서드 인자에 포함하지 않는다.
+ */
+interface KycRepository {
+    /** GET /kyc — 읽기 전용 신원 + KYC 상태. */
+    fetchStatus(): Promise<KycIdentity>;
+    /** POST /kyc — 지갑 링크 + 검증 시작/재개. */
+    initVerification(): Promise<KycIdentity>;
+}
+
+/** 매 호출마다 최신 access token을 읽어오는 getter. 동기/비동기 모두 허용. */
+type AccessTokenGetter = () => string | undefined | null | Promise<string | undefined | null>;
+interface HttpKycRepositoryOptions {
+    /**
+     * social 로그인 시 `X-Project-Id` 헤더로 전송 (embedded-wallet-gateway
+     * whitelist). SIWE-only DApp은 생략 가능하지만, 두 흐름 모두 지원하려면
+     * embeddedProjectId(미설정 시 crossProjectId)를 넘기는 걸 권장.
+     */
+    projectId?: string;
+    /**
+     * Bearer access token getter. 반환값이 있으면 `Authorization: Bearer <token>`
+     * 헤더를 붙인다. 쿠키 기반 세션(HttpOnly)만 쓰는 경우 생략 — 요청은 항상
+     * `credentials: 'include'`로 전송되므로 쿠키가 자동 첨부된다.
+     */
+    getAccessToken?: AccessTokenGetter;
+    /** native SDK 흐름에서만 사용. `X-App-Id`로 전송. 웹은 생략. */
+    appId?: string;
+    /** `X-App-Id`와 함께 전송. 'android' | 'ios' | 'windows'. 웹은 생략. */
+    appType?: string;
+    /** override 안 하면 getKycBaseUrl() 사용. */
+    baseUrl?: string;
+    paths?: Partial<KycEndpointPaths>;
+    /** GET/POST 공통 타임아웃. 기본 10초. */
+    timeoutMs?: number;
+}
+/**
+ * cross-auth `/kyc` 호출 리포지토리.
+ *
+ * 엔드포인트 (cross-auth swagger 기준):
+ *  - GET  /kyc → 읽기 전용. 신원(SIWE/social) + identity-core-api KYC 상태.
+ *  - POST /kyc → 지갑 링크(idempotent) + 검증 시작/재개(idempotent). 미승인 시
+ *                Sumsub SDK 토큰(kyc_token) surfacing.
+ *  GET/POST 모두 요청 바디가 없다 (식별은 토큰/헤더로만).
+ *  응답 envelope: { code, message, data: KYCResp }.
+ *
+ * 인증:
+ *  - BearerAuth(Authorization) 또는 HttpOnly 쿠키(credentials: include).
+ *  - social login은 추가로 `X-Project-Id` + client identifier가 필요하다:
+ *    web은 `Origin`(브라우저가 cross-origin 요청에 자동 첨부 — 수동 설정 불가),
+ *    native는 `X-App-Id` + `X-App-Type`. 이 조합이 없으면 백엔드가 401을 준다.
+ *
+ * 실패는 throw(KycError) — 상태 읽기는 호출자가 알아야 하므로 fail-closed로
+ * 숨기지 않는다. 401/403은 UNAUTHORIZED, 그 외는 STATUS_FAILED/START_FAILED.
+ */
+declare class HttpKycRepository implements KycRepository {
+    private readonly projectId?;
+    private readonly getAccessToken?;
+    private readonly appId?;
+    private readonly appType?;
+    private readonly baseUrl;
+    private readonly paths;
+    private readonly timeoutMs;
+    constructor(opts?: HttpKycRepositoryOptions);
+    fetchStatus(): Promise<KycIdentity>;
+    initVerification(): Promise<KycIdentity>;
+    private request;
+    private buildHeaders;
+    private parseIdentity;
+}
+
+/**
+ * 브라우저 환경용 KycPort 구현.
+ *
+ * 외부 통신은 KycRepository로 위임 — 기본은 HttpKycRepository(fetch),
+ * 테스트/데모에서는 mock repository를 주입할 수 있다. KYC는 온램프와 달리
+ * popup/postMessage 같은 브라우저 부수효과가 없다 (Sumsub websdk 실행은
+ * DApp이 `sdkToken`으로 직접 처리). 따라서 이 어댑터는 얇은 위임 레이어로,
+ * 추후 status 캐싱/이벤트 같은 정책의 확장 지점만 확보해 둔다.
+ */
+interface BrowserKycAdapterOptions {
+    /**
+     * social 로그인 시 `X-Project-Id`로 전달. kitConfig.embeddedProjectId
+     * (미설정 시 crossProjectId)를 넘기는 걸 권장. `repository`를 직접 주입하는
+     * 경우 무시되어도 무방.
+     */
+    projectId?: string;
+    /** Bearer access token getter. 쿠키 세션만 쓰면 생략 가능. */
+    getAccessToken?: AccessTokenGetter;
+    /** native SDK 흐름에서만 사용. 웹은 생략. */
+    appId?: string;
+    /** `X-App-Id`와 함께 전송. 'android' | 'ios' | 'windows'. 웹은 생략. */
+    appType?: string;
+    /**
+     * 외부 통신 리포지토리. 미주입 시 옵션으로 HttpKycRepository를 자동 구성.
+     * 테스트/데모에서는 mock 등을 주입.
+     */
+    repository?: KycRepository;
+}
+declare class BrowserKycAdapter implements KycPort {
+    private readonly repository;
+    constructor(opts?: BrowserKycAdapterOptions);
+    getStatus(): Promise<KycIdentity>;
+    startVerification(): Promise<KycIdentity>;
+}
+
+/**
+ * 프레임워크 무관 함수형 진입점.
+ *
+ * React/Vue/Svelte/vanilla 어디서든:
+ *   const kyc = createKyc({ projectId, getAccessToken: () => token });
+ *   const me = await kyc.getStatus();          // GET  /kyc
+ *   if (!me.verified) {
+ *     const started = await kyc.start();        // POST /kyc
+ *     // started.sdkToken 으로 Sumsub websdk 실행 (DApp 책임)
+ *   }
+ *
+ * 내부적으로 BrowserKycAdapter + GetKycStatusUseCase/StartKycUseCase 조립.
+ */
+
+interface CreateKycOptions extends BrowserKycAdapterOptions {
+}
+interface Kyc {
+    /** 내부 어댑터. 고급 사용자가 직접 다뤄야 할 때 노출. */
+    readonly port: KycPort;
+    /** GET /kyc — 읽기 전용 신원 + KYC 상태. */
+    getStatus(): Promise<KycIdentity>;
+    /** POST /kyc — 지갑 링크 + 검증 시작/재개. Sumsub SDK 토큰 surfacing. */
+    start(): Promise<KycIdentity>;
+}
+declare function createKyc(options?: CreateKycOptions): Kyc;
+
+/**
+ * KYC 검증 진입 — 응답 형태에 따라 자동 분기한다.
+ *
+ *  1) 기본: `identity.verificationUrl`(백엔드 hosted URL)이 있으면 새 탭으로 연다.
+ *     벤더 중립 — CDN·CSP 불필요. (제안: docs/kyc/01-verification-link-proposal.md)
+ *  2) fallback: URL이 없고 `identity.sdkToken`만 있으면 Sumsub WebSDK를
+ *     전체화면 모달에 launch한다 (벤더 결합은 여기서만).
+ *
+ * 완료 판정의 진실의 소스는 webhook이며, 호출자는 `GET /kyc` 폴링으로 최종
+ * 상태를 확인해야 한다 (두 경로 공통).
+ */
+type KycVerificationMode = 'url' | 'websdk';
+/**
+ * 검증 URL을 어디서 열지 (verificationUrl 모드에만 적용).
+ *  - 'newWindow' (기본): 새 탭/창 (`window.open`)
+ *  - 'currentWindow': 현재 창을 URL로 이동 (`location.assign`) — 검증 후 백엔드
+ *    `redirect`로 앱에 복귀
+ * WebSDK fallback(sdkToken)은 창 개념이 없어 항상 현재 창의 모달로 렌더된다.
+ */
+type KycLaunchTarget = 'newWindow' | 'currentWindow';
+interface KycVerificationHandle {
+    /** 'url' = 새 탭으로 열림, 'websdk' = 인페이지 모달 launch. */
+    readonly mode: KycVerificationMode;
+    /** websdk 모드: 모달을 닫는다. url 모드: no-op. */
+    close(): void;
+}
+interface LaunchKycVerificationOptions {
+    /**
+     * verificationUrl 모드에서 URL을 새 창/현재 창 중 어디서 열지. 기본 'newWindow'.
+     * WebSDK fallback에는 적용되지 않는다(항상 현재 창 모달).
+     */
+    target?: KycLaunchTarget;
+    /**
+     * websdk fallback에서 토큰 만료 시 새 SDK 토큰을 받아오는 콜백.
+     * 보통 `POST /kyc`를 다시 호출(idempotent)해 새 kyc_token을 반환한다.
+     * 미지정 시 최초 sdkToken을 재사용한다(세션이 짧으면 만료될 수 있음).
+     */
+    getFreshToken?: () => Promise<string>;
+    /** websdk 언어. 기본 'ko'. */
+    lang?: string;
+    /** url + newWindow 모드 window.open features. 기본 'noopener,noreferrer'. */
+    windowFeatures?: string;
+    onError?: (payload: unknown) => void;
+    onStatusChange?: (payload: unknown) => void;
+}
+declare function launchKycVerification(identity: KycIdentity, opts?: LaunchKycVerificationOptions): Promise<KycVerificationHandle>;
+
+export { type AccessTokenGetter as A, BrowserKycAdapter as B, type CreateKycOptions as C, DEFAULT_KYC_PATHS as D, HttpKycRepository as H, type KycPort as K, type LaunchKycVerificationOptions as L, type Unsubscribe as U, type KycIdentity as a, type BrowserKycAdapterOptions as b, type HttpKycRepositoryOptions as c, type Kyc as d, type KycEndpointPaths as e, type KycEnvironment as f, KycError as g, type KycErrorCode as h, type KycLaunchTarget as i, type KycLoginType as j, type KycRejectType as k, type KycRepository as l, type KycStatus as m, type KycVerificationHandle as n, type KycVerificationMode as o, createKyc as p, getKycBaseUrl as q, launchKycVerification as r, normalizeKycStatus as s, normalizeLoginType as t, normalizeRejectType as u };

package/dist/react/index.d.ts

@@ -0,0 +1,72 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { C as CreateKycOptions, a as KycIdentity, m as KycStatus, g as KycError, L as LaunchKycVerificationOptions, n as KycVerificationHandle, d as Kyc } from '../launchVerification-oM0NtTLd.js';
+export { h as KycErrorCode, i as KycLaunchTarget, j as KycLoginType, k as KycRejectType, o as KycVerificationMode, r as launchKycVerification } from '../launchVerification-oM0NtTLd.js';
+
+interface KycProviderProps {
+    /** createKyc options. 흔한 케이스는 { projectId, getAccessToken } 한두 줄. */
+    config: CreateKycOptions;
+    children: ReactNode;
+}
+/**
+ * KYC Provider — 어떤 React 앱에든 단독으로 마운트 가능.
+ * connect-kit-react를 안 쓰는 DApp도 이걸 직접 마운트해서 `useKyc`를 쓸 수 있다.
+ *
+ * `getAccessToken`은 매 요청 시점에 호출되므로, 토큰이 갱신돼도 Provider를
+ * 재마운트할 필요가 없다 — 클로저로 최신 토큰을 읽게 넘기면 된다.
+ */
+declare function KycProvider({ config, children }: KycProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseKycResult {
+    /** Provider mount 여부 (= 항상 true. 컨벤션 통일 위해 노출). */
+    isAvailable: boolean;
+    /** GET /kyc 결과. 마운트 직후엔 undefined. */
+    identity: KycIdentity | undefined;
+    /** identity?.status 단축 접근. */
+    status: KycStatus | undefined;
+    /** identity?.verified 단축 접근 (미로드 시 false). */
+    verified: boolean;
+    /** 상태 조회 중 여부. */
+    isLoading: boolean;
+    /** start() 진행 중 여부 (조회의 isLoading과 별개). */
+    isStarting: boolean;
+    /** 마지막 에러 (조회/시작 공통). 새 호출 시 null로 리셋. */
+    error: KycError | null;
+    /** 강제 재조회 (GET /kyc). */
+    refresh: () => Promise<KycIdentity | undefined>;
+    /**
+     * 검증 시작/재개 (POST /kyc). 성공 시 identity를 갱신하고 반환한다.
+     * 저수준 훅 — 진입(UI)까지 한 번에 하려면 `startVerification`을 쓴다.
+     */
+    start: () => Promise<KycIdentity>;
+    /**
+     * 검증 시작 + 진입까지 일괄 처리 (POST /kyc → 검증 진입).
+     * - `verificationUrl`이 오면 새 탭으로 연다(기본).
+     * - 없고 `sdkToken`만 오면 Sumsub WebSDK를 모달에 launch(fallback).
+     * 토큰 만료 시 재발급은 내부에서 `start()`를 재호출해 처리한다.
+     */
+    startVerification: (opts?: Omit<LaunchKycVerificationOptions, 'getFreshToken'>) => Promise<{
+        identity: KycIdentity;
+        handle: KycVerificationHandle;
+    }>;
+}
+interface UseKycOptions {
+    /** 마운트 시 자동으로 GET /kyc를 호출할지. 기본 true. */
+    autoFetch?: boolean;
+}
+/**
+ * KYC 메인 훅. 마운트 시 GET /kyc로 상태를 자동 조회하고, start()로 POST /kyc를
+ * 호출해 검증을 시작/재개한다. 인증(Bearer 토큰/쿠키)은 Provider에 주입된
+ * createKyc 옵션이 담당한다.
+ */
+declare function useKyc(opts?: UseKycOptions): UseKycResult;
+
+/**
+ * KycProvider 안에서는 Kyc facade를 반환, 밖에서는 null.
+ *
+ * "있으면 쓰고, 없으면 비활성"으로 동작하고 싶은 컴포넌트가 React 훅 규칙을
+ * 어기지 않고 KycProvider 마운트 여부를 분기할 수 있게 한다.
+ */
+declare function useOptionalKyc(): Kyc | null;
+
+export { CreateKycOptions, Kyc, KycError, KycIdentity, KycProvider, type KycProviderProps, KycStatus, KycVerificationHandle, LaunchKycVerificationOptions, type UseKycOptions, type UseKycResult, useKyc, useOptionalKyc };

package/dist/react/index.js

@@ -0,0 +1 @@
+import{a as u,k as C,l as f}from"../chunk-2477RDFG.js";import{useMemo as w}from"react";import{createContext as E,useContext as b}from"react";var i=E(null);function v(){let t=b(i);if(!t)throw new Error("useKyc must be used within <KycProvider>");return t}import{jsx as g}from"react/jsx-runtime";function I({config:t,children:o}){let n=w(()=>({kyc:C(t)}),[t.projectId,t.appId,t.appType,t.getAccessToken,t.repository]);return g(i.Provider,{value:n,children:o})}import{useCallback as d,useEffect as T,useRef as j,useState as l}from"react";function L(t={}){let{kyc:o}=v(),n=t.autoFetch??!0,[s,p]=l(void 0),[V,m]=l(n),[P,x]=l(!1),[k,a]=l(null),c=j(null),h=e=>e instanceof u?e:new u("NETWORK_ERROR",e instanceof Error?e.message:"KYC request failed"),K=d(async()=>{c.current&&(c.current.cancelled=!0);let e={cancelled:!1};c.current=e,a(null),m(!0);try{let r=await o.getStatus();return e.cancelled?void 0:(p(r),r)}catch(r){if(e.cancelled)return;a(h(r));return}finally{e.cancelled||m(!1)}},[o]),y=d(async()=>{a(null),x(!0);try{let e=await o.start();return p(e),e}catch(e){let r=h(e);throw a(r),r}finally{x(!1)}},[o]),O=d(async e=>{let r=await y(),R=await f(r,{...e,getFreshToken:async()=>(await y()).sdkToken??""});return{identity:r,handle:R}},[y]);return T(()=>{if(n)return K(),()=>{c.current&&(c.current.cancelled=!0)}},[n,K]),{isAvailable:!0,identity:s,status:s?.status,verified:s?.verified??!1,isLoading:V,isStarting:P,error:k,refresh:K,start:y,startVerification:O}}import{useContext as S}from"react";function U(){return S(i)?.kyc??null}export{u as KycError,I as KycProvider,f as launchKycVerification,L as useKyc,U as useOptionalKyc};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@nexus-cross/kyc",
+  "version": "1.3.4-beta.10",
+  "description": "cross-auth KYC integration (identity + Sumsub status). Framework-agnostic core + React adapter.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "echo 'no tests yet'",
+    "typecheck": "tsc --noEmit"
+  }
+}