@spacebar_ai/moldclaw-core 2026.3.14 → 2026.3.16

package/docs/SEC1_IMPLEMENTATION/RECURSIVE_QA/wave1-channels.md

@@ -0,0 +1,317 @@
+# Wave 1: 채널 통합 검수
+
+**검수일**: 2026-03-22
+**검수자**: SEC-1 QA Subagent
+**대상 파일**:
+
+1. `src/secrets/runtime-config-collectors-channels.ts`
+2. `src/channels/plugins/setup-wizard-helpers.ts`
+3. `src/channels/plugins/setup-wizard-helpers.test.ts`
+
+## 발견 사항
+
+| ID     | 심각도 | 파일                                  | 설명                                                                          |
+| ------ | ------ | ------------------------------------- | ----------------------------------------------------------------------------- |
+| CH-001 | MEDIUM | runtime-config-collectors-channels.ts | `hasConfiguredSecretInputValue`와 `coerceSecretRef` 간 SEC-1 처리 불일치      |
+| CH-002 | MEDIUM | runtime-config-collectors-channels.ts | `normalizeSecretStringValue`와 `hasConfiguredSecretInputValue` 함수 동작 상충 |
+| CH-003 | LOW    | sec1-utils.ts vs sec1-placeholder.ts  | 두 모듈 간 placeholder 인식 패턴 불일치 (prefix vs exact match)               |
+| CH-004 | LOW    | runtime-config-collectors-channels.ts | SEC-1 placeholder 환경변수 미설정 시 명시적 에러 메시지 없음                  |
+| CH-005 | INFO   | setup-wizard-helpers.ts               | SEC-1 placeholder 토큰 검증 통과 구현 완료 ✅                                 |
+| CH-006 | INFO   | setup-wizard-helpers.test.ts          | SEC-1 관련 테스트 커버리지 존재 ✅                                            |
+
+## 상세 분석
+
+### CH-001: `hasConfiguredSecretInputValue`와 `coerceSecretRef` 간 SEC-1 처리 불일치 [MEDIUM]
+
+**위치**: `runtime-config-collectors-channels.ts` line 67-80
+
+**문제**:
+
+```typescript
+function hasConfiguredSecretInputValue(
+  value: unknown,
+  defaults: SecretDefaults | undefined,
+): boolean {
+  // Check for SEC-1 placeholder first - these are valid configurations
+  if (typeof value === "string" && isSec1Placeholder(value.trim())) {
+    return true; // SEC-1은 "configured"로 취급
+  }
+  return normalizeSecretStringValue(value).length > 0 || coerceSecretRef(value, defaults) !== null;
+}
+```
+
+- `hasConfiguredSecretInputValue`는 SEC-1 placeholder(`__SECURE__DISCORD_TOKEN`)를 **configured**로 취급
+- 그러나 `collectSecretInputAssignment`에서 사용하는 `coerceSecretRef`는 SEC-1 placeholder를 **인식하지 못함** (null 반환)
+- 결과적으로 SEC-1 placeholder가 "configured"라고 판단되지만 실제 secret 수집 과정에서는 제외됨
+
+**영향**: Telegram, Matrix 등의 채널에서 SEC-1 placeholder가 설정된 경우, 조건문 분기가 잘못될 수 있음
+
+**예시** (Telegram botToken):
+
+```typescript
+const accountBotTokenConfigured = hasConfiguredSecretInputValue(
+  account.botToken, // "__SECURE__TELEGRAM_BOT_TOKEN"
+  params.defaults,
+);
+// accountBotTokenConfigured = true (SEC-1이므로)
+// 하지만 collectSecretInputAssignment에서 coerceSecretRef가 null 반환하여 수집 안 됨
+```
+
+**권장 조치**:
+
+1. SEC-1 placeholder를 SecretRef로 변환하는 로직 추가, 또는
+2. SEC-1 처리를 별도 단계로 분리하여 명확한 처리 흐름 구성
+
+---
+
+### CH-002: `normalizeSecretStringValue`와 `hasConfiguredSecretInputValue` 함수 동작 상충 [MEDIUM]
+
+**위치**: `runtime-config-collectors-channels.ts` line 52-65, 67-80
+
+**문제**:
+
+```typescript
+// normalizeSecretStringValue: SEC-1 → 빈 문자열 (unconfigured)
+function normalizeSecretStringValue(value: unknown): string {
+  // ...
+  if (isSec1Placeholder(trimmed)) {
+    return "";  // unconfigured로 취급
+  }
+  return trimmed;
+}
+
+// hasConfiguredSecretInputValue: SEC-1 → true (configured)
+function hasConfiguredSecretInputValue(value: unknown, ...): boolean {
+  if (typeof value === "string" && isSec1Placeholder(value.trim())) {
+    return true;  // configured로 취급
+  }
+  // ...
+}
+```
+
+두 함수가 SEC-1 placeholder를 상반되게 취급:
+
+- `normalizeSecretStringValue`: "값 없음" (빈 문자열)
+- `hasConfiguredSecretInputValue`: "값 있음" (true)
+
+**사용처 분석**:
+
+- `normalizeSecretStringValue`: Matrix accessToken 체크 (line 475)
+- `hasConfiguredSecretInputValue`: Telegram tokenFile 조건, Matrix password 조건 등
+
+**영향**: 동일한 SEC-1 placeholder 값에 대해 함수에 따라 다른 해석이 발생
+
+**권장 조치**:
+
+- SEC-1 placeholder의 의미를 명확히 정의하고 두 함수의 동작을 일관되게 통일
+- 주석으로 의도 명시 (의도된 동작이라면)
+
+---
+
+### CH-003: 두 SEC-1 모듈 간 placeholder 인식 패턴 불일치 [LOW]
+
+**위치**:
+
+- `sec1-utils.ts`: `isSec1Placeholder()` - prefix match
+- `sec1-placeholder.ts`: `isSecurePlaceholder()` - exact match
+
+**문제**:
+
+```typescript
+// sec1-utils.ts - prefix match
+export function isSec1Placeholder(value: unknown): boolean {
+  return value.startsWith(SEC1_PREFIX); // "__SECURE__"로 시작하면 모두 인식
+}
+
+// sec1-placeholder.ts - exact match
+const SEC1_PLACEHOLDER_PATTERN = /^__SECURE__$/i; // 정확히 "__SECURE__"만 인식
+```
+
+| 입력값                    | sec1-utils.ts | sec1-placeholder.ts |
+| ------------------------- | ------------- | ------------------- |
+| `__SECURE__`              | ✅ true       | ✅ true             |
+| `__SECURE__DISCORD_TOKEN` | ✅ true       | ❌ false            |
+| `__SECURE__API_KEY`       | ✅ true       | ❌ false            |
+
+**현재 상황**:
+
+- `runtime-config-collectors-channels.ts`는 `sec1-utils.ts`의 `isSec1Placeholder` 사용 (prefix match)
+- `provider-env-vars.ts`는 `sec1-placeholder.ts`의 `isSecurePlaceholder` 사용 (exact match)
+
+**영향**: `__SECURE__DISCORD_TOKEN` 형태의 확장 placeholder가 모듈에 따라 다르게 해석됨
+
+**권장 조치**:
+
+- 하나의 표준 패턴으로 통일
+- `sec1-placeholder.ts`의 `isSecurePlaceholderExtended()` 활용 권장
+
+---
+
+### CH-004: SEC-1 환경변수 미설정 시 명시적 에러 메시지 없음 [LOW]
+
+**위치**: `runtime-config-collectors-channels.ts` 전체
+
+**문제**:
+SEC-1 placeholder가 설정되어 있고 해당 환경변수가 없을 때, 명시적인 에러 메시지가 없음
+
+**현재 동작**:
+
+1. SEC-1 placeholder 감지됨
+2. `hasConfiguredSecretInputValue` → true (configured로 판단)
+3. 하지만 실제 런타임에서 환경변수 없으면 silent failure
+
+**권장 조치**:
+
+- SEC-1 placeholder 발견 시 해당 환경변수 존재 여부 체크
+- 환경변수 미설정 시 warning 또는 error 메시지 추가
+
+예시:
+
+```typescript
+if (isSec1Placeholder(value)) {
+  const envVar = extractSec1Identifier(value);
+  if (envVar && !process.env[envVar]) {
+    pushWarning(context, {
+      code: "SEC1_ENV_VAR_MISSING",
+      path: params.path,
+      message: `SEC-1 placeholder requires environment variable ${envVar} but it is not set.`,
+    });
+  }
+}
+```
+
+---
+
+### CH-005: setup-wizard-helpers.ts SEC-1 구현 ✅ [INFO]
+
+**상태**: 정상 구현됨
+
+`validateTokenFormat` 함수에서 SEC-1 placeholder를 올바르게 처리:
+
+```typescript
+export function validateTokenFormat(
+  token: string,
+  provider: keyof typeof TOKEN_VALIDATORS,
+): TokenValidationResult {
+  // ...
+  // SEC-1: Allow __SECURE__ placeholders without format validation
+  if (isSec1Placeholder(trimmed)) {
+    return { valid: true };
+  }
+  // ...
+}
+```
+
+- SEC-1 placeholder는 토큰 형식 검증을 건너뜀 ✅
+- 주석으로 의도 명시됨 ✅
+
+---
+
+### CH-006: setup-wizard-helpers.test.ts SEC-1 테스트 커버리지 ✅ [INFO]
+
+**상태**: 적절한 테스트 존재
+
+```typescript
+describe("SEC-1 support", () => {
+  it("accepts SEC-1 placeholders without format validation", () => {
+    expect(validateTokenFormat("__SECURE__DISCORD_TOKEN", "discord")).toEqual({ valid: true });
+    expect(validateTokenFormat("__SECURE__TELEGRAM_BOT_TOKEN", "telegram")).toEqual({
+      valid: true,
+    });
+    expect(validateTokenFormat("__SECURE__SLACK_TOKEN", "slack")).toEqual({ valid: true });
+    expect(validateTokenFormat("__SECURE__API_KEY", "openai")).toEqual({ valid: true });
+    expect(validateTokenFormat("__SECURE__ANY_SECRET", "generic")).toEqual({ valid: true });
+  });
+
+  it("accepts SEC-1 placeholders with whitespace", () => {
+    expect(validateTokenFormat("  __SECURE__TOKEN  ", "discord")).toEqual({ valid: true });
+  });
+});
+
+describe("createTokenValidator", () => {
+  it("accepts SEC-1 placeholders", () => {
+    const validator = createTokenValidator("discord");
+    expect(validator("__SECURE__DISCORD_TOKEN")).toBeUndefined();
+  });
+});
+```
+
+---
+
+## 채널별 SEC-1 지원 현황
+
+| 채널           | SEC-1 지원 | 비고                                         |
+| -------------- | ---------- | -------------------------------------------- |
+| Telegram       | ✅         | botToken, webhookSecret                      |
+| Slack          | ✅         | botToken, userToken, appToken, signingSecret |
+| Discord        | ✅         | token, pluralkit.token, voice.tts            |
+| IRC            | ✅         | password, nickserv.password                  |
+| BlueBubbles    | ✅         | password                                     |
+| Mattermost     | ✅         | botToken                                     |
+| Matrix         | ✅         | password                                     |
+| MSTeams        | ✅         | appPassword                                  |
+| Nextcloud Talk | ✅         | botSecret, apiPassword                       |
+| Feishu         | ✅         | appSecret, encryptKey, verificationToken     |
+| Zalo           | ✅         | botToken, webhookSecret                      |
+| Google Chat    | ✅         | serviceAccount                               |
+
+모든 채널이 `collectSecretInputAssignment`를 통해 secret input을 수집하며, SEC-1 placeholder 감지 로직(`isSec1Placeholder`)이 적용되어 있음.
+
+---
+
+## 기존 호환성 분석
+
+### `${ENV_VAR}` 방식과의 충돌 여부
+
+**결론**: 충돌 없음 ✅
+
+**분석**:
+
+1. **`${ENV_VAR}` 처리**: `types.secrets.ts`의 `parseEnvTemplateSecretRef()` → `coerceSecretRef()`
+2. **`__SECURE__*` 처리**: `sec1-utils.ts`의 `isSec1Placeholder()`
+
+두 방식은 서로 다른 경로로 처리됨:
+
+- `${DISCORD_TOKEN}` → `coerceSecretRef` → `SecretRef` 객체 생성 → secret resolver가 해석
+- `__SECURE__DISCORD_TOKEN` → `isSec1Placeholder`로 감지 → 각 채널 코드에서 환경변수 폴백
+
+**주의사항**:
+
+- `${ENV_VAR}`는 SecretRef 기반 시스템에서 처리
+- `__SECURE__*`는 SEC-1 fallback 시스템에서 처리
+- 동일한 설정에 두 방식을 혼용하지 않도록 문서화 필요
+
+---
+
+## 종합 평가
+
+### 통합 완전성: ⚠️ 부분적
+
+- 모든 12개 채널이 `isSec1Placeholder` 기반 감지 지원
+- 그러나 `hasConfiguredSecretInputValue`와 `coerceSecretRef` 간 불일치 존재 (CH-001)
+
+### 런타임 동작: ⚠️ 추가 확인 필요
+
+- `runtime-config-collectors-channels.ts`는 **수집 단계**
+- 실제 환경변수 해석은 각 채널 초기화 코드에서 `resolveWithSecureFallback` 호출로 수행되어야 함
+- 각 채널 플러그인 코드의 SEC-1 해석 로직 검수 필요
+
+### 에러 처리: ⚠️ 개선 필요
+
+- SEC-1 placeholder 환경변수 미설정 시 silent failure
+- 명시적 경고/에러 메시지 추가 권장 (CH-004)
+
+### 기존 호환성: ✅ 양호
+
+- `${ENV_VAR}` 방식과 충돌 없음
+- 두 시스템이 독립적으로 동작
+
+---
+
+## 권장 액션 아이템
+
+1. **[HIGH]** CH-001 해결: `hasConfiguredSecretInputValue`와 `coerceSecretRef` 동작 일관성 확보
+2. **[MEDIUM]** CH-002 해결: `normalizeSecretStringValue` 함수 의도 명확화 또는 동작 통일
+3. **[LOW]** CH-003 해결: SEC-1 placeholder 패턴 표준화 (prefix vs exact)
+4. **[LOW]** CH-004 해결: SEC-1 환경변수 미설정 시 경고 메시지 추가
+5. **[INFO]** 각 채널 플러그인 코드에서 `resolveWithSecureFallback` 사용 여부 Wave 2에서 검수

package/docs/SEC1_IMPLEMENTATION/RECURSIVE_QA/wave1-docs.md

@@ -0,0 +1,212 @@
+# Wave 1: 문서 품질 검수
+
+> **검수일**: 2026-03-22  
+> **검수자**: Subagent (sec1-qa-docs)  
+> **범위**: SEC-1 관련 모든 문서
+
+## 발견 사항
+
+| ID      | 심각도 | 파일                                 | 설명                                                                    |
+| ------- | ------ | ------------------------------------ | ----------------------------------------------------------------------- |
+| DOC-001 | HIGH   | SEC1.md, CHANNELS_REPORT.md          | 두 SEC-1 모듈(`sec1-placeholder.ts` vs `sec1-utils.ts`)의 차이점 미설명 |
+| DOC-002 | HIGH   | SEC1.md                              | Case sensitivity 동작 미설명 - 두 모듈이 서로 다르게 처리               |
+| DOC-003 | MEDIUM | SEC1.md, README.md, ENV_MAP_DRAFT.md | 환경변수 이름 불일치 (DISCORD_TOKEN vs DISCORD_BOT_TOKEN)               |
+| DOC-004 | MEDIUM | STRATEGY.md                          | 체크리스트가 모두 미완료 `[ ]` 상태지만 실제 구현은 완료됨              |
+| DOC-005 | MEDIUM | SEC1.md                              | API 레퍼런스 불완전 - `sec1-utils.ts`의 일부 함수 누락                  |
+| DOC-006 | LOW    | ENV_MAP_DRAFT.md                     | 파일명에 "DRAFT"가 있지만 공식 문서로 포함됨                            |
+| DOC-007 | LOW    | SEC1.md                              | Tauri IPC 예제가 실제 구현 없이 이론적 예시만 제공                      |
+| DOC-008 | MEDIUM | CHANNELS_REPORT.md                   | `hasConfiguredSecretInputValue()` 함수명이 실제 코드와 다름             |
+
+## 상세 분석
+
+### DOC-001: 두 SEC-1 모듈의 차이점 미설명 (HIGH)
+
+**문제**:
+프로젝트에 SEC-1 관련 두 개의 모듈이 존재하지만 문서에서 이 차이를 명확히 설명하지 않음:
+
+1. **`sec1-placeholder.ts`**:
+   - `isSecurePlaceholder()`: **정확한 `__SECURE__` 매칭**
+   - Case-insensitive (`__SECURE__`, `__secure__` 모두 허용)
+   - `__SECURE__`만 매칭, `__SECURE__DISCORD` 불일치
+2. **`sec1-utils.ts`**:
+   - `isSec1Placeholder()`: **`__SECURE__` prefix 매칭**
+   - Case-sensitive (`__SECURE__`만 허용)
+   - `__SECURE__DISCORD_TOKEN` 같은 식별자 포함 형식 지원
+
+**영향**:
+사용자가 잘못된 모듈/함수를 사용할 수 있음.
+
+**권장 조치**:
+SEC1.md에 "두 가지 SEC-1 유틸리티 모듈" 섹션 추가하여 차이점 명시.
+
+---
+
+### DOC-002: Case sensitivity 동작 미설명 (HIGH)
+
+**문제**:
+문서에서 SEC-1 플레이스홀더의 case sensitivity에 대해 언급하지 않음.
+
+**실제 동작**:
+
+```typescript
+// sec1-placeholder.ts - case-insensitive
+isSecurePlaceholder("__secure__"); // true ✅
+isSecurePlaceholder("__SECURE__"); // true ✅
+
+// sec1-utils.ts - case-sensitive
+isSec1Placeholder("__secure__"); // false ❌
+isSec1Placeholder("__SECURE__"); // true ✅
+```
+
+**영향**:
+사용자가 `__secure__`를 사용하면 일부 기능에서는 작동하고 일부에서는 작동하지 않음.
+
+**권장 조치**:
+
+1. SEC1.md에 case sensitivity 섹션 추가
+2. 권장 형식 명시: `__SECURE__` (대문자만 사용)
+
+---
+
+### DOC-003: 환경변수 이름 불일치 (MEDIUM)
+
+**문제**:
+문서와 코드에서 Discord 토큰 환경변수 이름이 불일치:
+
+| 출처                                     | 환경변수 이름       |
+| ---------------------------------------- | ------------------- |
+| SEC1.md 예제                             | `DISCORD_BOT_TOKEN` |
+| README.md                                | `DISCORD_BOT_TOKEN` |
+| ENV_MAP_DRAFT.md                         | `DISCORD_TOKEN`     |
+| 테스트 코드 (sec1-placeholder.test.ts)   | `DISCORD_TOKEN`     |
+| 실제 코드 (plugin-auto-enable.ts, io.ts) | `DISCORD_BOT_TOKEN` |
+
+**영향**:
+사용자가 ENV_MAP_DRAFT.md를 참고하면 잘못된 환경변수 이름 사용 가능.
+
+**권장 조치**:
+
+1. 공식적으로 사용하는 환경변수 이름 통일
+2. ENV_MAP_DRAFT.md 업데이트 또는 실제 구현과 동기화
+
+---
+
+### DOC-004: STRATEGY.md 체크리스트 미완료 상태 (MEDIUM)
+
+**문제**:
+STRATEGY.md의 체크리스트가 모두 미완료 `[ ]` 상태:
+
+```markdown
+- [ ] `secure-marker-env-map.ts` 생성
+- [ ] `secure-marker.ts` 구현
+- [ ] `coerceSecretRef()` 확장
+      ...
+```
+
+**실제 상태**:
+SEC-1 구현이 완료됨 (`sec1-placeholder.ts`, `sec1-utils.ts` 존재 및 테스트 통과).
+
+**영향**:
+문서를 읽는 사람이 SEC-1이 아직 구현되지 않았다고 오해할 수 있음.
+
+**권장 조치**:
+
+1. 체크리스트를 완료 상태 `[x]`로 업데이트
+2. 또는 STRATEGY.md를 "구현 완료 보고서"로 변환
+
+---
+
+### DOC-005: API 레퍼런스 불완전 (MEDIUM)
+
+**문제**:
+SEC1.md의 `sec1-utils.ts` API 레퍼런스에서 다음 함수 누락:
+
+| 누락된 함수                           | 설명                                       |
+| ------------------------------------- | ------------------------------------------ |
+| `normalizeSecretStringValueSec1()`    | SEC-1 필터링이 적용된 시크릿 문자열 정규화 |
+| `hasConfiguredSecretInputValueSec1()` | SEC-1 제외 구성된 시크릿 입력 값 확인      |
+
+**영향**:
+개발자가 완전한 API를 파악하기 어려움.
+
+**권장 조치**:
+SEC1.md API 레퍼런스 섹션에 누락된 함수 추가.
+
+---
+
+### DOC-006: DRAFT 문서 상태 (LOW)
+
+**문제**:
+`ENV_MAP_DRAFT.md` 파일명에 "DRAFT"가 포함되어 있어 초안임을 나타내지만, SEC1_IMPLEMENTATION 디렉토리에 공식 문서처럼 포함됨.
+
+**권장 조치**:
+
+1. 실제 구현과 동기화 후 "DRAFT" 제거
+2. 또는 README에 "초안 문서" 명시
+
+---
+
+### DOC-007: Tauri IPC 예제 검증 불가 (LOW)
+
+**문제**:
+SEC1.md의 Tauri IPC 예제 코드:
+
+```rust
+#[tauri::command]
+async fn sec1_store_secret(...)
+```
+
+이 예제는 이론적인 구현 가이드이며, moldclaw-core 레포지토리에서 실제 Tauri 백엔드 코드를 확인할 수 없음.
+
+**영향**:
+예제가 실제로 작동하는지 검증 불가.
+
+**권장 조치**:
+
+1. 예제가 이론적 가이드임을 명시
+2. 또는 실제 Tauri 앱 레포지토리 링크 추가
+
+---
+
+### DOC-008: 함수명 불일치 (MEDIUM)
+
+**문제**:
+CHANNELS_REPORT.md에서 설명하는 함수명과 실제 코드의 함수명이 다름:
+
+| 문서                              | 실제 코드                                                                           |
+| --------------------------------- | ----------------------------------------------------------------------------------- |
+| `hasConfiguredSecretInputValue()` | `hasConfiguredSecretInputValueSec1()` (sec1-utils.ts)                               |
+|                                   | `hasConfiguredSecretInputValue()` (runtime-config-collectors-channels.ts 내부 함수) |
+
+**영향**:
+개발자가 올바른 함수를 import하기 어려움.
+
+**권장 조치**:
+CHANNELS_REPORT.md에서 함수의 정확한 위치와 이름 명시.
+
+---
+
+## 검증된 항목 (이상 없음)
+
+| 항목                             | 상태    | 비고                                  |
+| -------------------------------- | ------- | ------------------------------------- |
+| SEC1.md 플레이스홀더 형식 설명   | ✅ 정확 | `__SECURE__` 및 `__SECURE__<ID>` 형식 |
+| README.md SEC-1 섹션 존재        | ✅ 확인 | Quick Start 가이드 포함               |
+| 테스트 커버리지                  | ✅ 충분 | 30+ 테스트 케이스                     |
+| sec1-placeholder.ts API 레퍼런스 | ✅ 정확 | 문서와 구현 일치                      |
+
+---
+
+## 권장 우선순위
+
+| 우선순위 | ID               | 예상 소요 시간 |
+| -------- | ---------------- | -------------- |
+| 1        | DOC-001, DOC-002 | 30분           |
+| 2        | DOC-003          | 15분           |
+| 3        | DOC-004          | 10분           |
+| 4        | DOC-005, DOC-008 | 20분           |
+| 5        | DOC-006, DOC-007 | 10분           |
+
+---
+
+_Generated by SEC-1 QA Subagent_