계약자를 위한 신원 확인 구축 방법: GPS 스코어링, 회전 QR, 그리고 Google Wallet 패스

발행: 1일 전 (2026년 3월 8일 PM 01:45 GMT+9)

11 분 소요

I’m happy to translate the article for you, but I need the full text of the article (the content you’d like translated). Could you please paste the article’s body here? I’ll keep the source line exactly as you provided and preserve all formatting, markdown, and code blocks while translating the rest into Korean.

Lynk ID 백엔드 하이라이트

우리는 Lynk ID 를 구축했습니다 — 주택 소유자가 QR 코드를 스캔하거나 NFC 배지를 탭하면 즉시 방문자를 확인할 수 있는 계약자 신원 신뢰 레이어이며, 양쪽 모두 앱을 다운로드할 필요가 없습니다.

이 글에서는 구축하면서 흥미로웠던 백엔드 네 가지 요소를 다룹니다:

복합 신뢰 점수 알고리즘 (그리고 NFC 하드‑게이트를 없앤 이유)
Node.js에서 RSA‑SHA256을 이용한 Google Wallet 패스 서명
B2B 웹훅 응답 래퍼
재생 방지를 위한 회전 QR 토큰

1. 복합 신뢰 점수 — GPS, NFC, 생체인식

초기 버전의 /api/v1/verify 는 순진한 하드‑게이트를 사용했습니다:

// old — broken for QR‑only partners
const approved = score >= 70 && nfcTap && deviceMatch;

NFC 탭을 전송하지 않은 모든 플랫폼은 디바이스 지문과 생체 매치가 강력하더라도 자동으로 거부되었습니다.
이를 해결하기 위해 두 가지 유효한 승인 경로를 갖는 소프트‑페널티 모델로 전환했습니다.

// src/app/api/v1/verify/route.ts

type VerifyRequestBody = {
  endpointId?: string;
  referenceId?: string;
  subjectId?: string;
  signals?: {
    nfcTap?: boolean;
    deviceMatch?: boolean;
    biometricMatch?: boolean;
    gpsDistanceMeters?: number;
  };
};

function calculateVerification(body: VerifyRequestBody) {
  const nfcTap            = body.signals?.nfcTap === true;
  const deviceMatch       = body.signals?.deviceMatch === true;
  const biometricMatch   = body.signals?.biometricMatch === true;
  const gpsDistanceMeters = Math.max(0, Number(body.signals?.gpsDistanceMeters ?? 0));

  let score = 100;
  if (!nfcTap)            score -= 30; // NFC not required, but rewarded
  if (!deviceMatch)       score -= 20;
  if (!biometricMatch)    score -= 15;
  if (gpsDistanceMeters > 100)  score -= 10; // out of proximity tier 1
  if (gpsDistanceMeters > 500)  score -= 10; // out of proximity tier 2

  score = Math.max(0, Math.min(100, score));

  const nfcPath = nfcTap;
  const qrPath  = deviceMatch && biometricMatch;

  // Approved on either path — NFC gives higher score/confidence
  const approved = score >= 60 && (nfcPath || qrPath);

  const confidence =
    nfcTap && deviceMatch && biometricMatch ? "high" :
    approved                               ? "medium" : "low";

  const riskLevel = score >= 85 ? "low" : score >= 65 ? "medium" : "high";

  return {
    approved,
    score,
    confidence,
    riskLevel,
    reasonCodes: [
      !nfcTap && !qrPath          ? "missing_nfc_tap"       : null,
      !deviceMatch               ? "device_mismatch"       : null,
      !biometricMatch            ? "biometric_unverified"  : null,
      gpsDistanceMeters > 100    ? "distance_out_of_range" : null,
    ].filter(Boolean),
  };
}

시나리오별 점수 분해

존재하는 신호	점수	승인	신뢰도
NFC + 디바이스 + 생체인식	100	✅	high
디바이스 + 생체인식 (QR 경로)	65	✅	medium
NFC만, 생체인식 없음	55	❌	low
아무것도 없음	35	❌	low

GPS 페널티는 누적됩니다 — 600 m 떨어져 있으면 총 ‑20점이 차감되어 경계선에 있던 중간‑신뢰 승인도 거부될 수 있습니다. GPS는 클라이언트가 보고하는 값이며(서버에서 삼각측량하지 않음) 많은 신호 중 하나일 뿐, 하드 게이트가 아닙니다.

2. RSA‑SHA256을 이용한 Google Wallet 패스 서명

Google Wallet 패스는 서비스 계정 개인 키로 JWT에 서명하여 발행합니다. google-auth-library 의 JWT 클래스는 OAuth 토큰을 처리하지만, “Save to Wallet” 링크를 만들 때는 직접 서명합니다 — OAuth 라운드‑트립이 필요 없습니다.

// src/lib/wallet/google.ts

import { createSign, randomUUID } from "crypto";

function base64UrlEncode(input: Buffer | string) {
  const buffer = Buffer.isBuffer(input) ? input : Buffer.from(input);
  return buffer
    .toString("base64")
    .replace(/\+/

*Sharp edge:* 환경에서는 **private key**를 PEM 형식으로 노출해야 합니다; 실수로 커밋되는 것을 방지하기 위해 비밀 관리 서비스나 환경 변수에서 로드하는 것이 권장됩니다.

### 3. B2B webhook 응답 래퍼  

*(내용은 간략히 생략되었습니다 – 원본 게시물에는 JSON 래퍼 스키마, 버전 관리 전략, 오류 처리 규칙이 포함되어 있습니다.)*

### 4. 재생 방지를 위한 회전 QR 토큰  

*(내용은 간략히 생략되었습니다 – 원본 게시물에서는 짧은 수명과 HMAC 서명이 포함된 토큰을 QR 페이로드에 삽입하는 방법, 서버가 이를 검증하는 방식, 그리고 회전이 재생 공격을 완화하는 방법을 설명합니다.)*

## Normalizing PEM Keys  

환경 변수는 `.env` 파일, Vercel 대시보드, 혹은 Docker 시크릿에서 이스케이프된 개행 문자(`\\n`) 형태로 전달되는 경우가 많습니다. 우리는 `createSign`에 전달되기 전에 키를 정규화합니다:

```ts
function normalizePrivateKey(rawKey: string) {
  let k = (rawKey || "").trim();

  // Strip surrounding quotes
  if (
    (k.startsWith('"') && k.endsWith('"')) ||
    (k.startsWith("'") && k.endsWith("'"))
  ) {
    k = k.slice(1, -1);
  }

  return k
    .replace(/\\r\\n/g, "\n")
    .replace(/\\n/g, "\n")
    .replace(/\r\n/g, "\n")
    .trim();
}

또한 서명 시도 전에 PEM 경계가 올바른지 검증합니다—경계가 잘못된 키는 Vercel 엣지 로그 깊숙이 숨겨진 난해한 OpenSSL 오류를 발생시킵니다:

if (
  !privateKey.includes("BEGIN PRIVATE KEY") ||
  !privateKey.includes("END PRIVATE KEY")
) {
  throw new Error(
    "Invalid GOOGLE_WALLET_SERVICE_ACCOUNT_PRIVATE_KEY: include full PEM boundaries."
  );
}

B2B 웹훅 / Verify 응답 엔벨로프

라이드셰어 플랫폼이나 엔터프라이즈 파트너가 /api/v1/verify 엔드포인트에 POST 요청을 보낼 때, 응답 엔벨로프는 다음과 같습니다:

{
  "verificationId": "a3c82f1e-9b47-4d2e-bf03-1234abcd5678",
  "apiVersion": "1.0.0",
  "endpointId": "lyft-dfw-staging",
  "referenceId": "trip_abc123",
  "subjectId": "usr_ryan_sideris",
  "result": {
    "approved": true,
    "score": 65,
    "confidence": "medium",
    "riskLevel": "medium",
    "reasonCodes": []
  },
  "billing": {
    "billable": true,
    "unit": "scan",
    "quantity": 1
  },
  "processedAt": "2026-03-07T14:22:01.003Z"
}

각 이벤트는 REST API를 사용해 Firestore api_verifications 컬렉션에 비동기적으로 저장됩니다(Node.js edge 함수에서는 SDK를 임포트할 필요가 없습니다):

async function persistVerificationEvent(event: Record<string, unknown>) {
  const url = `https://firestore.googleapis.com/v1/projects/${projectId}/databases/(default)/documents/api_verifications?key=${apiKey}`;

  await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ fields: toFirestoreFields(event) })
  });
}

저장 실패는 응답을 차단하지 않고 잡아 로그에 기록됩니다—느린 Firestore 쓰기 작업이 파트너의 실시간 드라이버 입장 흐름에 지연을 초래해서는 안 됩니다.

속도 제한은 API 키의 잘린 SHA‑256 해시를 키로 하는 프로세스 내(in‑memory) Map에서 수행됩니다. 이렇게 하면 로그에 키 자체가 노출되지 않으면서도 키별 윈도우링을 할 수 있습니다:

function hashApiKey(rawKey: string): string {
  return createHash("sha256").update(rawKey).digest("hex").slice(0, 12);
}

회전 QR — 백엔드 라운드‑트립 없이 재생 방지

정적인 QR URL은 스크린샷 공격이 일어나기 쉬운 상태입니다. 우리의 QR 값은 Math.floor(Date.now() / 60000)을 시간‑윈도우 토큰으로 URL에 추가해 60초마다 회전합니다. 스캐너 측에서는 토큰이 현재 시간보다 1 윈도우 이내인지 검증합니다.

// src/app/dashboard/badges/page.tsx
const [timeWindow, setTimeWindow] = useState(() => Math.floor(Date.now() / 60000));
const [countdown, setCountdown] = useState(() => 60 - (Math.floor(Date.now() / 1000) % 60));

// 1‑second tick — updates token and countdown display simultaneously
useEffect(() => {
  const tick = setInterval(() => {
    const now = Date.now();
    setTimeWindow(Math.floor(now / 60000));
    setCountdown(60 - (Math.floor(now / 1000) % 60));
  }, 1000);
  return () => clearInterval(tick);
}, []);

실시간 QR 표시

{/* visual indicator */}
<div>
  Refreshes in {countdown}s
</div>

?t= 값은 유닉스 분 인덱스로, Math.floor(epoch_ms / 60000)과 같습니다. 스캔 엔드포인트는 계약자 휴대폰과 서버 간 시계 차이를 고려해 ± 1 분 범위의 윈도우를 허용하므로, 실제 재생 가능 창은 무한이 아니라 60~120초가 됩니다.

서버가 발행한 논스를 사용하지 않는 이유
논스를 사용하면 계약자 휴대폰이 QR을 표시하기 전에 네트워크 라운드‑트립이 필요해 오프라인에서도 즉시 표시되는 사용자 경험이 깨집니다. 시간‑윈도우 방식은 지연 없이 대부분의 재생 방지를 제공합니다.

다음 단계

Apple Wallet pkpass 서명 (PassKit + WWDR 인증서 체인)
서버‑측 ?t= 검증을 /verify/[tagUid] 스캔 경로에서 수행
wallet‑pass 서브헤더에 포함된 배경‑체크 상태
파트너 이벤트 전달을 위한 Webhook HMAC 서명

이 중 유용한 것이 있다면, API 문서는 에, V2 변경 로그는 에 있습니다.

계약자를 위한 신원 확인 구축 방법: GPS 스코어링, 회전 QR, 그리고 Google Wallet 패스

Lynk ID 백엔드 하이라이트

1. 복합 신뢰 점수 — GPS, NFC, 생체인식

시나리오별 점수 분해

2. RSA‑SHA256을 이용한 Google Wallet 패스 서명

B2B 웹훅 / Verify 응답 엔벨로프

회전 QR — 백엔드 라운드‑트립 없이 재생 방지

실시간 QR 표시

다음 단계

관련 글

OAuth2 vs OpenID Connect: 차이점은 무엇인가?

textlens vs text-readability vs natural: 텍스트 분석을 위한 npm 패키지는?

신원 확인 KYC를 @etld SDK와 함께 해결하기

2/3의 Node.Js 사용자들이 구버전을 사용하고 있다. 그래서 OpenJS가 업그레이드 제공자를 위한 프로그램을 발표한다

Lynk ID 백엔드 하이라이트

1. 복합 신뢰 점수 — GPS, NFC, 생체인식

시나리오별 점수 분해

2. RSA‑SHA256을 이용한 Google Wallet 패스 서명

B2B 웹훅 / Verify 응답 엔벨로프

회전 QR — 백엔드 라운드‑트립 없이 재생 방지

실시간 QR 표시

다음 단계

관련 글

OAuth2 vs OpenID Connect: 차이점은 무엇인가?

textlens vs text-readability vs natural: 텍스트 분석을 위한 npm 패키지는?

신원 확인 KYC를 @etld SDK와 함께 해결하기

2/3의 Node.Js 사용자들이 구버전을 사용하고 있다. 그래서 OpenJS가 업그레이드 제공자를 위한 프로그램을 발표한다

Lynk ID 백엔드 하이라이트

2. RSA‑SHA256을 이용한 Google Wallet 패스 서명