공개키만 남기고 비밀번호를 걷어내기: Node.js와 SimpleWebAuthn으로 패스키 등록·인증을 구현하고 기존 로그인과 단계적으로 통합하기

-- 기존 users 테이블은 그대로 두고 credentials 테이블을 추가
CREATE TABLE credentials (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id       UUID NOT NULL REFERENCES users(id),
  credential_id TEXT NOT NULL UNIQUE,   -- base64url 인코딩
  public_key    BYTEA NOT NULL,         -- COSE 인코딩 공개키
  counter       BIGINT NOT NULL DEFAULT 0,
  transports    TEXT[],                 -- ['internal', 'hybrid', 'usb']
  created_at    TIMESTAMPTZ DEFAULT now(),
  last_used_at  TIMESTAMPTZ
);

npm install @simplewebauthn/server @simplewebauthn/browser
# 세션 스토어가 없는 경우
npm install express-session connect-redis

// session.d.ts
import 'express-session';
 
declare module 'express-session' {
  interface SessionData {
    registrationChallenge?: string;
    authChallenge?: string;
    userId?: string;
    // authUserId는 discoverable 플로우에서 세션에 의존하지 않으므로 포함하지 않음
  }
}

import { generateRegistrationOptions } from '@simplewebauthn/server';
import type { Request, Response } from 'express';
 
export async function registerStart(req: Request, res: Response) {
  // req.user는 Passport.js 또는 직접 구현한 세션 미들웨어가 채워주는 현재 로그인 사용자
  const user = req.user;
 
  // 이미 등록된 자격증명은 excludeCredentials로 중복 방지
  const existingCredentials = await db.credentials.findByUserId(user.id);
 
  const options = await generateRegistrationOptions({
    rpName: 'My App',
    rpID: process.env.RP_ID ?? 'localhost',
    userID: new Uint8Array(Buffer.from(user.id)),
    userName: user.email,
    userDisplayName: user.name,
    // 'none': 기기 제조사 진위 확인(attestation)을 요구하지 않음
    // 포기하는 것: 이 자격증명이 정말 Secure Enclave에서 생성됐는지 서버에서 검증 불가
    // 의료·금융·엔터프라이즈 환경에서는 'direct' 또는 'indirect' 검토 필요
    attestationType: 'none',
    excludeCredentials: existingCredentials.map(c => ({
      id: c.credentialId,
      transports: c.transports,
    })),
    authenticatorSelection: {
      residentKey: 'preferred',
      // 'preferred'는 UV 미지원 장치에서 사용자 검증을 건너뛸 수 있어 AAL1 수준
      // NIST SP 800-63-4 AAL2 요건이 필요한 서비스는 'required'로 변경
      userVerification: 'preferred',
    },
  });
 
  // 챌린지를 세션에 저장 — finish 단계 검증에 반드시 필요
  // 재전송 공격 방지를 위해 세션 TTL을 5~10분으로 제한할 것 (아래 세션 설정 참고)
  req.session.registrationChallenge = options.challenge;
 
  res.json(options);
}

import { verifyRegistrationResponse } from '@simplewebauthn/server';
 
export async function registerFinish(req: Request, res: Response) {
  const expectedChallenge = req.session.registrationChallenge;
 
  if (!expectedChallenge) {
    return res.status(400).json({ error: '챌린지가 없습니다. 등록을 다시 시작해주세요.' });
  }
 
  try {
    const { verified, registrationInfo } = await verifyRegistrationResponse({
      response: req.body,
      expectedChallenge,
      expectedOrigin: process.env.EXPECTED_ORIGIN ?? 'http://localhost:3000',
      expectedRPID: process.env.RP_ID ?? 'localhost',
    });
 
    if (!verified || !registrationInfo) {
      return res.status(400).json({ error: '검증 실패' });
    }
 
    // v13의 credential 구조 — v12의 credentialID/credentialPublicKey와 이름이 다름
    const { credential } = registrationInfo;
 
    await db.credentials.create({
      userId: req.user.id,
      credentialId: credential.id,
      publicKey: credential.publicKey,
      counter: credential.counter,
      transports: credential.transports ?? [],
    });
 
    delete req.session.registrationChallenge;
 
    res.json({ verified: true });
  } catch (err) {
    // verifyRegistrationResponse는 파싱 오류·서명 불일치 등에서 예외를 던짐
    // try-catch 없이 배포하면 Express 기본 핸들러가 스택 트레이스를 노출할 수 있음
    console.error('패스키 등록 검증 실패:', err);
    return res.status(400).json({ error: '등록 처리 중 오류가 발생했습니다.' });
  }
}

import { generateAuthenticationOptions } from '@simplewebauthn/server';
 
export async function loginStart(req: Request, res: Response) {
  const { email } = req.body; // optional — 없으면 discoverable 플로우
 
  let allowCredentials: { id: string; transports: string[] }[] | undefined;
 
  if (email) {
    const user = await db.users.findByEmail(email);
    if (user) {
      const userCredentials = await db.credentials.findByUserId(user.id);
      allowCredentials = userCredentials.map(c => ({
        id: c.credentialId,
        transports: c.transports,
      }));
    }
    // user가 없어도 빈 allowCredentials로 처리 — 사용자 존재 여부 노출 방지
  }
 
  const options = await generateAuthenticationOptions({
    rpID: process.env.RP_ID ?? 'localhost',
    userVerification: 'preferred',
    ...(allowCredentials && { allowCredentials }),
  });
 
  req.session.authChallenge = options.challenge;
  // userId는 여기서 세션에 저장하지 않음
  // finish 단계에서 credentialId로 DB를 조회해 도출 — discoverable 플로우 지원의 핵심
 
  res.json(options);
}

import { verifyAuthenticationResponse } from '@simplewebauthn/server';
 
export async function loginFinish(req: Request, res: Response) {
  const expectedChallenge = req.session.authChallenge;
 
  if (!expectedChallenge) {
    return res.status(400).json({ error: '인증 세션이 만료되었습니다.' });
  }
 
  try {
    // credentialId로 먼저 조회 — discoverable·이메일 플로우 모두 동작
    const dbCredential = await db.credentials.findByCredentialId(req.body.id);
 
    if (!dbCredential) {
      return res.status(400).json({ error: '자격증명을 찾을 수 없습니다.' });
    }
 
    const { verified, authenticationInfo } = await verifyAuthenticationResponse({
      response: req.body,
      expectedChallenge,
      expectedOrigin: process.env.EXPECTED_ORIGIN ?? 'http://localhost:3000',
      expectedRPID: process.env.RP_ID ?? 'localhost',
      credential: {             // v13: 파라미터명이 'credential' (v12는 'authenticator')
        id: dbCredential.credentialId,
        publicKey: dbCredential.publicKey,
        counter: dbCredential.counter,
        transports: dbCredential.transports,
      },
    });
 
    if (!verified) {
      return res.status(401).json({ error: '인증 실패' });
    }
 
    // 낙관적 잠금으로 counter 업데이트 — 동시 요청 두 개가 같은 counter로 통과하는 것을 방지
    const updated = await db.credentials.updateCounterIfMatch(
      dbCredential.id,
      authenticationInfo.newCounter,
      dbCredential.counter // 예상 counter 값 — 조회 시점과 다르면 업데이트 실패
    );
 
    if (!updated) {
      return res.status(401).json({ error: '동시 인증 충돌이 감지되었습니다.' });
    }
 
    delete req.session.authChallenge;
 
    // dbCredential에서 userId를 도출 — 이메일 없는 discoverable 플로우도 여기서 처리
    req.session.userId = dbCredential.userId;
 
    res.json({ verified: true });
  } catch (err) {
    console.error('패스키 인증 검증 실패:', err);
    return res.status(400).json({ error: '인증 처리 중 오류가 발생했습니다.' });
  }
}

-- WHERE counter = :expectedCounter 조건이 낙관적 잠금의 핵심
-- 다른 요청이 먼저 업데이트했다면 RETURNING 결과가 비어 있음
UPDATE credentials
SET counter = :newCounter, last_used_at = NOW()
WHERE id = :id AND counter = :expectedCounter
RETURNING id;

// express-session 사용 시
app.use(session({
  secret: process.env.SESSION_SECRET!,
  resave: false,
  saveUninitialized: false,
  cookie: { maxAge: 10 * 60 * 1000 }, // 10분
}));
 
// Redis로 챌린지를 별도 관리할 경우
await redis.set(`challenge:${sessionId}`, challenge, 'EX', 600); // 600초

import { startRegistration, startAuthentication } from '@simplewebauthn/browser';
 
async function registerPasskey() {
  const optionsJSON = await fetch('/register/start', {
    method: 'POST',
    credentials: 'include',
  }).then(r => r.json());
 
  // v13: { optionsJSON } 객체 형태로 전달
  const registrationResponse = await startRegistration({ optionsJSON });
 
  const result = await fetch('/register/finish', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(registrationResponse),
    credentials: 'include',
  }).then(r => r.json());
 
  return result.verified;
}
 
// email은 optional — 없으면 discoverable 플로우, 있으면 allowCredentials 플로우
async function loginWithPasskey(email?: string) {
  const optionsJSON = await fetch('/login/start', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email }),
    credentials: 'include',
  }).then(r => r.json());
 
  const authenticationResponse = await startAuthentication({ optionsJSON });
 
  const result = await fetch('/login/finish', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(authenticationResponse),
    credentials: 'include',
  }).then(r => r.json());
 
  return result.verified;
}

export async function passwordLoginFinish(req: Request, res: Response) {
  // ... 기존 비밀번호 검증 로직 ...
 
  const userCredentials = await db.credentials.findByUserId(user.id);
 
  res.json({
    success: true,
    // 패스키가 없는 사용자에게 등록 권유 플래그 반환
    suggestPasskeyRegistration: userCredentials.length === 0,
  });
}

const rpID = process.env.RP_ID ?? 'localhost';
const expectedOrigin = process.env.EXPECTED_ORIGIN ?? 'http://localhost:3000';