> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Chrome 확장 프로그램(MV3)을 갖춘 SaaS 만들기: 웹 인증과 API 공유

대부분의 팀은 브라우저 확장용 두 번째 백엔드를 만듭니다. Manifest V3 컴패니언을 워크스페이스 API 키로 기존 SaaS에 연결하는 방법—인증 이중화도 두 번째 DB도 없이.

_게시일 2026-11-07._
_2026-11-07 업데이트됨._

> **SaaS와 백엔드를 공유하는 Chrome 확장 프로그램을 만들려면?**
> 두 번째 백엔드를 만들지 않는 것입니다. MV3 확장은 HttpOnly 쿠키에 의존할 수 없으므로 워크스페이스 API 키로 인증합니다. 확장은 하나의 워크스페이스에 묶인 스코프 키로 앱의 버전 지정 REST API(/api/v1)를 호출해, 웹 앱과 같은 인증 모델·테넌트 스코프·Postgres DB를 재사용합니다. supastack의 MV3 스캐폴드—팝업, 옵션 페이지, 백그라운드 워커, 최소 권한 매니페스트—가 정확히 이 배선입니다.

## 함정: 모르는 사이에 만드는 두 번째 백엔드

흔한 이야기입니다. SaaS에 페이지 캡처, 콘텐츠 클리핑, 웹 주석용 컴패니언 확장이 필요해집니다. 6개월 후 당신은 두 개의 인증 체계(웹은 쿠키, 확장은 수제), 확장이 실제로 호출할 수 있는 평행 API, 그리고 원래 하나였어야 할 두 데이터 저장소를 맞추는 동기화 계층을 유지하고 있습니다.

그 전부가 불필요합니다. 확장은 기존 제품의 한 클라이언트일 뿐—들고 있을 수 있는 자격 증명과 프로그래밍 접근용 API면 충분합니다. 실수는, 제대로 된 SaaS가 이미 가진 워크스페이스 API 키와 버전 지정 REST 표면 대신 새 백엔드에 손을 뻗는 것입니다.


## Manifest V3가 실제로 허용하는 것

MV3는 백그라운드 페이지를 수명 짧은 Service Worker로 대체하고 확장을 최소 권한으로 밀었습니다. 실무적으로는 영구 메모리 상태에 의존할 수 없고, 세션 재사용을 위해 쿠키를 긁으면 안 되며(HttpOnly 쿠키는 어차피 닿지 않음), 모든 호스트 권한이 웹 스토어 심사 질문이 됩니다.

깔끔한 답은 플랫폼이 이미 준 것입니다. `chrome.storage.local`의 스코프 자격 증명과 앱 오리진으로의 HTTPS 호출—설치 시가 아니라 설정 시에 선택적 호스트 권한으로 요청합니다.


## supastack의 MV3 스캐폴드: 이미 배선된 부분

supastack의 `apps/extension`은 의도적으로 작고 프레임워크 없이 만든 Manifest V3 컴패니언—「페이지를 워크스페이스에 저장」—으로 전체 패턴을 엔드투엔드로 보여줍니다. 활성 탭의 제목·URL·선택 텍스트를 버전 지정 REST API `POST /api/v1/content-entries`로 워크스페이스 콘텐츠 항목에 저장합니다.

인증은 Settings → Developers에서 발급하는 워크스페이스 API 키(`sk_…`)입니다. 키는 정확히 하나의 워크스페이스에 묶이므로 그 바인딩 자체가 워크스페이스 선택이며, 키는 절대 밖으로 쓸 수 없습니다. 옵션 페이지는 앱 URL과 키를 `chrome.storage.local`에 저장하고 해당 오리진만 접근을 요청한 뒤 `GET /api/v1/workspaces/current`로 연결을 확인합니다.

```
apps/extension/
  manifest.json        MV3: service worker, least-privilege permissions
  src/
    background.js      context-menu save + badge feedback
    popup.html/.js     capture UI — title, URL, selection, note
    options.html/.js   app URL + workspace API key setup
    lib/
      api.mjs          versioned /api/v1 client (key auth)
      capture.mjs      active-tab + selection capture
      config.mjs       chrome.storage.local persistence
```


## 기본 최소 권한

스캐폴드는 작업에 필요한 최소 권한만 동봉합니다—웹 스토어 심사와 사용자 신뢰 모두에 중요합니다:

- `tabs` 없음, `<all_urls>` 없음, cookies/webRequest/declarativeNetRequest 없음—필요 없는 것을 정직하게 선언하는 스캐폴드입니다.

| 권한 | 이유 |
|---|---|
| activeTab | 호출 시에만 현재 페이지의 제목/URL 읽기 |
| scripting | 호출된 탭 내 선택 텍스트 읽기 |
| contextMenus | 우클릭 저장 메뉴 등록 |
| storage | 앱 URL, API 키, 캐시된 워크스페이스 유지 |
| optional_host_permissions | 앱 오리진은 설정 시 요청—설치 시 사이트 접근 제로 |


## 스캐폴드에서 당신 제품의 컴패니언으로

리브랜딩은 `manifest.json`의 이름 변경이고, 확장이 재미있는 부분입니다—그리고 같은 패턴 안에 머뭅니다. 새 캡처 유형은 같은 키로 새 `/api/v1` 엔드포인트를 호출하고, 앱의 OpenAPI 문서에서 생성된 타입 `@supastack/api-sdk`가 요청 형태의 정직함을 지킵니다.

확장은 다른 클라이언트처럼 같은 테넌트 스코프 API로 읽고 쓰므로, 저장한 페이지는 웹 대시보드가 나열하는 같은 Postgres 행에 떨어집니다—하나의 DB, 하나의 인증 모델, `workspaceId` 스코프를 강제하는 곳은 한 곳. 두 번째 백엔드 없음, 동기화 없음, 드리프트 없음. 티어는 [가격 페이지](https://supastack.dev/#pricing)에서 비교하세요.

|  | DIY 두 번째 백엔드 방식 | supastack MV3 스캐폴드 |
|---|---|---|
| 인증 | 쿠키 옆에 수제 토큰 체계 | 워크스페이스 API 키—웹과 같은 인증 모델 |
| API | 확장용 새 엔드포인트 발명 | 버전 지정 /api/v1 + OpenAPI 타입 SDK |
| 데이터 | 두 번째 저장소 + 동기화 로직 | 같은 Postgres 행, 워크스페이스 스코프 |
| 권한 | 편의를 위한 넓은 접근 | 최소 권한 매니페스트, 심사에 유리 |


## FAQ: 하나의 백엔드로 SaaS + Chrome 확장

확장 컴패니언을 출시하기 전 개발자들이 묻는 질문입니다:

- 세션 쿠키 대신 API 키인 이유는?, HttpOnly 쿠키는 설계상 확장 JS에 보이지 않고 MV3 Service Worker는 수명이 짧습니다. `chrome.storage.local`의 스코프 `sk_…` 키는 지속적·폐기 가능하고 하나의 워크스페이스에 묶여 테넌트를 넘을 수 없습니다.
- Firefox에서도 동작하나요?, MV3는 같은 표면을 지원합니다. 코드는 `browser ?? chrome` 네임스페이스 심으로 Chromium 우선 개발됐으므로 Firefox는 재작성이 아니라 이식입니다.
- 바로 스토어에 올릴 수 있나요?, 프로덕션 패턴의 스캐폴드이지 스토어 제출물은 아닙니다—매니페스트 개명, 자체 캡처 로직, 리스팅 문구는 당신의 몫입니다. 어려운 부분(인증, API, 테넌트 스코프)은 이미 끝났습니다.
- 어느 라이선스에 확장이 포함되나요?, $299 Full Bundle이 5개 표면 전부—두 웹 엔진, Expo, Tauri, 확장 스캐폴드—를 한 리포지토리로 제공합니다.