KOR | ENG

sshbridge

sshbridge는 Kotlin Multiplatform + Compose Multiplatform 기반의 모바일 SSH 앱 실험 저장소입니다. 목표는 모바일에서 원격 shell 작업을 더 덜 불편하게 만들고, tmux 세션 선택 진입 같은 실제 운영 흐름을 Android 앱 MVP 수준까지 연결하는 것이었습니다.

이 저장소는 현재 더 이상 적극적으로 개발하지 않는 스냅샷입니다. 다만 Android-first SSH MVP, terminal session 흐름, 보안 경계, 부가 기능 시도들이 남아 있어 참고하거나 재사용할 수 있도록 공개 가능한 형태로 정리했습니다.

무엇을 만들려고 했는가

• 모바일에서 원격 SSH shell에 빠르게 접속할 수 있는 앱
• 특히, 시중 앱의 경우 한국어 입력이 부드럽지 않은 것들이 많아 이를 해결하기 위함
• host key 검증과 credential 저장을 포함한 기본 보안 경계
• 단순 exec가 아니라 interactive PTY 기반 terminal session
• 저장된 프로필, 재접속, startup command, tmux attach 같은 실사용 흐름
• SFTP, Git diff, browser preview 같은 side-channel 기능
• 장기적으로는 Mosh와 iOS 확장까지 고려한 구조

현재 포함된 구현

• Kotlin Multiplatform 구조: shared, composeApp, androidApp, androidSsh
• Android native SSH bridge: libssh2 + mbedTLS
• host key SHA256 probe와 TOFU 기반 trust gate
• password, private key, passphrase-protected key 인증 경로
• interactive PTY shell open/read/write/resize/close 흐름
• Compose 기반 Android MVP connect / terminal input / reconnect UI
• Android Keystore 기반 저장 프로필 및 credential/passphrase 저장
• tmux session list와 one-tap attach seed
• SFTP list/read/upload/download MVP seed
• remote Git diff preview seed
• SSH port forwarding 기반 browser preview seed

아직 완성되지 않은 부분

• Mosh native integration
• 완전한 xterm 호환 terminal renderer
• IME composition과 hardware keyboard 고도화
• Ed25519-only host key / user auth 지원
• 대용량 SFTP streaming, byte-level progress, resume
• iOS native SSH bridge와 실제 iOS product flow
• cloud sync, encrypted export/import, billing adapter

기술 구조

모듈	역할
shared	domain model, validator, host key policy, terminal core seed, session controller
composeApp	Compose Multiplatform UI 레이어
androidApp	Android app entrypoint와 product UI
androidSsh	Android JNI/CMake SSH native bridge

구조와 설계 선택은 docs/architecture.md, docs/technical-decisions.md, ADR 문서에 정리했습니다.

문서 안내

• 프로젝트 개요
• 구현 상태
• 설계와 구조
• 개발 과정 정리
• 보안 및 프라이버시 경계
• 기술 결정 요약
• 스크린샷

빌드 메모

이 저장소는 npm 패키지가 아니라 Gradle/Kotlin Multiplatform 프로젝트입니다. 최소한 다음 환경이 필요합니다.

• JDK 17+
• Android SDK / NDK / CMake
• Android emulator 또는 실기기

대표 명령은 아래와 같습니다.

npm ci
npm run shared:test
npm run android:debug
npm run android:native
npm run ios:framework

추가 smoke 스크립트는 scripts/android/ 아래에 남아 있습니다. 다만 이 스크립트들은 로컬 SSH 서버, emulator, test fixture에 의존하므로 그대로 재현되지는 않을 수 있습니다.

스크린샷

현재 저장소에는 password auth 기반 tmux attach 흐름 스크린샷이 포함돼 있습니다.

• tmux password attach screenshots

공개 이유

원래는 Android MVP를 더 밀고 iOS와 Mosh까지 연결할 계획이었습니다. 하지만 우선순위가 다른 프로젝트로 이동하면서 여기서 멈췄고, 구현된 구조와 실험 결과는 다른 작업에 참고가 될 수 있다고 판단했습니다. 그래서 개발 중단 시점의 상태를 다듬어 공개 가능한 형태로 남깁니다.

라이선스

이 저장소의 코드와 문서는 MIT License로 배포합니다. 상업적 사용, 수정, 재배포를 포함해 자유롭게 활용할 수 있습니다.