@sena-ai/platform-core 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sena-ai/platform-core",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/specs/auth.md

@@ -0,0 +1,84 @@
+# Auth & Session
+
+## 한 줄 요약
+
+관리 웹 UI 접근을 Slack OpenID Connect 로그인과 Vault 암호화 세션 쿠키로 보호한다.
+
+## 상위 스펙 연결
+
+- Related Requirements: `PLATFORM-FR-001`, `PLATFORM-FR-004`, `PLATFORM-FR-005`
+- Related AC: `PLATFORM-AC-001`, `PLATFORM-AC-004`, `PLATFORM-AC-005`
+
+## Behavior
+
+### `PLATFORM-AUTH-01` 초기 설정과 접근 제어
+
+- Trigger: `/setup` 또는 보호된 라우트 접근
+- Main Flow:
+  - 로그인 앱 설정이 없으면 setup 흐름으로 유도한다.
+  - 설정이 이미 있으면 허용된 워크스페이스 세션이 있는 사용자만 setup에 접근할 수 있다.
+
+### `PLATFORM-AUTH-02` Slack OpenID Connect 로그인
+
+- Trigger: `/auth/login` -> `/auth/callback`
+- Main Flow:
+  - authorize URL로 리다이렉트한다.
+  - state를 저장소에 만들고 10분 제한을 둔다.
+  - callback에서 state를 소비하고 token/userInfo를 조회한다.
+  - 허용 워크스페이스를 확인하고 세션 쿠키를 발급한다.
+
+### `PLATFORM-AUTH-03` 세션 검증과 로그아웃
+
+- Trigger: 보호된 웹/API 라우트 접근 또는 `/auth/logout`
+- Main Flow:
+  - 세션 쿠키를 Vault로 복호화해 구조와 만료를 검증한다.
+  - 사용자 workspace가 허용 목록에 속하면 컨텍스트에 user/session을 주입한다.
+  - 로그아웃 시 쿠키를 제거하고 로그인 페이지로 보낸다.
+
+## Constraints
+
+- `PLATFORM-AUTH-C-001`: 세션 쿠키는 `httpOnly`, `secure`, `sameSite=Lax`, `path=/`를 유지해야 한다.
+- `PLATFORM-AUTH-C-002`: state는 일회용이어야 하며 만료된 값은 허용하면 안 된다.
+- `PLATFORM-AUTH-C-003`: 보호된 API 경로와 웹 경로는 실패 응답 형식이 구분돼야 한다.
+
+## Interface
+
+- Routes:
+  - `GET /auth/login`
+  - `GET /auth/callback`
+  - `POST /auth/logout`
+  - `GET/POST /setup`, `/api/setup`
+- Session Types:
+  - `AuthSession`
+  - `AuthSessionUser`
+- Helper/API:
+  - `createAuthHandler(...)`
+  - `createAuthMiddleware(...)`
+  - `createSessionCookieValue(...)`
+  - `parseSessionCookieValue(...)`
+
+## Realization
+
+- 모듈 경계:
+  - `auth/handler.ts`가 라우트와 middleware를 담당하고 `auth/session.ts`가 쿠키 직렬화를 맡는다.
+- 상태 모델:
+  - OAuth state는 저장소에, 세션은 Vault 암호화 쿠키에 저장한다.
+- 실패 처리:
+  - 인증 실패는 API JSON 또는 웹 redirect/error page로 분리해 응답한다.
+
+## Dependencies
+
+- Depends On: `vault.md`, `database.md`, `runtime.md`
+- Blocks: `web-ui.md`, 보호된 API
+- Parallelizable With: `slack-integration.md`
+
+## AC
+
+- Given 로그인 앱 설정이 없을 때 When 관리 UI에 접근하면 Then setup 페이지로 이동한다.
+- Given 유효한 Slack 로그인 callback이 올 때 When state와 workspace 검증이 통과하면 Then 세션 쿠키가 발급된다.
+- Given 보호된 API 경로 접근 시 세션이 없을 때 When 요청하면 Then JSON 에러와 redirect 정보가 반환된다.
+## 개편 메모
+
+- AGENTS.md 가이드에 맞춰 상위/상세 스펙 섹션과 traceability를 정규화했다.
+- 기존 구현 계약을 바꾸지 않고 문서 구조와 검증 기준을 명확히 재배치했다.
+

package/specs/database.md

@@ -0,0 +1,72 @@
+# Database
+
+## 한 줄 요약
+
+플랫폼 코어는 봇, 토큰, OAuth state, 워크스페이스 설정을 공통 Repository 계약으로 저장한다.
+
+## 상위 스펙 연결
+
+- Related Requirements: `PLATFORM-FR-005`, `PLATFORM-FR-006`
+- Related AC: `PLATFORM-AC-005`
+
+## Behavior
+
+### `PLATFORM-DB-01` 봇/토큰/설정 저장
+
+- `bots`: 봇 메타데이터와 암호화된 Slack 자격 증명 저장
+- `config_tokens`: 워크스페이스별 Config Token 저장
+- `oauth_states`: OAuth state의 생성/소비/만료 정리
+- `workspace_admin_config`: Slack 로그인 앱과 웹 API 설정 저장
+
+### `PLATFORM-DB-02` 공통 Repository 계약
+
+- MySQL, PostgreSQL, D1 구현은 동일한 Repository 메서드 집합을 제공한다.
+
+### `PLATFORM-DB-03` 런타임별 DB 초기화
+
+- Node.js는 MySQL을 기본 경로로 사용한다.
+- PostgreSQL은 동일 계약의 확장 경로다.
+- CF Workers는 D1 구현을 사용한다.
+
+## Constraints
+
+- `PLATFORM-DB-C-001`: 민감 컬럼은 평문이 아닌 암호문 저장을 전제로 한다.
+- `PLATFORM-DB-C-002`: state consume는 읽기 후 삭제 semantics를 가져야 한다.
+- `PLATFORM-DB-C-003`: workspace별 설정은 workspace id 기준으로 격리되어야 한다.
+
+## Interface
+
+- Repository Contracts:
+  - `BotRepository`
+  - `ConfigTokenRepository`
+  - `OAuthStateRepository`
+  - `WorkspaceAdminConfigRepository`
+- DB Factories:
+  - `initMySQLDb`, `createMySQLRepositories`
+  - `initPostgreSQLDb`, `createPostgreSQLRepositories`
+  - `initD1`, `createD1Repositories`
+
+## Realization
+
+- 모듈 경계:
+  - DB별 schema/index 구현이 동일한 Repository 인터페이스를 만족한다.
+- 상태 모델:
+  - DB별 timestamp/enum/upsert 차이를 각 adapter 내부에 캡슐화한다.
+- 마이그레이션:
+  - Node.js는 drizzle-kit, CF Workers는 SQL migration 파일을 사용한다.
+
+## Dependencies
+
+- Depends On: Drizzle ORM, `vault.md`
+- Blocks: `auth.md`, `slack-integration.md`, `web-ui.md`
+- Parallelizable With: `runtime.md`
+
+## AC
+
+- Given 봇 또는 토큰 데이터를 저장할 때 When Repository를 사용하면 Then 각 DB 구현이 동일한 메서드 계약을 제공한다.
+- Given OAuth state를 소비할 때 When 동일 state를 다시 읽으려 하면 Then 일회용 semantics 때문에 실패한다.
+## 개편 메모
+
+- AGENTS.md 가이드에 맞춰 상위/상세 스펙 섹션과 traceability를 정규화했다.
+- 기존 구현 계약을 바꾸지 않고 문서 구조와 검증 기준을 명확히 재배치했다.
+

package/specs/index.md

@@ -0,0 +1,109 @@
+# @sena-ai/platform-core
+
+## 한 줄 요약
+
+멀티테넌트 sena-ai 플랫폼의 웹 앱, Slack 프로비저닝, 인증, 릴레이, 비밀 저장, DB, 런타임 추상화를 하나의 코어 라이브러리로 제공한다.
+
+## 문제 정의
+
+- 로컬 봇 런타임이 Slack 토큰 없이 플랫폼을 경유하도록 만들려면 릴레이/API 프록시, Vault, 인증, 프로비저닝이 함께 설계돼야 한다.
+- Node.js와 Cloudflare Workers라는 서로 다른 런타임에서 동일한 플랫폼 계약을 유지하지 않으면 운영 경로가 분기된다.
+- 관리자 UI, Slack OAuth, 이벤트 릴레이, DB 저장소가 따로 정의되면 워크스페이스 격리와 토큰 보안이 쉽게 깨질 수 있다.
+
+## 목표 & 성공 지표
+
+- 플랫폼 핵심 로직을 `Platform` 인터페이스와 `createApp()` 조합으로 런타임 독립적으로 제공한다.
+- Slack 봇 생성/설치/이벤트 수신/릴레이/API 프록시/관리 UI/인증이 하나의 패키지에서 추적 가능해야 한다.
+- 완료 기준:
+  - 상위 스펙이 플랫폼의 목표, 경계, 보안 원칙, 런타임 독립성을 명시한다.
+  - 각 도메인 스펙이 상위 FR/NFR/AC를 참조한다.
+  - 실제 소스의 라우트, 저장소, 암호화, 릴레이 의미와 문서가 일치한다.
+
+## 스펙 안정성 분류
+
+- `Stable`
+  - Zero Token Exposure 원칙
+  - Slack OAuth/Events/Relay/API Proxy의 외부 계약
+  - Vault 암호화 포맷과 워크스페이스 격리 규칙
+- `Flexible`
+  - 관리 UI 렌더링 세부 구조, 로그 문구, 부트스트랩 스크립트 UX
+- `Experimental`
+  - PostgreSQL 사용 확장, 추가 운영 API, 배포 토폴로지 확장
+
+## 용어 정의
+
+- `Platform`: 런타임 독립 서비스 조합 인터페이스.
+- `RelayHub`: 봇 런타임 연결 관리와 이벤트 디스패치를 담당하는 계층.
+- `connect_key`: 로컬 봇 런타임이 플랫폼에 인증할 때 쓰는 봇별 연결 키.
+- `Config Token`: Slack App Manifest API를 호출하기 위한 워크스페이스 단위 토큰.
+- `Workspace Admin Config`: 관리 UI 로그인 앱과 Slack 웹 API 접근 설정.
+
+## 요구사항
+
+- `PLATFORM-FR-001 [Committed][Stable]`: `createApp()`은 인증, Slack, 릴레이, 웹 UI, API를 하나의 Hono 앱으로 조립해야 한다.
+- `PLATFORM-FR-002 [Committed][Stable]`: 플랫폼은 로컬 봇 런타임에 이벤트를 전달하고 Slack API를 프록시해야 한다.
+- `PLATFORM-FR-003 [Committed][Stable]`: Slack 앱 생성/설치/삭제와 이벤트 수신을 지원해야 한다.
+- `PLATFORM-FR-004 [Committed][Stable]`: 관리 UI 접근은 Slack OpenID Connect와 세션 쿠키로 보호되어야 한다.
+- `PLATFORM-FR-005 [Committed][Stable]`: 민감 정보는 Vault로 암호화되어 저장돼야 한다.
+- `PLATFORM-FR-006 [Committed][Stable]`: MySQL, PostgreSQL, D1에 대해 동일한 Repository 계약을 제공해야 한다.
+- `PLATFORM-FR-007 [Committed][Stable]`: Node.js와 Cloudflare Workers 런타임 구현을 동일한 플랫폼 계약으로 조합할 수 있어야 한다.
+- `PLATFORM-FR-008 [Committed][Flexible]`: 웹 UI와 API는 봇 생성, 상태 확인, 삭제, 부트스트랩 스크립트 제공을 지원해야 한다.
+- `PLATFORM-NFR-001 [Committed][Stable]`: 봇 런타임은 Slack 토큰을 직접 보유하면 안 된다.
+- `PLATFORM-NFR-002 [Committed][Stable]`: 워크스페이스별 설정과 세션은 교차 접근되지 않아야 한다.
+- `PLATFORM-NFR-003 [Committed][Stable]`: Slack Events API 응답은 3초 제한을 넘기지 않도록 즉시 응답 구조를 유지해야 한다.
+- `PLATFORM-NFR-004 [Planned][Experimental]`: 플랫폼 코어는 추가 런타임/DB 조합에도 동일 계약을 유지할 수 있어야 한다.
+
+## 수용 기준 (AC)
+
+- `PLATFORM-AC-001`: Given 런타임 서비스와 저장소가 조합될 때 When `createApp()`을 호출하면 Then 플랫폼 라우트가 구성된 앱이 생성된다.
+- `PLATFORM-AC-002`: Given 유효한 `connect_key`를 가진 봇 런타임이 연결될 때 When Slack 이벤트가 들어오면 Then 이벤트는 릴레이를 통해 해당 봇으로 전달된다.
+- `PLATFORM-AC-003`: Given Config Token과 봇 정보가 있을 때 When 프로비저닝을 실행하면 Then Slack 앱 생성/OAuth/삭제 흐름이 수행된다.
+- `PLATFORM-AC-004`: Given 관리 UI 접근 시 When 로그인 앱 설정과 세션 검증이 통과하면 Then 보호된 페이지/API에 접근할 수 있다.
+- `PLATFORM-AC-005`: Given 토큰/시크릿/세션 값이 저장될 때 When DB 또는 쿠키에 기록되면 Then Vault 암호문 형태로 저장된다.
+- `PLATFORM-AC-006`: Given Node.js 또는 CF Workers 환경일 때 When 각 런타임 팩토리를 사용하면 Then 같은 `Platform` 계약으로 앱을 실행할 수 있다.
+
+## 의존관계 맵
+
+- Depends On: Hono, Drizzle ORM, Slack HTTP API, 런타임별 crypto/relay 구현
+- Blocks: `platform-node`, `platform-worker`, `platform-connector`
+- Parallelizable With: 개별 통합/관리 UI 개선
+
+## 범위 경계 (Non-goals)
+
+- Slack 외 타 플랫폼 연동은 이번 범위 밖이다.
+- 장기 데이터 분석, billing, 조직 관리 기능은 포함하지 않는다.
+- 로컬 봇 런타임 자체 구현은 `platform-connector`와 코어 외 패키지 책임이다.
+
+## 제약 & 가정
+
+- Slack App Manifest API와 OpenID Connect/OAuth 2.0 가용성을 전제로 한다.
+- Vault master key는 런타임별 비밀 환경 변수로 제공된다.
+- Node.js는 MySQL을 기본 경로로 사용하고 PostgreSQL은 확장용 구현 상태다.
+
+## 리스크 & 완화책
+
+- `Risk`: 토큰이 클라이언트나 로컬 봇에 노출되면 플랫폼 보안 모델이 무너진다.
+  - `완화`: API proxy와 connect_key 인증을 Stable 계약으로 명시한다.
+- `Risk`: 런타임별 relay/vault 구현 차이로 동작이 갈라질 수 있다.
+  - `완화`: 공통 인터페이스와 교차 런타임 호환 포맷을 문서화한다.
+- `Risk`: 워크스페이스 설정 누수가 발생할 수 있다.
+  - `완화`: auth/database/web-ui에서 workspace scoping을 명시한다.
+
+## 검증 계획
+
+- 단위 테스트 및 수동 smoke test로 OAuth, Slack Events, relay/api, 세션 쿠키, Vault 암호화, 저장소 CRUD 검증
+- Node.js/CF Workers 조립 경로를 각각 배포 패키지 수준에서 검증
+
+## 상세 스펙 맵
+
+- [auth.md](/Users/channy/workspace/sena-ai/packages/platform/core/specs/auth.md)
+- [database.md](/Users/channy/workspace/sena-ai/packages/platform/core/specs/database.md)
+- [relay.md](/Users/channy/workspace/sena-ai/packages/platform/core/specs/relay.md)
+- [runtime.md](/Users/channy/workspace/sena-ai/packages/platform/core/specs/runtime.md)
+- [slack-integration.md](/Users/channy/workspace/sena-ai/packages/platform/core/specs/slack-integration.md)
+- [vault.md](/Users/channy/workspace/sena-ai/packages/platform/core/specs/vault.md)
+- [web-ui.md](/Users/channy/workspace/sena-ai/packages/platform/core/specs/web-ui.md)
+## 개편 메모
+
+- AGENTS.md 가이드에 맞춰 상위/상세 스펙 섹션과 traceability를 정규화했다.
+- 기존 구현 계약을 바꾸지 않고 문서 구조와 검증 기준을 명확히 재배치했다.

package/specs/relay.md

@@ -0,0 +1,78 @@
+# Relay & API Proxy
+
+## 한 줄 요약
+
+릴레이는 로컬 봇 런타임과 플랫폼을 연결하고, Slack 이벤트 전달과 Slack API 프록시를 담당한다.
+
+## 상위 스펙 연결
+
+- Related Requirements: `PLATFORM-FR-001`, `PLATFORM-FR-002`, `PLATFORM-FR-005`
+- Related AC: `PLATFORM-AC-001`, `PLATFORM-AC-002`, `PLATFORM-AC-005`
+
+## Behavior
+
+### `PLATFORM-RELAY-01` 봇 연결 수립
+
+- Trigger: `GET /relay/stream?connect_key=...`
+- Main Flow:
+  - connect key로 active 봇을 찾는다.
+  - 인증이 성공하면 런타임별 relay 구현이 스트리밍 연결을 수립한다.
+  - 연결 완료 이벤트를 보낸다.
+
+### `PLATFORM-RELAY-02` Slack 이벤트 전달
+
+- Trigger: Slack event callback
+- Main Flow:
+  - 봇 ID 대상 relay에 이벤트를 dispatch 한다.
+  - 연결이 없으면 드롭하되 경고를 남긴다.
+
+### `PLATFORM-RELAY-03` Slack API 프록시
+
+- Trigger: `POST /relay/api`
+- Main Flow:
+  - `x-connect-key`로 봇을 인증한다.
+  - Vault로 봇 토큰을 복호화한다.
+  - Slack API 호출을 대행하고 응답을 돌려준다.
+
+## Constraints
+
+- `PLATFORM-RELAY-C-001`: 봇 런타임은 Slack 토큰을 직접 보유하지 않아야 한다.
+- `PLATFORM-RELAY-C-002`: 비활성 봇은 스트림 연결과 API 호출이 모두 거부돼야 한다.
+- `PLATFORM-RELAY-C-003`: 런타임별 relay 구현 차이가 있어도 `RelayHub` 외부 계약은 동일해야 한다.
+
+## Interface
+
+- `RelayHub`
+  - `handleStream(c, botId, connectKey)`
+  - `dispatch(botId, event)`
+  - `isConnected(botId)`
+  - `connectedBots()`
+- Routes:
+  - `GET /relay/stream`
+  - `POST /relay/api`
+
+## Realization
+
+- 모듈 경계:
+  - `relay/api-proxy.ts`는 Slack API proxy만, 런타임별 `runtime/*/relay.ts`는 연결 유지와 dispatch만 담당한다.
+- 상태 모델:
+  - Node.js는 봇당 SSE 연결, CF는 봇당 Durable Object/WebSocket 연결을 사용한다.
+- 실패 처리:
+  - 연결 없음은 이벤트 드롭으로 처리하되 시스템 전체 실패로 보지 않는다.
+
+## Dependencies
+
+- Depends On: `vault.md`, `database.md`, `runtime.md`
+- Blocks: `platform-connector`
+- Parallelizable With: `slack-integration.md`
+
+## AC
+
+- Given 유효한 connect key가 있을 때 When 봇 런타임이 `/relay/stream`에 연결하면 Then relay 연결이 수립된다.
+- Given Slack 이벤트가 들어올 때 When 대상 봇이 연결돼 있으면 Then 이벤트가 해당 봇에 전달된다.
+- Given 봇 런타임이 `/relay/api`를 호출할 때 When 인증이 통과하면 Then 플랫폼이 Slack API를 대신 호출한다.
+## 개편 메모
+
+- AGENTS.md 가이드에 맞춰 상위/상세 스펙 섹션과 traceability를 정규화했다.
+- 기존 구현 계약을 바꾸지 않고 문서 구조와 검증 기준을 명확히 재배치했다.
+

package/specs/runtime.md

@@ -0,0 +1,68 @@
+# Runtime Implementations
+
+## 한 줄 요약
+
+플랫폼 코어는 Node.js와 Cloudflare Workers에서 동일한 `Platform` 계약을 조립할 수 있도록 런타임별 Vault, Relay, Crypto 구현을 제공한다.
+
+## 상위 스펙 연결
+
+- Related Requirements: `PLATFORM-FR-006`, `PLATFORM-FR-007`
+- Related AC: `PLATFORM-AC-006`
+
+## Behavior
+
+### `PLATFORM-RUNTIME-01` Node.js 런타임 조립
+
+- Trigger: `createNodeRuntime(config)`
+- Main Flow:
+  - Node Vault, SSE Relay, Node Crypto를 조립해 반환한다.
+
+### `PLATFORM-RUNTIME-02` Cloudflare Workers 런타임 조립
+
+- Trigger: `createCfRuntime(env)`
+- Main Flow:
+  - CF Vault, DO Relay, CF Crypto를 비동기로 초기화해 반환한다.
+
+### `PLATFORM-RUNTIME-03` 공통 Crypto 계약
+
+- `randomHex`, `uuid`, `hmacSha256`, `timingSafeEqual`를 Promise 기반 공통 인터페이스로 제공한다.
+
+## Constraints
+
+- `PLATFORM-RUNTIME-C-001`: 런타임별 구현 차이가 있어도 `Vault`, `RelayHub`, `CryptoProvider` 외부 계약은 동일해야 한다.
+- `PLATFORM-RUNTIME-C-002`: CF와 Node의 Vault 포맷은 상호 호환 가능해야 한다.
+- `PLATFORM-RUNTIME-C-003`: timing-safe 비교는 각 런타임의 보안 특성에 맞게 구현해야 한다.
+
+## Interface
+
+- Node:
+  - `createNodeRuntime(config: NodeRuntimeConfig): NodeRuntime`
+- CF:
+  - `createCfRuntime(env: CfEnv): Promise<CfRuntime>`
+- Shared:
+  - `CryptoProvider`
+  - `Vault`
+  - `RelayHub`
+
+## Realization
+
+- 모듈 경계:
+  - `runtime/node/*`, `runtime/cf/*`가 각 책임을 나눈다.
+- 상태 모델:
+  - Node는 동기 초기화, CF는 Web Crypto import와 Durable Object binding 때문에 비동기 초기화가 필요하다.
+
+## Dependencies
+
+- Depends On: `vault.md`, `relay.md`
+- Blocks: `platform-node`, `platform-worker`
+- Parallelizable With: `database.md`
+
+## AC
+
+- Given Node.js 환경일 때 When `createNodeRuntime()`을 호출하면 Then Node용 Vault/Relay/Crypto 조합을 얻는다.
+- Given CF Workers 환경일 때 When `createCfRuntime()`을 호출하면 Then CF용 Vault/Relay/Crypto 조합을 얻는다.
+## 개편 메모
+
+- AGENTS.md 가이드에 맞춰 상위/상세 스펙 섹션과 traceability를 정규화했다.
+- 기존 구현 계약을 바꾸지 않고 문서 구조와 검증 기준을 명확히 재배치했다.
+

package/specs/slack-integration.md

@@ -0,0 +1,85 @@
+# Slack Integration
+
+## 한 줄 요약
+
+Slack 앱 프로비저닝, OAuth 설치, Events API 수신을 플랫폼 도메인 규칙에 맞게 처리한다.
+
+## 상위 스펙 연결
+
+- Related Requirements: `PLATFORM-FR-003`, `PLATFORM-FR-005`, `PLATFORM-NFR-003`
+- Related AC: `PLATFORM-AC-003`
+
+## Behavior
+
+### `PLATFORM-SLACK-01` 앱 프로비저닝
+
+- Trigger: 봇 생성 또는 재프로비저닝
+- Main Flow:
+  - workspace의 Config Token을 읽는다.
+  - manifest 템플릿에 봇 이름, 이벤트 URL, redirect URL을 주입한다.
+  - Slack App Manifest API로 앱을 생성한다.
+  - app/client/signing secret 정보를 저장한다.
+
+### `PLATFORM-SLACK-02` 봇 OAuth 설치
+
+- Trigger: `/oauth/start/:botId` -> `/oauth/callback`
+- Main Flow:
+  - state를 만들고 authorize URL로 보낸다.
+  - callback에서 state를 소비하고 `oauth.v2.access`로 봇 토큰을 얻는다.
+  - 봇 토큰을 암호화 저장하고 봇 상태를 active로 바꾼다.
+
+### `PLATFORM-SLACK-03` Events API 수신
+
+- Trigger: `POST /slack/events/:botId`
+- Main Flow:
+  - active 봇 조회 및 signing secret 검증을 수행한다.
+  - `url_verification`이면 challenge를 반환한다.
+  - `event_callback`이면 relay로 전달하고 Slack에는 즉시 `{ ok: true }`를 응답한다.
+
+### `PLATFORM-SLACK-04` Config Token 갱신
+
+- Trigger: 주기적 스케줄 또는 런타임별 bootstrap 로직
+- Main Flow:
+  - refresh token으로 새 access/refresh token을 발급받아 저장한다.
+
+## Constraints
+
+- `PLATFORM-SLACK-C-001`: 이벤트 서명 검증은 5분 이내 요청과 HMAC-SHA256 비교를 사용해야 한다.
+- `PLATFORM-SLACK-C-002`: OAuth state는 일회용이어야 한다.
+- `PLATFORM-SLACK-C-003`: Slack Events API는 3초 내 응답 가능 구조여야 한다.
+
+## Interface
+
+- Routes:
+  - `GET /oauth/start/:botId`
+  - `GET /oauth/callback`
+  - `POST /slack/events/:botId`
+- Provisioner:
+  - `rotateConfigToken(workspaceId)`
+  - `createApp(workspaceId, botId, botName, botUsername)`
+  - `deleteApp(workspaceId, appId)`
+
+## Realization
+
+- 모듈 경계:
+  - `slack/provisioner.ts`, `slack/oauth.ts`, `slack/events.ts`로 나눈다.
+- 실패 처리:
+  - Slack 앱 삭제 실패는 DB 삭제를 막지 않는다.
+  - 이벤트 전달 실패는 Slack 재시도와는 별개로 플랫폼 로그에 남긴다.
+
+## Dependencies
+
+- Depends On: `database.md`, `relay.md`, `vault.md`, `runtime.md`
+- Blocks: `web-ui.md`, `platform-node`, `platform-worker`
+- Parallelizable With: `auth.md`
+
+## AC
+
+- Given Config Token이 있을 때 When 프로비저닝을 실행하면 Then Slack 앱 생성 결과가 DB에 반영된다.
+- Given OAuth callback이 성공할 때 When bot token을 받으면 Then 봇 상태가 active로 전환된다.
+- Given Slack 이벤트가 들어올 때 When 서명 검증이 통과하면 Then 이벤트는 relay에 전달되고 Slack에는 즉시 응답한다.
+## 개편 메모
+
+- AGENTS.md 가이드에 맞춰 상위/상세 스펙 섹션과 traceability를 정규화했다.
+- 기존 구현 계약을 바꾸지 않고 문서 구조와 검증 기준을 명확히 재배치했다.
+

package/specs/vault.md

@@ -0,0 +1,70 @@
+# Vault
+
+## 한 줄 요약
+
+플랫폼 민감 정보를 AES-256-GCM으로 암복호화하고 Node.js/CF Workers 간 호환 가능한 암호문 포맷을 유지한다.
+
+## 상위 스펙 연결
+
+- Related Requirements: `PLATFORM-FR-005`, `PLATFORM-NFR-001`
+- Related AC: `PLATFORM-AC-005`, `PLATFORM-AC-006`
+
+## Behavior
+
+### `PLATFORM-VAULT-01` 암호화
+
+- Trigger: `encrypt(plaintext)`
+- Main Flow:
+  - 32바이트 master key와 랜덤 IV로 AES-256-GCM 암호화를 수행한다.
+  - `base64(IV + AuthTag + Ciphertext)` 형식으로 인코딩한다.
+
+### `PLATFORM-VAULT-02` 복호화
+
+- Trigger: `decrypt(encoded)`
+- Main Flow:
+  - 저장 형식을 파싱해 IV, auth tag, ciphertext를 분리한다.
+  - 원문 문자열을 복원한다.
+
+### `PLATFORM-VAULT-03` 런타임 간 호환
+
+- Trigger: Node에서 쓴 암호문을 CF에서 읽거나 그 반대
+- Main Flow:
+  - 두 구현이 동일한 바이너리 레이아웃을 유지한다.
+
+## Constraints
+
+- `PLATFORM-VAULT-C-001`: master key는 64자 hex, 32바이트 길이여야 한다.
+- `PLATFORM-VAULT-C-002`: 저장 포맷은 Node/CF 양쪽에서 동일해야 한다.
+- `PLATFORM-VAULT-C-003`: 평문 토큰/시크릿은 저장 계층에 직접 내려가면 안 된다.
+
+## Interface
+
+- `Vault`
+  - `encrypt(plaintext: string): Promise<string>`
+  - `decrypt(encoded: string): Promise<string>`
+- Runtimes:
+  - `createNodeVault(masterKeyHex)`
+  - `createCfVault(masterKeyHex)`
+
+## Realization
+
+- 모듈 경계:
+  - `runtime/node/vault.ts`, `runtime/cf/vault.ts`
+- 상태 모델:
+  - 키는 초기화 시 import/Buffer 변환 후 런타임 객체 안에 유지한다.
+
+## Dependencies
+
+- Depends On: Node crypto, Web Crypto
+- Blocks: `auth.md`, `database.md`, `relay.md`, `slack-integration.md`
+- Parallelizable With: `runtime.md`
+
+## AC
+
+- Given 유효한 master key가 있을 때 When `encrypt()` 후 `decrypt()`를 호출하면 Then 원문이 복원된다.
+- Given Node 또는 CF 환경일 때 When 같은 암호문을 처리하면 Then 동일한 저장 포맷으로 해석된다.
+## 개편 메모
+
+- AGENTS.md 가이드에 맞춰 상위/상세 스펙 섹션과 traceability를 정규화했다.
+- 기존 구현 계약을 바꾸지 않고 문서 구조와 검증 기준을 명확히 재배치했다.
+

package/specs/web-ui.md

@@ -0,0 +1,84 @@
+# Web UI & API
+
+## 한 줄 요약
+
+관리자는 웹 UI와 JSON API로 Slack 봇을 생성, 조회, 삭제하고 로컬 부트스트랩 정보를 얻는다.
+
+## 상위 스펙 연결
+
+- Related Requirements: `PLATFORM-FR-001`, `PLATFORM-FR-004`, `PLATFORM-FR-008`
+- Related AC: `PLATFORM-AC-001`, `PLATFORM-AC-004`
+
+## Behavior
+
+### `PLATFORM-WEB-01` 봇 생성/조회/삭제 API
+
+- Routes:
+  - `POST /api/bots`
+  - `GET /api/bots/:botId`
+  - `POST /api/bots/:botId/provision`
+  - `DELETE /api/bots/:botId`
+  - `POST /api/bots/:botId/icon`
+- Main Flow:
+  - 입력 검증 후 봇 레코드를 만들고 프로비저닝을 시작한다.
+  - 상태 조회와 삭제, 아이콘 업로드를 제공한다.
+
+### `PLATFORM-WEB-02` 관리 페이지
+
+- Routes:
+  - `/`
+  - `/bots/new`
+  - `/bots/:botId/setup`
+  - `/bots/:botId/complete`
+  - `/admin/bots`
+  - `/admin/connections`
+- Main Flow:
+  - 대시보드에 봇 목록과 상태를 보여준다.
+  - setup/complete 페이지에서 프로비저닝 상태와 설치/부트스트랩 안내를 제공한다.
+
+### `PLATFORM-WEB-03` 초기 설정과 부트스트랩 스크립트
+
+- Routes:
+  - `GET /setup`
+  - `POST /api/setup`
+  - `GET /install.sh`
+- Main Flow:
+  - Slack 로그인 앱 설정을 저장한다.
+  - `install.sh`는 로컬 프로젝트 초기화를 위한 shell 스크립트를 제공한다.
+
+## Constraints
+
+- `PLATFORM-WEB-C-001`: 보호된 페이지와 API는 auth middleware 뒤에 있어야 한다.
+- `PLATFORM-WEB-C-002`: 봇 username은 영문소문자/숫자/하이픈 규칙을 따라야 한다.
+- `PLATFORM-WEB-C-003`: 부트스트랩 스크립트는 connect key와 platform URL을 명시적으로 주입받아야 한다.
+
+## Interface
+
+- Web pages: dashboard, new bot, setup progress, completion, admin pages
+- API routes: 봇 생성/조회/재프로비저닝/삭제/아이콘 업로드, setup 저장
+
+## Realization
+
+- 모듈 경계:
+  - `web/api.ts`, `web/pages.ts`, `web/setup.ts`
+- 상태 모델:
+  - 봇 상태는 DB를 source of truth로 하고 setup page는 polling으로 반영한다.
+- 실패 처리:
+  - 프로비저닝 실패는 상태와 재시도 API로 노출한다.
+
+## Dependencies
+
+- Depends On: `auth.md`, `database.md`, `slack-integration.md`
+- Blocks: 운영 UI
+- Parallelizable With: `relay.md`
+
+## AC
+
+- Given 인증된 관리자가 있을 때 When `POST /api/bots`를 호출하면 Then pending 봇이 생성되고 프로비저닝이 시작된다.
+- Given setup/complete 페이지를 열 때 When Slack 앱 생성 또는 OAuth가 완료되면 Then 다음 단계 안내가 반영된다.
+- Given `GET /install.sh`를 호출할 때 When 필요한 인자를 전달하면 Then 로컬 부트스트랩용 shell 스크립트를 받을 수 있다.
+## 개편 메모
+
+- AGENTS.md 가이드에 맞춰 상위/상세 스펙 섹션과 traceability를 정규화했다.
+- 기존 구현 계약을 바꾸지 않고 문서 구조와 검증 기준을 명확히 재배치했다.
+