CAPTCHA API 키를 브라우저 JavaScript에 노출하지 않기

워크스페이스 키는 Authorization: Bearer로 solvethree 요청을 인증합니다. NEXT_PUBLIC_SOLVETHREE_API_KEY와 같은 번들에 포함되는 공개 환경 변수를 비롯해 브라우저 JavaScript에 키를 넣으면 해당 자격 증명이 브라우저에 노출됩니다. 값을 난독화하거나 직접 fetch 요청을 보낼 때만 추가해도 비공개로 유지되지는 않습니다.

SOLVETHREE_API_KEY는 서버 전용 설정에 보관하고 신뢰할 수 있는 서버 코드에서만 사용하세요. 브라우저는 애플리케이션 경로를 호출해야 하며, 워크스페이스 키로 solvethree 작업 API를 직접 호출해서는 안 됩니다.

// Import only from trusted server code. Your application authenticates the caller.
import { Solvethree } from '@solvethree/sdk';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
export async function createCaptchaForLogin(requestId) {
  return client.createTask({
    site: process.env.CAPTCHA_SITE,
    action: 'login',
    proxy: process.env.SOLVETHREE_PROXY,
    requestId,
  }, { waitMs: 0, signal: AbortSignal.timeout(20000) });
}
// The browser calls your authenticated application route, not the solver API.
// Save the returned task ID; retrieve that ID from server code with getTask.
// Submit a ready token using the proxy/browser identity attached to that solve.
// Merely moving the key server-side does not configure the browser's proxy.

서버에서 SOLVETHREE_API_KEY, CAPTCHA_SITE, SOLVETHREE_PROXY를 설정하세요. CAPTCHA_SITE는 전체 URL이 아닌 대상 호스트 이름입니다. 헬퍼는 액션을 login으로 고정하고 프록시 하나를 제공합니다. 브라우저는 이 입력값 중 어느 것도 선택하지 않습니다.

헬퍼를 호출하기 전에 워크스페이스에 해당 호스트 이름의 활성 프로필을 설정하세요. site와 action을 전송해도 프로필이 생성되지는 않습니다. 사이트 프로필 설정을 참고하세요.

waitMs: 0은 솔루션 생성이 완료될 때까지 기다리지 않고 작업 생성을 요청합니다. 반환된 작업 ID를 저장하고 서버 코드에서 getTask로 조회하세요. 헬퍼의 20초 중단 신호는 해당 요청의 시간을 제한하며, 솔루션 생성이 20초 안에 완료된다는 보장은 아닙니다.

헬퍼 자체는 인증된 경로가 아닙니다. 브라우저 요청을 수락하기 전에 헬퍼를 감싸는 로직에 다음 검사를 추가하세요.

브라우저가 제공한 작업 본문을 그대로 전달하지 마세요. 다른 호스트 이름, 액션, 프록시 또는 작업 유형을 선택하려는 시도는 거부하세요. 호출자 또는 애플리케이션 세션별로 생성 제한을 적용하세요. 인증된 호출자도 새 작업을 계속 시작해 크레딧을 소진할 수 있습니다. 경로에서 쿠키 인증을 사용한다면 작업 생성 요청을 교차 사이트 요청 위조로부터 보호하세요.

작업 ID는 권한 증명이 아닙니다. 모든 진행 상황 요청에서 소유권을 확인하고, 브라우저 응답에 워크스페이스 자격 증명이나 서버 프록시 자격 증명을 반환하지 마세요.

• 논리적으로 동일한 로그인 시도에는 하나의 requestId를 유지하세요. 문서에 명시된 형식인 ASCII 영문자, 숫자, 밑줄 또는 하이픈 1–64자로 구성되었는지 검증하세요. 이를 호출자의 시도와 연결하세요. requestId는 인증 자격 증명이 아닙니다.
• 생성 요청이 타임아웃되면 해당 requestId와 원래 작업 입력값을 유지하세요. 같은 ID로 동일한 요청을 반복하면 기존 작업을 복구합니다. ID를 재사용하면서 입력값을 변경하면 충돌이 발생합니다.
• 성공 응답 페이로드를 해석하기 전에 성공이 아닌 HTTP 응답을 처리하세요. 조회한 작업에서 pending과 solving은 폴링을 계속해야 한다는 뜻이고, ready는 솔루션을 사용할 수 있다는 뜻입니다.

작업 ID를 얻은 뒤에는 브라우저 새로고침이나 진행 상황 요청 때마다 새 솔루션 생성을 시작하지 말고 해당 작업을 조회하세요. 실패 원인 진단은 API 오류 처리를 참고하세요.

준비된 토큰을 브라우저에 반환하기 전에 대상 요청을 어디서 실행할지 결정하세요. 제출 클라이언트는 반환된 userAgent와 secChUa 식별 정보, 그리고 해당 솔루션 생성에 성공한 프록시를 사용해야 합니다. 워크스페이스 키를 백엔드로 옮겨도 브라우저의 프록시가 설정되지는 않습니다.

브라우저가 해당 설정으로 제출할 수 없다면 토큰만 전달하는 것으로는 통합이 완성되지 않습니다. 다른 세션의 식별 정보, 프록시 또는 대상 URL을 섞지 말고 일관되게 설정할 수 있는 제출 클라이언트를 사용하세요. 작업이 준비되었다는 것은 solvethree가 솔루션을 생성했다는 뜻이지, 대상이 후속 요청을 수락했다는 뜻은 아닙니다.