Add auth token requirement notice for LocalStack latest images

docs/contributor-research/README.md

@@ -0,0 +1,92 @@
+# Testcontainers-Node 기여 전략 리서치
+
+## 목표
+
+TypeScript/Node.js 백엔드 엔지니어가 `testcontainers/testcontainers-node`에 기여할 후보를 정리한 문서.
+
+**"머지 가능성이 높으면서 백엔드 채용팀에 어필할 수 있는 것"**을 기준으로 선별.
+
+## 저장소 상태
+
+- 업스트림: `testcontainers/testcontainers-node`
+- 포크: `PreAgile/testcontainers-node`
+- 최종 업데이트: 2026-03-22
+
+### 저장소 특징
+
+| 항목 | 내용 |
+|------|------|
+| Stars | 2,499 |
+| 언어 | TypeScript |
+| 구조 | 모노레포 — `packages/testcontainers` (코어) + 41개 모듈 (`packages/modules/*`) |
+| 오픈 이슈 | **5개** (매우 적음 — 잘 관리되는 프로젝트) |
+| 라이선스 | MIT |
+
+### 메인테이너 분석
+
+| 이름 | GitHub | 역할 | 커밋 수 | 특징 |
+|------|--------|------|---------|------|
+| Cristian Greco | `cristianrgreco` | 핵심 메인테이너 | 640 / 1,125 총 커밋 (57%, 봇 제외 시 ~75%) | 리뷰 빠름 (당일~2일), 높은 품질 기준 |
+| Andreas Hofmeister | `HofmeisterAn` | 간헐적 기여 | 소수 | 가끔 리뷰 참여 |
+
+> 참고: 총 1,125 커밋 중 github-actions(195), dependabot(75) 등 봇 커밋이 상당수. 인간 기여자 중에서는 cristianrgreco가 압도적이나, "90%+"는 과장된 수치.
+
+### 머지 패턴
+
+- **리뷰 속도**: 심플한 PR은 당일, 기능 PR은 1-2일, 외부 기여자는 1-3주
+- **선호**: 깔끔하고 집중된 PR. API 변경 시 문서 업데이트 같은 PR에 포함
+- **높은 품질 기준**: GH-1135에서 2개 PR(외부 + 메인테이너 본인 것) 모두 닫힘 — 기준이 엄격
+- **새 모듈 수용적**: Oracle Free 모듈 PR #1242가 17일 만에 머지
+
+### AGENTS.md 준수 필수
+
+이 프로젝트는 `AGENTS.md`에 PR 프로세스, 라벨링, 커밋 컨벤션이 상세히 기술됨. CONTRIBUTING.md보다 AGENTS.md를 따를 것.
+
+## 완료된 PR
+
+| PR | 이슈 | 상태 | 날짜 |
+|----|------|------|------|
+| — | — | 아직 없음 | — |
+
+## 현재 후보 (2026-03-22)
+
+| 순위 | 이슈 | 유형 | 머지 확률 | 포트폴리오 가치 | 상태 | 상세 문서 |
+|------|------|------|----------|---------------|------|----------|
+| 1 | `GH-1274` LocalStack auth token 대응 | 문서/예제 | 매우 높음 | 중간 | 🔴 **긴급** (3/23 데드라인), 문서 중심 변경 | [issue-1274-localstack-auth.md](issue-1274-localstack-auth.md) |
+| 2 | 새 모듈 추가 (예: Meilisearch) | 신규 모듈 | 중상 | 중상 | 🟢 상시 가능, 선례 있으나 개별 심사 | [new-module-opportunity.md](new-module-opportunity.md) |
+| 3 | `GH-1135` archiver 경량 대체 | 보안/성능 | 중간 | 높음 | 🟡 2차례 PR 닫힘, 실패 원인 분석 선행 필수 | [issue-1135-replace-archiver.md](issue-1135-replace-archiver.md) |
+| 4 | `GH-1049` BuildKit 빌드 로그 디코딩 | 기능 개선 | 낮음-중간 | 매우 높음 | 🟡 기술적 난이도 매우 높음 | [issue-1049-buildkit-logs.md](issue-1049-buildkit-logs.md) |
+| 5 | `GH-1237` Docker 빌드 시 인증 정보 미적용 | 버그 | 낮음-중간 | 높음 | 🟡 업스트림 이슈 가능성, 모니터링 | [issue-1237-build-credentials.md](issue-1237-build-credentials.md) |
+
+## 추천 실행 순서
+
+### 1단계: 빠른 첫 머지
+
+1. **GH-1274 LocalStack auth token** — 긴급. 3/23부터 `localstack/localstack:latest`에 `LOCALSTACK_AUTH_TOKEN` 필수. 기존 모듈은 `.withEnvironment()`로 이미 토큰 전달 가능하므로, **문서/예제 업데이트가 핵심**. 소스 수정(편의 메서드 등)은 메인테이너 선호에 따라 옵션
+
+### 2단계: 안정적인 기여
+
+2. **새 모듈 추가** — 검증된 패턴. 41개 기존 모듈이 템플릿. 실제 사용하는 서비스로 만들면 자연스러운 스토리
+
+### 3단계: 고난이도 도전
+
+3. **GH-1135 archiver 교체** — 2번의 실패 원인 분석 후 시도. 성공하면 보안+성능 기여로 큰 임팩트
+4. **GH-1049 BuildKit 로그** — protobuf 디코딩 역량 필요. 성공하면 매우 인상적
+5. **GH-1237 인증 버그** — 업스트림 `docker-modem` 이슈일 가능성. 복합 디버깅 필요
+
+## 피해야 할 이슈
+
+| 이슈 | 이유 |
+|------|------|
+| `GH-687` / PR #1096 HealthCheckWaitStrategy | `digital88`가 7개월째 활발히 작업 중 |
+| PR #1276 lock file per user | `seanwu1105`가 방금 제출 (3/21) |
+
+## PR 제출 전 체크리스트
+
+- [ ] AGENTS.md 규칙 확인
+- [ ] `npm run format` 실행
+- [ ] `npm run lint` 실행
+- [ ] 관련 모듈만 타겟 테스트 실행
+- [ ] 문서 변경 시 같은 PR에 포함
+- [ ] PR 하나에 이슈 하나
+- [ ] 커밋 메시지 컨벤션 준수

docs/contributor-research/issue-1049-buildkit-logs.md

@@ -0,0 +1,73 @@
+# Issue GH-1049: Container build logs aren't useful because they're encoded (BuildKit)
+
+## 기본 정보
+
+| 항목 | 내용 |
+|------|------|
+| 이슈 | [GH-1049](https://github.com/testcontainers/testcontainers-node/issues/1049) |
+| 제목 | Container build logs aren't useful because they're encoded |
+| 라벨 | `enhancement`, `never-stale` |
+| 클레임 | `weyert`가 관심 표시 → **8개월+ PR 미제출** |
+| 모듈 | `packages/testcontainers` (코어) |
+
+## 문제
+
+Docker BuildKit이 활성화된 환경에서 컨테이너 빌드 로그가 base64 인코딩된 protobuf 메시지(`aux` 프로퍼티)로 반환됨. 사람이 읽을 수 없는 형태.
+
+### 현재 동작
+
+```
+빌드 로그: {"aux": "CjkKOBo2c2hhMjU2OjA5MWNkYTJlZj..."}
+```
+
+### 원하는 동작
+
+```
+Step 1/5: FROM node:18-alpine
+Step 2/5: WORKDIR /app
+...
+```
+
+## 기술적 배경
+
+- BuildKit은 Docker의 차세대 빌드 엔진 (Docker Desktop에서 기본 활성)
+- 빌드 진행 상황을 gRPC/protobuf로 전송
+- `aux` 필드에 base64로 인코딩된 protobuf 메시지가 들어있음
+- 디코딩하려면 `moby/buildkit`의 gRPC 스키마 정의가 필요
+
+## 메인테이너 코멘트
+
+> "I tried decoding these messages... it was not at all trivial."
+> "Do not copy/paste schemas into the repository."
+
+→ protobuf 스키마를 벤더링하지 말고, 적절한 디코딩 방법을 찾아야 함
+
+## 해결 방향
+
+1. `moby/buildkit` gRPC 정의에서 관련 proto 파일 확인
+2. `protobufjs` 또는 유사 라이브러리로 런타임 디코딩
+3. 또는 BuildKit API의 non-aux 출력 모드 활용 (가능한 경우)
+
+## 머지 확률 평가
+
+| 요소 | 평가 |
+|------|------|
+| 메인테이너 관심 | ✅ `never-stale` + 명시적 관심 |
+| 기술적 난이도 | ❌ **매우 높음** — 메인테이너도 "trivial하지 않다"고 |
+| 경쟁자 | ✅ 8개월간 미실행 |
+| 스키마 제약 | ⚠️ proto 스키마 벤더링 금지 |
+| **종합 머지 확률** | **중하 (35-45%)** |
+
+## 포트폴리오 가치
+
+**매우 높음** — 성공 시:
+1. Docker/BuildKit 내부 지식
+2. protobuf 디코딩 역량
+3. 메인테이너도 못 풀었던 문제 해결 — 최강 시그널
+
+## 리스크
+
+- **메인테이너가 "trivial하지 않다"고 한 난이도** — 상당한 연구 시간 필요
+- protobuf 스키마 벤더링 금지 정책 → 대안 접근법 필요
+- 새 의존성(protobufjs 등) 추가에 대한 거부감 가능
+- **충분한 신뢰와 실력 검증 후 도전 권장**

docs/contributor-research/issue-1135-replace-archiver.md

@@ -0,0 +1,74 @@
+# Issue GH-1135: Replace `archiver` with lighter alternative
+
+## 기본 정보
+
+| 항목 | 내용 |
+|------|------|
+| 이슈 | [GH-1135](https://github.com/testcontainers/testcontainers-node/issues/1135) |
+| 제목 | Replace `archiver` with lighter alternative |
+| 라벨 | `enhancement`, `never-stale` |
+| 클레임 | **없음** (2차례 PR 닫힌 후 방치) |
+| 모듈 | `packages/testcontainers` (코어) |
+
+## 문제
+
+`archiver` 패키지가 64개 의존성, 7MB+ 용량으로 프로젝트 전체 의존성의 상당 부분을 차지.
+
+이슈 작성자가 보안 관련 근거로 [socket.dev 공급망 공격 보고서](https://socket.dev/blog/npm-author-qix-compromised-in-major-supply-chain-attack)를 링크함 — archiver의 일부 의존성 저자(`qix-`)의 npm 계정이 침해된 사건. 단, archiver 자체가 직접 침해된 것은 아니며 **간접적 공급망 리스크**로 보는 것이 정확.
+
+### 현재 `archiver` 사용처
+
+Docker 컨테이너에 파일/디렉토리를 복사할 때 tar 아카이브를 생성하는 데 사용:
+- 파일 복사 (단일/다중)
+- 디렉토리 복사
+- 인라인 콘텐츠 복사
+- `copyUIDGID` 옵션 지원
+
+## 이전 PR 분석
+
+### PR #1161 (ayuhito — modern-tar 저자, 2025-10 닫힘)
+
+- **접근**: `modern-tar` 라이브러리 사용 (48MB → 38MB 감소)
+- **닫힌 이유**: 메인테이너가 명시적으로 답변 — "`modern-tar`가 아직 몇 주밖에 안 된 라이브러리라서 `archiver`(검증된 라이브러리) 대비 신뢰성이 부족하다. 대신 `tar-stream`이나 `tar-fs` 같은 검증된 대안을 선호한다."
+- **메인테이너 피드백**: "I'd happily accept a PR to use `tar-stream` or `tar-fs`"
+
+### PR #1246 (cristianrgreco — 메인테이너 본인, 2026-02 닫힘)
+
+- **접근**: `tar-fs` 사용
+- **닫힌 이유**: 코멘트 없이 닫힘. 원인 미확인 — copy 동작의 전체 케이스 커버가 어려웠을 가능성이 있지만, **확인된 사실이 아님. 추가 조사 필요.**
+
+## 해결 방향
+
+PR #1161 리뷰에서 메인테이너가 `tar-stream` (archiver가 내부적으로 사용) 또는 `tar-fs`를 선호한다고 명시. PR #1246이 `tar-fs`로 시도했으나 닫힌 이유를 파악하는 것이 핵심.
+
+### 사전 조사 항목
+
+1. **PR #1246의 닫힌 이유 확인** — diff와 CI 결과 분석, 필요 시 메인테이너에게 직접 질문
+2. `archiver` → `tar-stream` 직접 교체 POC
+3. 모든 copy 케이스 목록 작성 (파일, 디렉토리, 인라인, copyUIDGID)
+4. 기존 테스트 전부 통과 확인
+
+## 머지 확률 평가
+
+| 요소 | 평가 |
+|------|------|
+| 메인테이너 관심 | ✅ "PR welcome!" + `never-stale` + 선호 대안 명시 |
+| 의존성 감소 효과 | ✅ 7MB+ 제거 |
+| 경쟁자 | ✅ 현재 없음 |
+| 기술적 난이도 | ⚠️ 높음 — copy 동작의 엣지 케이스가 많을 수 있음 |
+| 이전 실패 이력 | ⚠️ 2차례 PR 닫힘 (1건은 라이브러리 선택 문제, 1건은 원인 미확인) |
+| **종합** | **중간** — PR #1246 실패 원인 파악 여부에 크게 좌우 |
+
+## 포트폴리오 가치
+
+**높음**:
+1. 의존성 최적화 — 실무에서 중요한 주제
+2. 공급망 보안 인식
+3. 코어 패키지 개선
+
+## 리스크
+
+- PR #1246이 왜 닫혔는지 모르는 상태에서 시작하면 같은 함정에 빠질 수 있음 → **사전 조사 필수**
+- copy 동작의 엣지 케이스가 많을 수 있음
+- 코어 패키지 변경이라 회귀 리스크
+- **GH-1274 이후, 신뢰 쌓은 뒤 시도 권장**

docs/contributor-research/issue-1237-build-credentials.md

@@ -0,0 +1,62 @@
+# Issue GH-1237: Credentials not used for pulling images during build
+
+## 기본 정보
+
+| 항목 | 내용 |
+|------|------|
+| 이슈 | [GH-1237](https://github.com/testcontainers/testcontainers-node/issues/1237) |
+| 제목 | Credentials not used for pulling images during build |
+| 라벨 | `triage` |
+| 클레임 | **없음** (메인테이너가 조사 중) |
+| 모듈 | `packages/testcontainers` (코어 — GenericContainerBuilder) |
+
+## 문제
+
+`GenericContainerBuilder`로 Docker 이미지를 빌드할 때, base 이미지를 pull하는 과정에서 `~/.docker/config.json`의 인증 정보가 적용되지 않음. 프라이빗 레지스트리의 base 이미지를 사용하는 Dockerfile 빌드가 실패.
+
+### 증상
+
+```
+Error: pull access denied for private-registry.com/base-image
+```
+
+레지스트리 주소가 `localhost`로 resolve되는 현상 — `docker-modem`의 레지스트리 해석 로직 문제 추정.
+
+## 조사 상태
+
+- 메인테이너 `cristianrgreco`가 직접 조사 중
+- 업스트림 `docker-modem` 이슈 (`apocas/docker-modem#194`) 연관 가능성 식별
+- 아직 triage 단계 — 근본 원인 미확정
+
+## 해결 방향
+
+### 시나리오 1: testcontainers-node 내부 문제
+
+- `GenericContainerBuilder`에서 빌드 시 auth config를 올바르게 전달하도록 수정
+
+### 시나리오 2: docker-modem 업스트림 문제
+
+- `docker-modem`에 PR 제출 → testcontainers-node에서 업데이트된 버전 사용
+
+## 머지 확률 평가
+
+| 요소 | 평가 |
+|------|------|
+| 메인테이너 관심 | ✅ 직접 조사 중 |
+| 근본 원인 | ⚠️ **미확정** — 업스트림일 수 있음 |
+| 변경 범위 | ⚠️ 코어 인증 로직 |
+| **종합 머지 확률** | **중하 (30-40%)** |
+
+## 포트폴리오 가치
+
+**높음** — 성공 시:
+1. Docker 인증 메커니즘 깊은 이해
+2. 업스트림 + 다운스트림 크로스 프로젝트 디버깅 능력
+3. 보안 관련 기여
+
+## 리스크
+
+- **근본 원인이 업스트림(`docker-modem`)일 가능성** — 두 프로젝트에 PR 필요
+- 메인테이너가 직접 조사 중 — 기여 공간이 좁을 수 있음
+- triage 단계라 방향이 바뀔 수 있음
+- **모니터링 대상** — 근본 원인 확정 후 판단

docs/contributor-research/issue-1274-localstack-auth.md

@@ -0,0 +1,73 @@
+# Issue GH-1274: LocalStack module docs/examples need updating for auth token requirement
+
+## ✅ 상태: PR 제출 완료
+
+> **2026-03-22**: [PR #1277](https://github.com/testcontainers/testcontainers-node/pull/1277) 제출. `docs/modules/localstack.md`에 auth token 필수화 안내 섹션 추가. 리뷰 대기 중.
+
+## 기본 정보
+
+| 항목 | 내용 |
+|------|------|
+| 이슈 | [GH-1274](https://github.com/testcontainers/testcontainers-node/issues/1274) |
+| 제목 | LocalStack module docs/examples need updating for auth token requirement |
+| 작성일 | 2026-03-17 |
+| PR | [#1277](https://github.com/testcontainers/testcontainers-node/pull/1277) |
+| 긴급도 | 🔴 **2026-03-23부터 `latest` 태그 사용자 기준 breaking change** |
+| 모듈 | `packages/modules/localstack` |
+
+## 문제
+
+2026-03-23부터 `localstack/localstack:latest` Docker 이미지가 `LOCALSTACK_AUTH_TOKEN` 환경변수를 **필수**로 요구. `latest` 태그를 사용하는 사용자에게 breaking이며, 버전 고정 사용자는 영향 없을 수 있음. 현재 testcontainers-node의 LocalStack 모듈 문서/예제에 이 토큰에 대한 안내가 없어서 `latest` 사용자들이 혼란을 겪을 수 있음.
+
+## 현재 모듈 구조 분석
+
+`localstack-container.ts`를 보면:
+- `GenericContainer`를 상속
+- `withEnvironment()`로 `LOCALSTACK_HOST`, `LAMBDA_DOCKER_FLAGS` 등 환경변수 주입
+- **사용자가 이미 `.withEnvironment({ LOCALSTACK_AUTH_TOKEN: "..." })`로 토큰을 넣을 수 있음**
+
+→ **모듈 소스 수정은 필수가 아님**. 이슈 제목 그대로 **문서/예제 중심** 변경이 핵심.
+
+### 영향 범위
+
+- **문서/예제** (핵심): auth token 필수화 안내, `.withEnvironment()` 사용 예시 추가
+- **모듈 소스** (옵션): `withAuthToken(token)` 같은 편의 메서드 추가는 가능하지만 필수 아님
+- **CI** (확인 필요): 기존 테스트가 latest 이미지를 쓴다면 CI 환경에도 토큰 설정 필요할 수 있음
+
+## 해결 방향
+
+1. 문서에 auth token 필수화 안내 + `.withEnvironment()` 사용 예시 추가
+2. 필요 시 CI 환경에 토큰 secret 추가
+
+> 편의 메서드(`withAuthToken()` 등) 추가는 **이번 이슈 범위 밖**. 문서 PR 하나로 끝낼 수 있는 일을 코드 변경까지 열어두면 범위만 커짐.
+
+## 머지 확률 평가
+
+| 요소 | 평가 |
+|------|------|
+| 긴급도 | ✅ **3/23 데드라인 — 즉시 필요** |
+| 하위 호환성 | ✅ 문서/예제 변경 중심 |
+| 변경 범위 | ✅ 매우 좁음 |
+| 경쟁자 | ✅ 없음 (5일간) |
+| **종합** | **매우 높음** |
+
+## 포트폴리오 가치
+
+**중간** — 코드 시그널은 약하지만:
+- 생태계 변화에 빠르게 대응하는 능력
+- 첫 머지 확보용으로 전략적 가치
+- LocalStack/AWS 테스팅 경험 어필
+
+## 실행 계획
+
+1. `docs/modules/localstack.md`와 관련 테스트/예제가 `latest`를 실제로 쓰는지 먼저 확인 → 문서만 수정하면 되는지, 테스트/CI도 손대야 하는지 판단
+2. LocalStack 공식 문서에서 auth token 변경사항 확인
+3. 기존 문서/예제에서 수정할 부분 특정
+4. 문서 업데이트 PR 제출 (범위를 문서/예제에 한정)
+
+## 리스크
+
+- 데드라인이 **오늘/내일** — 시간이 촉박
+- 메인테이너가 이미 직접 처리했을 가능성 → 이슈 확인 후 진행
+- auth token이 유료 플랜 전용일 수 있음 → CI에서 무료 토큰으로 테스트 가능한지 확인 필요
+- 문서 변경만으로는 코드 시그널이 약함 — **첫 머지 확보 + 후속 기여 발판** 관점