토스뱅크에는 400개가 넘는 배포 Pipeline 이 있습니다. Pipeline의 개수가 많아지고, 종류가 다양해지고, 동작이 복잡해지며 여러 어려움이 생기는데요. 토스뱅크에서 Pipeline을 유연하고 안전하게 운영하기 위해 노력한 이야기를 소개해 보려 합니다.
Pipeline이란?
반복하는 일을 자동화하는 시스템을 말

생산성, 안정성, 보안성을 모두 달성하기 위해선 ‘Pipeline’을 어떻게 설정해야 할까요?
다양하고 복잡한 토스뱅크의 배포 ‘Pipeline’를 안전하게 운영하기 위한 노력을 소개합니다.

유연하고 안전하게 배포 Pipeline 운영하기

전통적인 환경의 보안 아키텍처는 방화벽과 같은 경계를 기준으로 신뢰와 비신뢰를 나누어서 운영이 되고 있었는데요. 신뢰 구간에서의 추가적인 보안 통제가 없으면서 신뢰의 크기가 커진다면 그만큼 보안의 Risk들도 증가하게 된다는 한계점들이 있었고, 다원화 된 Identity 관리, 보안 솔루션 관리, 재택근무 환경과 오피스 

왜 보안이 강화될수록, 업무는 불편해지는 걸까요? 
금융에서 가장 중요한 가치인 ‘안전’과 혁신을 위한 ‘업무 편의성’, 두 마리 토끼를 모두 잡기 위한 여정을 소개합니다.  

금융사 최초의 Zero Trust 아키텍처 도입기

더 완벽한 보안에 도전하는 토스의 여정은 어떨까요? 매일 더 안전해지는 서비스를 만드는 토스의 ‘Security Review’를 소개합니다.

보안의 끝없는 Next Level을 향해, 토스의 Security Review

토스 보안기술팀(Security Tech)에서는 개발 서비스 외에도 회사에서 사용하는 프레임워크나 Third-party 시스템의 취약점을 연구하고 있어요.
이번 아티클에서는 Node.js의 Built-in API 중 하나인 url.parse() 의 Hostname Spoofing 취약점을 발견하고 안전한 코드로 패치될 수 있도록 컨트리뷰션 했던 과정을 다뤄보려 합니다.


url.parse() 취약점 발생 원인
Node.js의 url.parse()는 WHATWG URL API가 아닌 자체적인 스펙으로 개발된 함수에요.
WHATWG URL API
WHATWG는 Web Hypertext Application Technology Working Group의 약어로 국제 웹 표준화 그룹을 뜻해요. WHATWG URL API 는 국제 표준 스펙으로 URL(Uniform Resource Locator)을 다룰 수 있도록 제공되는 API입니다.  
WHATWG URL API가 등장하기 전에 자체적으로 개발된 URL 파싱 함수로 보이는데요. 표준 스펙이 아니다 보니 다른 파서(parser)와 결과가 다르고, 이 때문에 예상하기 어려운 코드 흐름도 발생했어요.
url.parse()에서는 hostname을 잘못된 방식으로 파싱하는 취약점이 있었는데요. 아래 보이는 Node.js url 라이브러리의 getHostname() 함수에서 발생했어요.
/* comment
해당 취약점은 v19.1.0에서 패치되었습니다. 
아래 코드는 v19.1.0 이전 버전에서 확인할 수 있습니다.
*/
function getHostname(self, rest, hostname) {
  for (let i = 0; i < hostname.length; ++i) {
    const code = hostname.charCodeAt(i);
    const isValid = (code >= CHAR_LOWERCASE_A && code <= CHAR_LOWERCASE_Z) ||
                    code === CHAR_DOT ||
                    (code >= CHAR_UPPERCASE_A && code <= CHAR_UPPERCASE_Z) ||
                    (code >= CHAR_0 && code <= CHAR_9) ||
                    code === CHAR_HYPHEN_MINUS ||
                    code === CHAR_PLUS ||
                    code === CHAR_UNDERSCORE ||
                    code > 127;

    // Invalid host character
    if (!isValid) {
      self.hostname = hostname.slice(0, i);
      return `/${hostname.slice(i)}${rest}`;
    }
  }
  return rest;
}
getHostname() 함수의 로직은 단순해요. 반복문으로 전달된 문자열의 문자를 하나씩 가져온 뒤, isvalid 조건에 맞는 값을 구하는 로직인데요. 조건에 맞지 않는 문자가 발견되면, 이전 문자까지 문자열을 slice하고 hostname으로 설정해요. 그 뒤로 오는 문자들은 모두 path로 설정하고요.
isValid 의 조건을 정규식으로 표현해보면 /[a-zA-Z0-9\.\-\+_]/u 와 같은데요(ECMAScript 기준). “hostname으로는 저 범위의 문자들만 올 수 있어!”라고 설정해둔 것이죠. hostname에 올 수 없는 문자열은 모두 path로 정의하고요.

디버깅 코드
function getHostname(self, rest, hostname) {
    console.log(`[DEBUG] getHostname() arg: ${hostname}`); //debug
    for (let i = 0; i < hostname.length; ++i) {
      const code = hostname.charCodeAt(i);
      const isValid = (code >= CHAR_LOWERCASE_A && code <= CHAR_LOWERCASE_Z) ||
                      code === CHAR_DOT ||
                      (code >= CHAR_UPPERCASE_A && code <= CHAR_UPPERCASE_Z) ||
                      (code >= CHAR_0 && code <= CHAR_9) ||
                      code === CHAR_HYPHEN_MINUS ||
                      code === CHAR_PLUS ||
                      code === CHAR_UNDERSCORE ||
                      code > 127;
    
        console.log(`[DEBUG] getHostname(${i}): ${hostname.slice(0, i)}`); //debug
      // Invalid host character
      if (!isValid) {
        console.log("[DEBUG] result hostname: " + hostname.slice(0,i)); //debug
        self.hostname = hostname.slice(0, i);
        console.log(`[DEBUG] result path: /${hostname.slice(i)}${rest}`); //debug

        return `/${hostname.slice(i)}${rest}`;
      }
    }
    return rest;
  }
getHostname() 함수에 디버깅 코드를 추가해보면, 실제로 isValid 조건에 해당하지 않는 문자가 반복문에 오면, hostname 파싱을 중단해요. 나머지 문자열은 앞에 / 를 붙여 path로 사용하고요.
그래서 http://EVIL_DOMAIN*.toss.im 의 hostname이 EVIL_DOMAIN 이 되어버리면서 Hostname Spoofing 취약점이 발생해요.
Hostname Spoofing
Hostname Spoofing은 시스템을 대상으로 Hostname을 속이는 해킹 기법을 말합니다.
Spoofing은 ‘속이다’라는 사전적 의미를 갖고 있으며, 시스템을 대상으로 어떠한 정보를 속이는 해킹 기법을 Spoofing이라고 합니다.


WHATWG URL API ↔ url.parse() 비교
반면 WHATWG URL AP 의 hostname 파싱 결과는 evil_domain*.toss.im 입니다. 


Reserved Characters
Node.js에서 hostname을 왜 이렇게 파싱할까요? RFC 3986는 Standard URI Syntax 를 정의해둔 문서인데요. 2.2 Reserved Characters를 보면 그 이유를 찾을 수 있어요.

Reserved Characters는 URI를 구성할 수 있으면서 특수 목적을 가진 문자가 예약된 것입니다. 예시로는 port 구분자로 사용되는 : 또는  path 구분자로 사용되는 /가 있어요.  따라서, *, !, $, :, # 와 같은 문자들은 hostname으로 사용할 수 없습니다. 정의된 문자들은 gethostName()의 isValid 조건과 비슷하죠.
취약점 악용 시나리오
이러한 WHATWG URL API ↔ url.parse() 간 파싱 결과 차이는 서비스의 도메인 검증로직을 우회하는데 악용할 수 있어요. 간단한 예시를 함께 살펴볼게요.
// server.ts (exec command: ts-node server.ts)
/* dependencise
	express@^4.18.1
	ts-node@^10.9.1
	typescript@^4.3.2
	node-fetch@2
	@types/node-fetch@^2.6.2
*/
import express, { Request, Response, NextFunction } from 'express';

const node_fetch = require("node-fetch");
const app = express();

app.get("/image/resize", async (req: Request, res: Response) => {
	// GET메소드로 url파라미터 입력 받음
	const url = req.query.url as string; 
	// WHATWG URL API를 이용해 hostname 파싱
	const host = new URL(url).hostname; 

	// 파싱한 hostname 검증 (example.com과 *.example.com일 경우에만 분기문 통과)
	if(host === "toss.im" || host.endsWith(".toss.im")) { 
		// 검증된 hostname일 경우, node_fetch로 http request
		var result = await node_fetch.default(url); 
		var requestUrl = result.url; 
		// 파라미터로 입력된 url과 node_fetch로 실제 요청한 url 콘솔 출력
		console.log(`Input URL: ${url} / Request URL: ${requestUrl}`);
	// 그 외 경우는 reject
	} else {
		console.log("reject");
	}
});

app.listen(4540, () => {
});
위 코드는 파라미터로 URL을 입력받고, 입력된 URL을 검증 후 fetch하는 간단한 웹서버인데요. WHATWG URL API로 hostname을 가져온 뒤, toss.im 과 일치하거나 .toss.im 으로 끝나는지 도메인을 검증해요.

URL 파라미터 값을 https://google.com!.toss.im 로 입력하면 검증 로직이 우회되고 서버는 https://google.com/!.toss.im/ 으로 요청하게 되는데요. 그 이유는 아래 node-fetch 라이브러리 코드를 보면 알 수 있어요.
/* node-fetch v2.6.11 
 * [https://github.com/node-fetch/node-fetch/tree/v2.6.11]
 * request.js
 *
 * Request class contains server only options
 *
 * 
 */

import Url from 'url'; // [1]
import Stream from 'stream';
import whatwgUrl from 'whatwg-url';
import Headers, { exportNodeCompatibleHeaders } from './headers.js';
import Body, { clone, extractContentType, getTotalBytes } from './body';

const INTERNALS = Symbol('Request internals');
const URL = Url.URL || whatwgUrl.URL;

// fix an issue where "format", "parse" aren't a named export for node <10
const parse_url = Url.parse; // [2]
const format_url = Url.format;

/**
 * Wrapper around `new URL` to handle arbitrary URLs
 *
 * @param  {string} urlStr
 * @return {void}
 */
function parseURL(urlStr) {
	/*
		Check whether the URL is absolute or not

		Scheme: https://tools.ietf.org/html/rfc3986#section-3.1
		Absolute URL: https://tools.ietf.org/html/rfc3986#section-4.3
	*/
	if (/^[a-zA-Z][a-zA-Z\d+\-.]*:/.exec(urlStr)) {
		urlStr = new URL(urlStr).toString() // [3]
	}

	// Fallback to old implementation for arbitrary URLs
	return parse_url(urlStr); // [4]
}
위 코드는 node-fetch 라이브러리에서 URL을 파싱하는 코드 부분입니다. 중요한 부분은 주석으로 번호 표시를 해두었는데요.
[1] Node.js의 url 라이브러리를 가져옵니다.
[2] Node.js의 url.parse()함수를 parse_url 변수에 저장합니다.
[3] 파싱할 URL이 /^[a-zA-Z][a-zA-Z\d+\-.]*:/ 정규식 조건과 일치하면 WHATWG URL API로 파싱합니다.
[4] 그 외에 경우는 Node.js의 url.parse()함수로 파싱합니다.
https://google.com!.toss.im 은 [3] 정규식 조건에 충족되지 않으니, [4] url.parse()로 hostname이 파싱되었고 Node.js의 잘못된 파싱 방식으로 인해 검증 로직이 우회된 것이죠.
이런 예시와 같이 서비스 서버의 검증 로직을 우회하고 공격자가 원하는 임의의 도메인으로 요청하도록 하는 공격기법을 SSRF(Server Side Request Forgery)라고 하는데요. 공격자는 SSRF 공격을 통해 외부에 공개되어 있지 않은 서비스 내부 망에 접근하여 민감한 정보들을 탈취하거나, 관리자 기능들을 악용할 수 있어요.
취약점 패치 컨트리뷰션
화이트해커 문화에는 취약점을 제보하고 그에 따른 보상을 받는 버그바운티(Bug Bounty) 프로그램이 있어요. 보안에 중요한 가치를 두고 있는 기업들이 독립적으로 운영하거나 국가기관에서 운영하기도 하는데요. 토스에서도 작년에 토스 버그바운티 챌린지를 진행한 바 있고, 국가 기관에서는 한국인터넷진흥원(KISA)이 국내 소프트웨어에 대한 취약점을 제보받고 있어요.

저 또한 버그바운티 프로그램을 통해 Node.js 측에 취약점을 제보하였고, 취약점을 알맞게 패치할 수 있는 방안들에 대해 논의하면서 컨트리뷰션을 시작했어요.

기존에 Unreserved Characters 를 화이트리스트로 처리하는 방식 대신 Reserved Characters 를 블랙리스트로 처리하는 방식으로 변경하여 isValid 조건을 좀 더 엄격하게 가져가도록 패치했어요.

패치된 코드는 Pull Request에서 확인할 수 있고, 해당 Pull Request는 v19.1.0, v18.13.0 에서 적용됐어요.

추가로 기존에 Legacy 상태였던 url.parse()함수를 Deprecated로 변경하였는데요. --pending-deprecation 옵션을 사용하는 경우, 런타임에서 Deprecated 함수임을 경고하도록 패치되었습니다.


이 글을 읽으신 분들도 Node.js를 사용하고 계시다면, 취약점이 존재하는 버전을 사용 중인지 확인해보세요. *취약점은 v19.1.0, v18.13.0 에서 패치되었습니다.
그리고 저희 보안기술팀(Security Tech)에서 이와 같은 보안 연구를 같이 해나갈 동료분들을 찾고 있습니다. 관심이 있으시다면 언제든지 문을 두드려 주세요!


토스 보안기술팀(Security Tech)에서는 개발 서비스 외에도 회사에서 사용하는 프레임워크나 Third-party 시스템의 취약점을 연구하고 있어요.
이번 아티클에서는 Node.js의 Built-in API 중 하나인 url.parse() 의 Hostname Spoofing 취약점을 발견하고 안전한 코드로 패치될 수

토스 보안기술팀은 안전한 금융 서비스를 제공하기 위한 연구를 수행하고 있어요.
많은 서비스에서 사용되고 있는 Node.js의 취약점을 분석하고 안전하게 패치될 수 있도록 기여했던 과정을 소개드려요.

Node.js url.parse() 취약점 컨트리뷰션

메모리에 남지 않는 문자열을 통해 민감한 정보를 안전하게 사용하는 방법을 공유합니다.

메모리에 남지 않는 문자열


프론트엔드 개발자라면 한 번쯤 고민해봤을 성능 최적화!
토스 개발자들이 전하는 최적화의 본질과 실무 노하우를 공개합니다.
“서비스 최적화 언제, 어떻게 시작해야 할까요?”
”초기 로딩 속도를 개선하려면 무엇을 줄이고 바꿔야하는 걸까요?”
”사용자가 느끼는 반응성과 실제 성능, 둘 다 잡는 방법은?”
초기 로딩부터 런타임 최적화까지
토스의 박서진, 박건영, 조유성 님이 전하는 최적화 사례와 비법을 만나보세요!

타임스탬프
00:00 인트로
01:25 성능 최적화, 지금 시작해도 될까요?
04:30 초기 로딩 속도를 좌우하는 3대 요인
09:44 런타임 성능을 높이는 데 필요한 도구와 전략
16:07 React 리렌더링 최적화 꿀팁

출연진
박서진, 토스 Head of Frontend
박건영, 토스증권 Frontend Developer
조유성, 토스 UX Engineering Team Leader

다른 모닥불 회차 보러가기
EP.6 프론트엔드 개발에서 Next.js, 꼭 써야 할까?
EP.7 개발자 리더로서 성장당한 썰
EP.8 Next.js 그만 쓰세요! 면접관이 진짜 원하는 것!?




프론트엔드 개발자라면 한 번쯤 고민해봤을 성능 최적화!
토스 개발자들이 전하는 최적화의 본질과 실무 노하우를 공개합니다.
“서비스 최적화 언제, 어떻게 시작해야 할까요?”
”초기 로딩 속도를 개선하려면 무엇을 줄이고 바꿔야하는 걸까요?”
”사용자가 느끼는 반응성과 실제 성능, 둘 다 잡는 방법은?”
초기 로딩부터 런타임

프론트엔드 개발자라면 한 번쯤 고민해봤을 성능 최적화! 토스 개발자들이 전하는 최적화의 본질과 실무 노하우를 공개합니다.

초기 로딩부터 런타임 최적화까지, 토스의 박서진, 박건영, 조유성 님이 전하는 최적화 사례와 비법을 만나보세요!

프론트엔드 서비스 최적화? 토스에서는 '이렇게' 합니다! 모닥불 | EP.9

안녕하세요. 토스 Frontend Developer 강민우입니다.
토스팀 프론트엔드 챕터는 이전부터 퍼널에 관해 SLASH23 발표도 했었고, Slash Library에 use-funnel를 오픈소스로 배포하는 등 퍼널 라이브러리를 꾸준히 대내외적으로 사용하고 있었습니다. 그런데 기존에 사용하던 퍼널 라이브러리에는 다음과 같은 문제점들이 발견되기 시작했어요. 문제의식에 대한 더 자세한 내용은 이전의 선영님의 아티클을 읽어보세요.
Next.js에 의존성이 있기 때문에, react-router-dom을 사용하는 곳에서 쓰기 어려웠어요. 혹은 라우터를 사용하지 않는 곳에서 퍼널 상태를 관리하고 싶은 니즈도 있었고요.

각각의 단계별로 상태 관리를 지원하지 않기 때문에 이전 단계에서 입력한 상태를 현재 단계에서 있다는 것을 따로 증명해야 됐어요.
뒤로가기를 했을 때 현재 페이지에 있던 상태를 사용하고 싶지 않았어요. 기존 라이브러리에서는 상태를 히스토리에 연동하지 않기 때문입니다.
다양한 추가 기능을 넣고 싶은데 그러한 인터페이스가 마련되어 있지 않았어요. 예를 들어, 약관동의를 BottomSheet로 띄운 컴포넌트를 하나의 단계로 사용하기 어려웠어요.
이런 문제로 사내에서 워킹그룹으로 새롭게 @use-funnel 오픈소스 라이브러리를 개발하기 시작했어요. 이전 아티클에서는 문제의식과 워킹그룹의 타임라인을 공유드렸다면 이번 아티클에서는 라이브러리의 구현에 대해서 더 자세히 살펴볼게요.
Next.js 의존성 제거
먼저 Next.js 뿐만 아니라 다른 라우터를 지원하기 위해서 모노레포 형태의 콘셉트을 잡았습니다. @use-funnel/core 라는 패키지를 통해 핵심 기능을 만들어 둔 후, createUseFunnel 이라는 훅을 만드는 함수를 패키지에서 반환하도록 했습니다.
// @use-funnel/core
export function createUseFunnel(useRouter) {
	return function useFunnel(options) {
		const router = useRouter(options);
		// ... 퍼널 관련 코드들
	}
}
그리고 라우터를 구현하는 @use-funnel/next , @use-funnel/react-router-dom 패키지에서 실제 퍼널 상태를 만드는데 필요한 것들을 구현하도록 했습니다.
import { createUseFunnel } from '@use-funnel/core';
import { useMemo, useState } from 'react';

export const useFunnel = createUseFunnel(({ id, initialState }) => {
  const [history, setHistory] = useState([initialState]);
  const [currentIndex, setCurrentIndex] = useState(0);
  return useMemo(
    () => ({
      history,
      currentIndex,
      currentState: history[currentIndex],
      push(state) {
        setHistory((prev) => [...prev.slice(0, currentIndex + 1), state]);
        setCurrentIndex((prev) => prev + 1);
      },
      replace(state) {
        setHistory((prev) => {
          const newHistory = prev.slice(0, currentIndex + 1);
          newHistory[currentIndex] = state;
          return newHistory;
        });
      },
      go: (index) => setCurrentIndex((prev) => prev + index),
    }),
    [history, currentIndex],
  );
});
이를 통해 react-router-dom, @react-navigation/native 등 다양한 라우터 등을 대응할 수 있게 되었고, 커스텀한 상태를 구현할 경우를 위한 케이스를 위해 직접 @use-funnel/core 패키지를 가져와서 구현할 수 있게 되었습니다.
단계별로 상태 관리 안전하게 할 수 있게 하기
이렇게 만들어지는 useFunnel() 훅에 단계로 별로 상태 관리를 어떻게 정의할까요? 
// 기존의 useFunnel()
const [Funnel, setFunnel] = useFunnel(['AStep', 'BStep', 'CStep'] as const);

// 새로운 useFunnel()
const funnel = useFunnel<{
  AStep: { foo?: string; bar?: string };
  BStep: { foo: string; bar?: string };
  CStep: { foo: string; bar: string };
}>({
  initial: {
    step: 'AStep',
    context: {}
  }
});
기존에는 단순히 단계 배열을 요구하는 것이었지만, 새로운 useFunnel()을 사용할 때 각각의 단계별로 상태를 타입스크립트 제네릭으로 정의할 수 있게 했습니다. 
// 기존 렌더링
<Funnel>
  <Funnel.Step name="AStep"><AStep /></Funnel.Step>
  <Funnel.Step name="BStep"><BStep /></Funnel.Step>
  <Funnel.Step name="CStep"><CStep /></Funnel.Step>
</Funnel>

// 새로운 방식
switch (funnel.step) {
  case 'AStep': return <AStep />;
  case 'BStep': return <BStep foo={funnel.context.foo} />;
  case 'CStep': return <CStep foo={funnel.context.foo} bar={funnel.context.bar} />;
}
또한, 단계별로 상태를 추론하기 위해서 기존의 컴포넌트만 반환해주던 결과에서 구별된 유니온(Discriminated unions)을 반환해서 각 단계와 상태를 타입 안전하게 사용할 수 있도록 했어요.
switch (funnel.step) {
  case 'AStep': {
	  return (
		  <AStep
			  // BStep으로 이동하기 위해서는 `foo` 가 반드시 필요!
			  onNext={foo => funnel.history.push('BStep', { foo })}
		  />
	  );
  }
  case 'BStep': {
	  return (
		  <BStep
			  foo={funnel.context.foo}
			  onNext={bar => funnel.history.push('CStep', { bar })}
			  // AStep으로 이동하기 위해서는 아무런 조건이 없어도 되므로 상태를 안 넘겨줘도 됨.
			  onReplace={() => funnel.history.replace('AStep')}
		  />
	  );
  }
  case 'CStep': return <CStep foo={funnel.context.foo} bar={funnel.context.bar} />;
}
그리고 안전하게 다음 단계로 넘어가기 위해서, 단계를 변경할 때 해당 단계에 필요한 상태가 있는지 비교해서 꼭 필요한 상태가 누락되면 타입 오류가 나도록 했습니다.
예를 들어, 위 예제에서 “AStep” 의 경우 “BStep” 으로 이동하기 위해서 foo 프로퍼티가 필수로 요구되며, “BStep” 에서 “AStep” 으로 이동하기 위해서는 필수로 요구하지 않습니다.
이를 구현하기 위해서 타입스크립트에서 현재 단계의 상태 타입과 이동 단계의 상태 타입을 비교해서 달라진 상태가 있는지 확인했어요. 상태가 다르면 단계 이동 함수에서 반드시 상태를 기입하도록 했어요.
type CurrentStep = { foo: string; bar?: string };
type TargetStep = { foo: string; bar: string };

// { foo?: string; bar: string }
// CurrentStep에서 이미 foo가 존재하기 때문에 foo를 optional하게 요구합니다.
type Input = CompareMergeContext<CurrentStep, TargetStep>;
CompareMergeContext 타입의 자세한 구현체가 궁금하시면 이걸 열어주세요! 
// TBase에서 TResult로 변환할 때 필수적인 키를 가져옵니다.
export type RequiredCompareKeys<TBase, TResult> = keyof TResult | keyof TBase extends infer K
  ? K extends keyof TResult
    ? K extends keyof TBase
      ? TBase[K] extends TResult[K]
        ? never
        : K
      : undefined extends TResult[K]
        ? never
        : K
    : never
  : never;

// TBase에서 TResult로 변환할 때 필수적이지 않은 키를 가져옵니다.
export type OptionalCompareKeys<TBase, TResult> = keyof TBase | keyof TResult extends infer K
  ? K extends keyof TResult
    ? K extends keyof TBase
      ? TBase[K] extends TResult[K]
        ? K
        : never
      : undefined extends TResult[K]
        ? K
        : never
    : K extends keyof TBase
      ? K
      : never
  : never;
 
// RequiredCompareKeys와 OptionalCompareKeys를 합쳐서 새로운 객체 타입을 만든다.
export type CompareMergeContext<TBase, TResult> = Prettify<
  {
    [K in RequiredCompareKeys<TBase, TResult>]: K extends keyof TResult
      ? TResult[K]
      : K extends keyof TBase
        ? TBase[K]
        : never;
  } & {
    [K in OptionalCompareKeys<TBase, TResult>]?: K extends keyof TBase
      ? TBase[K]
      : K extends keyof TResult
        ? TResult[K]
        : never;
  }
>;
또한 런타임 밸리데이션을 통해 상태 검증을 구현해야 하는 경우, 제네릭 선언 없이 단계를 정의해서 사용할 수 있도록 했습니다.
import { z } from 'zod';

const AStepZod = z.object({ foo: z.string().optional(), bar: z.string().optional() });
const BStepZod = AStepZod.required({ foo: true });
const CStepZod = BStepZod.required({ bar: true });

const funnel = useFunnel({
  steps: {
    AStep: { parse: AStepZod.parse },
    BStep: { parse: BStepZod.parse },
    CStep: { parse: CStepZod.parse },
  },
  initial: {
    step: 'AStep',
    context: {},
  }
});
다양한 추가 기능을 구현하기 위한 인터페이스

토스에서는 유저에게 이용약관 및 개인정보 처리 동의를 받기 위해 같은 바텀시트를 활용한 UI를 자주 사용하는데요, 이러한 UI를 하나의 단계로 표현하고 싶은 니즈가 있었습니다.
기존의 useFunnel() 에서는 별도로 이전의 단계의 상태를 저장하고 있지 않기 때문에 이러한 구현이 조금 어려웠습니다.
새로운 버전의 useFunnel()에서는 이러한 다양한 문제를 해결하기 이전 단계들의 상태를 저장하고, 이를 쉽게 사용하기 위해 훅에서 반환되는 Render 컴포넌트를 만들었습니다.
const funnel = useFunnel(...);

<funnel.Render
	AStep={({ history }) => (
		<AStep
		  // BStep으로 이동하기 위해서는 `foo` 가 반드시 필요!
		  onNext={foo => history.push('BStep', { foo })}
	  />
  )}
  BStep={({ context, history }) => (
	  <BStep
		  foo={context.foo}
		  onNext={bar => history.push('CStep', { bar })}
		  // AStep으로 이동하기 위해서는 아무런 조건이 없어도 되므로 상태를 안 넘겨줘도 됨.
		  onReplace={() => history.replace('AStep')}
	  />
  )}
  CStep={({ context }) => <CStep foo={context.foo} bar={context.bar} />}
/>
이 컴포넌트 따로 switch-case 없이 모든 단계의 렌더링을 쉽게 사용할 수 있는 용도로도 사용할 수 있습니다.
여기에서 AStep에서 BStep으로 이동할 때, AStep의 렌더링을 그대로 유지한 채 BStep의 렌더링을 보여주고 싶었습니다. 이를 위해 funnel.Render.overlay 라는 구현체로 렌더 함수를 감싸서, 내부에서 처리하도록 했습니다.
<funnel.Render
	AStep={({ history }) => (
		<AStep
		  // BStep으로 이동하기 위해서는 `foo` 가 반드시 필요!
		  onNext={foo => history.push('BStep', { foo })}
	  />
  )}
  BStep={funnel.Render.overlay(({ context, history }) => (
	  <BStep
		  foo={context.foo}
		  onNext={bar => history.push('CStep', { bar })}
		  // AStep으로 이동하기 위해서는 아무런 조건이 없어도 되므로 상태를 안 넘겨줘도 됨.
		  onReplace={() => history.replace('AStep')}
	  />
	)}
  CStep={({ context }) => (
	  <CStep foo={context.foo} bar={context.bar} />
  )}
/>
내부 구현은 간단하게 다음과 같습니다.
const renderEntires: Array<{ step: string; element: React.ReactNode }> = [];

// Overlay를 렌더링할 때, renderBeforeOverlay에 먼저 렌더링할 단계의 컴포넌트들을 배열(renderEntires)에 추가합니다.
if (render.type === 'overlay') {
  declare const renderBeforeOverlay: Array<{ step: string; element: React.ReactNode }>;
  renderEntries.push(...renderBeforeOverlay);
}

renderEntires.push(render(funnelRenderStep));

return (
  <Fragment>
    {renderEntires.map((entry) => (
      <Fragment key={entry.step}>{entry.element}</Fragment>
    ))}
  </Fragment>
);
Render 컴포넌트는 항상 배열을 통해 현재 퍼널 단계를 렌더링하고 있습니다. 현재 퍼널 단계가 Overlay이라면 이전 단계를 배열에 담아서 렌더링을 하도록 했습니다.
추가로 Render 컴포넌트를 통해 한 가지 편의 기능을 추가한 것이 있습니다. 바로 현재 단계에서 조건에 따라 여러 단계의 퍼널로 갈 때 사용하기 좋은 funnel.Render.with 입니다.
<funnel.Render
	AStep={funnel.Render.with({
	  events: {
	    GoBStepWithFoo(foo: string, { history }) {
	      history.push('BStep', { foo })
	    },
	    GoBStepWithBar(bar: number, { history }) {
	      history.push('BStep', { bar })
	    },
	    GoCStep(_, { history }) {
	      history.push('CStep')
	    }
	  },
	  render({ dispatch }) {
		  return (
			  <AStep
			    onFoo={foo => dispatch('GoBStepWithFoo', foo)}
			    onBar={bar => dispatch('GoBStepWithBar', bar)}
			    onC={() => dispatch('GoCStep')}
			  />
		  );
	  }
	})}
/>
복잡한 퍼널에서 이동 규칙과 렌더링 규칙을 나눠줌으로써 응집성 있는 퍼널을 기대할 수 있게되었습니다.
마치며
토스에서는 이러한 공통된 관심사를 가진 사람들을 모아 워킹그룹을 운영할 수 있어요. 저에게는 이것이 첫 워킹그룹이었는데요, 단순히 사내 라이브러리 개선에서 시작해 오픈소스까지 발전해서 업무와 병행하느라 힘들었지만 그만큼 보람이 매우 깊었습니다. 
앞으로도 많은 기능과 개선을 꾸준히 진행할 예정입니다. @use-funnel 많이 사용해주시고 문제 있으면 언제든지 이슈를 남겨주세요. 
토스 프론트엔드 챕터는 @use-funnel 외에도 여러 오픈소스를 운영하고 있습니다. 토스에서 운영중인 오픈소스는 여기서 확인하실 수 있어요.



안녕하세요. 토스 Frontend Developer 강민우입니다.
토스팀 프론트엔드 챕터는 이전부터 퍼널에 관해 SLASH23 발표도 했었고, Slash Library에 use-funnel를 오픈소스로 배포하는 등 퍼널 라이브러리를 꾸준히 대내외적으로 사용하고 있었습니다. 그런데 기존에 사용하던 퍼널 라이브러리에는 다음과

이번 아티클에서는 @use-funnel 라이브러리의 구현 과정과 방법에 대해서 더 자세히 살펴볼게요.

@use-funnel 개발기 #2: 기존 라이브러리를 어떻게 뜯어 고칠 것인가?

새로운 기능을 개발하다 보면 이런 순간이 찾아와요. 모니터에는 수십 개의 탭이 열려있고, 팀 내부 도구 사용법을 찾아보려는데 문서가 어디 있는지조차 기억나지 않죠. 결국 동료에게 메시지를 보내고 답장을 기다리면서 개발 흐름이 끊기고 맙니다. 익숙한 상황이죠?
토스 프론트엔드 챕터도 비슷한 문제를 경험하고 있었는데요. 이 문제를 조금 다르게 풀어 봤습니다. 문서를 더 잘 써서 방문하게 하는 대신, 문서가 직접 찾아가는 방식으로요.
문서의 경로의존성 깨기
문서의 경로의존성은 사용자가 원하는 정보를 찾기 위해 정해진 경로를 따라가야 하는 제약을 뜻해요. 기존의 기술 문서는 생산자 입장에서 구조화되어 있어서 사용자 입장에서 원하는 정보를 찾으려면 여러 번의 탐색, 혹은 검색이 필요하죠. 이런 문서의 경로의존성을 깨기 위해 먼저 개발자들이 어떻게 일하는지 관찰하고, 인터뷰했어요. 
개발자들이 지식을 얻기 위해 주로 사용하는 방식은 “질문하기”였어요. 옆에 있는 동료에게 물어보거나, 사내 메신저 채널에 질문을 던지는 거죠. 자연스럽고 공감되는 행동이었어요. 그래서 이런 개발자의 행동을 존중하는 방식으로 문서의 형태를 바꿔보기로 했습니다.
질문하기의 가장 큰 장점은 원하는 정보를 즉각적으로 얻을 수 있다는 거예요. 방대한 문서를 검색하고 읽는 것보다 동료에게 직접 물어보는 것이 시간과 노력 면에서 훨씬 효율적이에요. 개발자들이 문서를 더 적극적으로 활용하게 하려면, 이러한 즉각성이 문서에도 필요하다고 생각했어요. 마치 대화하듯이 문서에 질문을 던졌을 때 맥락에 맞는 답변을 바로 받을 수 있다면, 문서는 더욱 강력한 도구가 될 거예요.
그렇게 탄생한 도구가 바로 ‘박씨’에요.
박씨: 질문하면서 문서 읽기
특징: 질문하면 문서 내용을 기반으로 답변해줘요. 일의 흐름이 끊기지 않고 바로바로 정보를 얻을 수 있어요.
위치: IDE(VSCode, Cursor)와 사내 메신저에 있어요.
효과: "문서 찾기"가 아닌 "대화하듯 물어보기”로 지식을 얻을 수 있어요.
재밌는 점: 박씨는 프론트엔드 챕터 헤드 서진님의 페르소나를 따서 만들어 졌어요.


박씨는 LLM이 더 정확하고 신뢰할 수 있는 답변을 만들어내기 위해 개발된 RAG(Retrieval-Augmented Generation) 기반 챗봇이에요. 기존 문서들을 바탕으로 믿을 수 있는 정보를 답변하고, 그 출처를 함께 제공해요. 박씨를 사용하면 문서를 탐색하거나 키워드로 검색할 필요 없이, 궁금한 점을 자연스럽게 물어보면서 필요한 정보를 얻을 수 있어요. 동료에게 물어보는 것보다 더 정확하고, 누구에게나 일관된 답변을 제공한다는 장점이 있죠.
박씨가 좋은 품질의 답변을 하려면 탄탄한 기반 지식이 필요해요. 그래서 저희는 문서의 양과 질을 모두 높이는 것에도 많은 공을 들이고 있어요. 하지만 테크니컬 라이터와 소수의 개발자들만으로는 충분한 문서를 만들기 어려웠어요. 이 시스템이 확장성을 가지려면 누구나 자신의 지식을 쉽게 문서화할 수 있어야 했죠. 그래서 실록봇이라는 문서 자동화 도구를 만들었답니다.
실록봇: 대화를 바로 문서화하기
역할: 사내 메신저 대화 속 중요 정보를 쉽게 문서화해요.
작동방식: 대화 스레드에 실록봇 이모지를 붙이거나 봇을 호출하면 AI가 대화를 분석하고 요약해서  PR을 올려요.
효과: 사람이 시간을 내서 문서를 따로 작성하는 것이 아니라, 실제 문제 해결 과정에서 자연스럽게 그리고 자동으로 기록할 수 있어요.

실록봇은 팀 내에서 오가는 중요한 대화를 요약해서 자동으로 문서화 해줘요. 사실 개발자들은 사내 메신저에서 질문에 답하거나 대화하며 항상 지식을 교류하고 있더라구요. 그런 대화가 메신저에서 일어나기 때문에 빠르게 휘발되고, 반복적으로 같은 질문이 올라오는 게 아쉬웠어요. 실록봇은 메신저에서 일어나는 대화를 요약해서 문서 리포지토리에 PR을 만들어요. 메신저에 남긴 유용한 메시지나 논의 스레드를 최소한의 노력으로 기록할 수 있게 된 것이죠.
예를 들어, 어떤 버그를 해결하기 위해 나눈 대화가 도움이 됐다고 생각한 팀원이 실록봇을 호출해요. 그러면 그 대화는 바로 문서가 되고, 이렇게 만들어진 정보는 박씨가 학습해요. 덕분에 팀원들은 같은 질문을 반복할 필요 없이 실록봇이 모은 정보와 박씨를 사용해 쉽게 해결책을 찾을 수 있어요. 문서를 위한 문서 작성이 아니라, 지식이 공유되는 순간에 자연스럽게 문서가 만들어지는 거예요.
지식이 흐르는 팀
박씨와 실록봇 덕분에 이제 토스 프론트엔드 챕터는 특정 팀원에게 지식이 몰려있거나, 같은 질문이 반복되는 문제가 줄었어요. 필요한 순간에 필요한 정보가 제공되면서 팀 내 지식이 자연스럽게 흐르는 환경이 되었답니다. 그리고 이런 환경이 팀의 생산성과 효율성을 높이고 있어요. 개발자의 행동을 관찰하고, ‘기술 문서’를 정적인 정보 모음이 아니라 개발자의 학습과 문제 해결을 도와주는 시스템으로 접근했던 것이 유효했어요.
테크니컬 라이팅도 함께 진화하고 있는데요. 이전에는 공급자 관점에서 정보를 구조화하고 특정 기능을 효과적으로 설명하는 것에 초점을 맞췄다면, 지금은 개발자가 문서를 잘 사용할 수 있는 시스템을 만드는 데 집중하고 있어요. 결국 테크니컬 라이팅의 본질은 ‘어떻게 문서로 개발자의 문제 해결을 도와줄 수 있을까’이기 때문이에요.
토스 프론트엔드 플랫폼 팀은 지식을 공유하고, 접근하기 좋은 학습 인프라를 만드는 여정에 함께하실 분을 기다리고 있어요. AI 기반 문서화 시스템을 더욱 발전시키고, 코드와 자연스럽게 연결되는 문서 자동화 시스템을 만들고, 사내 메신저를 비롯한 여러 플랫폼과 잘 어우러지는 문서 생태계를 구축하는 일들이 기다리고 있어요.
개발자들이 더 효율적으로 일할 수 있는 환경을 만들어서 개발자 경험을 한 단계 높이는 일에 관심 있으신가요? 그렇다면 Frontend Platform Engineer에 지원해 주세요! 함께 더 나은 개발 문화를 만들어가요.



새로운 기능을 개발하다 보면 이런 순간이 찾아와요. 모니터에는 수십 개의 탭이 열려있고, 팀 내부 도구 사용법을 찾아보려는데 문서가 어디 있는지조차 기억나지 않죠. 결국 동료에게 메시지를 보내고 답장을 기다리면서 개발 흐름이 끊기고 맙니다. 익숙한 상황이죠?
토스 프론트엔드 챕터도 비슷한 문제를 경험하고 있었는데요. 이 