@aemeath/surf-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SolarisCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# 🌊 surf-cli
+
+`surf-cli` は、Surfshark の OpenVPN 手動設定を CLI から扱うための TypeScript 製ツールです。Linux を主対象にし、`openvpn` が導入済みであることを前提に `sudo openvpn` を起動します。macOS は `openvpn` CLI がある場合のみ best-effort です。
+
+> 注意: Surfshark 公式ドキュメントでは、OpenVPN 手動接続で使う username/password は通常のアカウントメール・パスワードとは別物です。通常ログイン API は公開仕様ではないため、メール/パスワード・コードログインは experimental とし、失敗時は手動 OpenVPN 認証情報入力へフォールバックします。
+
+## 📦 インストール
+
+### パッケージマネージャー
+
+```bash
+npm install -g @aemeath/surf-cli
+# bun install -g @aemeath/surf-cli
+# pnpm install -g @aemeath/surf-cli
+# yarn global add @aemeath/surf-cli
+```
+
+### インストールスクリプト
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/aemeath/surf-cli/master/scripts/install.sh | bash
+```
+
+### 開発版（ソースから）
+
+```bash
+git clone https://codeberg.org/aemeath/surf-cli.git
+cd surf-cli
+corepack enable
+pnpm install
+pnpm build
+pnpm link --global
+```
+
+## ✅ 要件
+
+- Node.js 22 以上
+- Linux（推奨）または macOS（best-effort）
+- `openvpn`
+- `sudo`
+- Surfshark の有効な契約
+
+## 🚀 使い方
+
+### Quick Start
+
+```bash
+surf-cli doctor                    # 前提条件を確認
+surf-cli auth login --manual       # OpenVPN 認証情報を登録
+surf-cli servers refresh           # サーバー設定をダウンロード
+surf-cli connect jp-tok            # 日本・東京サーバーに接続
+surf-cli status                    # 接続状態を確認
+surf-cli disconnect                # 切断
+```
+
+ヘルプは `surf-cli --help` または各コマンドで `surf-cli <command> --help` で確認できます。
+
+## 🔐 認証
+
+推奨は Surfshark dashboard の `VPN > Manual Setup > Desktop or mobile > OpenVPN` で確認できる OpenVPN service credentials の手動登録です。
+
+```bash
+surf-cli auth login --manual
+```
+
+experimental なログイン経路（`--email`, `--code`）も用意していますが、Surfshark の非公開 Web API に依存するため、OpenVPN service credentials を取得できない場合は手動入力へフォールバックします。
+
+認証情報は OS keyring（`@napi-rs/keyring`）へ保存します。keyring が使えない環境では、平文ファイルへ自動保存しません。
+
+詳細は [`docs/topics/authentication.md`](docs/topics/authentication.md) を参照してください。
+
+## 🔧 トラブルシュート
+
+`CONNECTION_FAILED` で OpenVPN が初期化前に終了した場合、`surf-cli` は OpenVPN log、起動直後の stderr/stdout、終了コードの順に診断情報を表示します。
+
+- まず `surf-cli doctor` で `openvpn` と `sudo` が利用できるか確認してください。
+- sudo password prompt が出る場合は、端末でパスワードを入力してください。
+- 詳細を直接確認したい場合は `surf-cli connect jp-tok --foreground` のように foreground 実行してください。
+- `AUTH_FAILED` の場合は、通常の Surfshark アカウントではなく OpenVPN service credentials を `surf-cli auth login --manual` で登録し直してください。
+
+詳細は [`docs/topics/vpn-connection.md`](docs/topics/vpn-connection.md) を参照してください。
+
+## 📚 ドキュメント
+
+| ドキュメント                                                     | 内容                                         |
+| ---------------------------------------------------------------- | -------------------------------------------- |
+| [`docs/README.md`](docs/README.md)                               | ドキュメントインデックス・アーキテクチャ概要 |
+| [`docs/topics/authentication.md`](docs/topics/authentication.md) | 認証方法の詳細                               |
+| [`docs/topics/vpn-connection.md`](docs/topics/vpn-connection.md) | VPN 接続モデルの詳細                         |
+| [`docs/topics/server-catalog.md`](docs/topics/server-catalog.md) | サーバー設定の取得・展開・検索               |
+| [`docs/topics/data-storage.md`](docs/topics/data-storage.md)     | データ保存場所・XDG パス・権限               |
+| [`docs/topics/error-handling.md`](docs/topics/error-handling.md) | エラー種別・exit code                        |
+| [`docs/development.md`](docs/development.md)                     | 開発手順・CI/CD                              |
+
+## 🔒 セキュリティ
+
+- Surfshark アカウントパスワードは保存しません。
+- OpenVPN service credentials は OS keyring に保存します。
+- 実行時 auth file は XDG runtime 配下に 0600 で作成します。
+- CI に Surfshark credentials を渡す設計にはしていません。
+
+脆弱性の報告は [`SECURITY.md`](SECURITY.md) を参照してください。

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## 対象
+
+`surf-cli` は Surfshark OpenVPN 手動設定をローカル端末で扱う CLI です。現在の主対象は Linux です。
+
+## 機密情報の扱い
+
+- Surfshark アカウントメール/パスワードは永続化しません。
+- OpenVPN service credentials は OS keyring に保存します。
+- keyring が使えない場合、平文ファイルへの自動保存は行いません。
+- OpenVPN 実行時のみ `$XDG_RUNTIME_DIR/surf-cli/openvpn.auth` を 0600 で作成します。
+- ログとエラーメッセージには password/token を出さない方針です。
+
+## 非公開 API について
+
+メール/パスワード・コードログインは Surfshark の公開仕様ではない Web API に依存する experimental 機能です。仕様変更や 2FA/Cloudflare challenge により失敗する可能性があります。安定運用には `surf-cli auth login --manual` を使ってください。
+
+## 報告
+
+脆弱性を見つけた場合は、公開 issue に秘密情報を含めず、Codeberg の issue で概要のみを共有してください。認証情報、ログ、`.ovpn` 以外の個人情報、トークンは貼り付けないでください。

package/dist/adapters/credential-store.d.ts

@@ -0,0 +1,26 @@
+import { type OpenVpnCredentials } from '../core/types.js';
+export interface CredentialStoreStatus {
+    available: boolean;
+    backend: string;
+    message?: string;
+}
+export interface CredentialStore {
+    get(): Promise<OpenVpnCredentials | null>;
+    set(credentials: OpenVpnCredentials): Promise<void>;
+    delete(): Promise<void>;
+    status(): Promise<CredentialStoreStatus>;
+}
+export declare class KeyringCredentialStore implements CredentialStore {
+    get(): Promise<OpenVpnCredentials | null>;
+    set(credentials: OpenVpnCredentials): Promise<void>;
+    delete(): Promise<void>;
+    status(): Promise<CredentialStoreStatus>;
+    private createEntry;
+}
+export declare class MemoryCredentialStore implements CredentialStore {
+    private credentials;
+    get(): Promise<OpenVpnCredentials | null>;
+    set(credentials: OpenVpnCredentials): Promise<void>;
+    delete(): Promise<void>;
+    status(): Promise<CredentialStoreStatus>;
+}

package/dist/adapters/credential-store.js

@@ -0,0 +1,69 @@
+import { SurfCliError } from '../core/errors.js';
+import { openVpnCredentialsSchema } from '../core/types.js';
+const SERVICE_NAME = 'surf-cli';
+const ACCOUNT_NAME = 'openvpn-service-credentials';
+export class KeyringCredentialStore {
+    async get() {
+        const entry = await this.createEntry();
+        const value = entry.getPassword();
+        if (!value) {
+            return null;
+        }
+        return openVpnCredentialsSchema.parse(JSON.parse(value));
+    }
+    async set(credentials) {
+        const parsed = openVpnCredentialsSchema.parse(credentials);
+        const entry = await this.createEntry();
+        entry.setPassword(JSON.stringify(parsed));
+    }
+    async delete() {
+        const entry = await this.createEntry();
+        try {
+            entry.deletePassword();
+        }
+        catch (error) {
+            if (error instanceof Error && /not found|no matching/i.test(error.message)) {
+                return;
+            }
+            throw error;
+        }
+    }
+    async status() {
+        try {
+            await this.createEntry();
+            return { available: true, backend: '@napi-rs/keyring' };
+        }
+        catch (error) {
+            return {
+                available: false,
+                backend: '@napi-rs/keyring',
+                message: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    async createEntry() {
+        try {
+            const keyring = (await import('@napi-rs/keyring'));
+            return new keyring.Entry(SERVICE_NAME, ACCOUNT_NAME);
+        }
+        catch (error) {
+            throw new SurfCliError('AUTH_REQUIRED', 'OS keyring is unavailable. Install a desktop keyring service, or run connect interactively to enter credentials for this session.', { cause: error });
+        }
+    }
+}
+export class MemoryCredentialStore {
+    credentials = null;
+    async get() {
+        return this.credentials;
+    }
+    async set(credentials) {
+        this.credentials = openVpnCredentialsSchema.parse(credentials);
+    }
+    async delete() {
+        this.credentials = null;
+    }
+    async status() {
+        return { available: true, backend: 'memory' };
+    }
+}
+//# sourceMappingURL=credential-store.js.map

package/dist/adapters/credential-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-store.js","sourceRoot":"","sources":["../../src/adapters/credential-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAA2B,MAAM,kBAAkB,CAAC;AAyBrF,MAAM,YAAY,GAAG,UAAU,CAAC;AAChC,MAAM,YAAY,GAAG,6BAA6B,CAAC;AAEnD,MAAM,OAAO,sBAAsB;IACjC,KAAK,CAAC,GAAG;QACP,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,wBAAwB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,WAA+B;QACvC,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAC3D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACvC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,MAAM;QACV,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,CAAC;YACH,KAAK,CAAC,cAAc,EAAE,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,IAAI,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3E,OAAO;YACT,CAAC;YAED,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;YACzB,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;QAC1D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,SAAS,EAAE,KAAK;gBAChB,OAAO,EAAE,kBAAkB;gBAC3B,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAChE,CAAC;QACJ,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,WAAW;QACvB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,CAAC,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAkB,CAAC;YACpE,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,YAAY,CACpB,eAAe,EACf,mIAAmI,EACnI,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAED,MAAM,OAAO,qBAAqB;IACxB,WAAW,GAA8B,IAAI,CAAC;IAEtD,KAAK,CAAC,GAAG;QACP,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,WAA+B;QACvC,IAAI,CAAC,WAAW,GAAG,wBAAwB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACjE,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,MAAM;QACV,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAChD,CAAC;CACF"}

package/dist/adapters/openvpn-runner.d.ts

@@ -0,0 +1,56 @@
+import type { Protocol } from '../core/types.js';
+export interface OpenVpnProcessInfo {
+    pid: number;
+    commandLine: string;
+}
+export interface OpenVpnStartOptions {
+    configPath: string;
+    authFilePath: string;
+    pidFilePath: string;
+    statusFilePath: string;
+    logFilePath: string;
+    foreground: boolean;
+    useSudo?: boolean;
+    initTimeoutMs?: number;
+}
+export interface OpenVpnStartResult {
+    pid: number;
+}
+export interface ParsedOpenVpnStatus {
+    updatedAt?: string;
+    statistics: Record<string, string>;
+    raw: string;
+}
+export declare class OpenVpnRunner {
+    start(options: OpenVpnStartOptions): Promise<OpenVpnStartResult>;
+    terminate(pid: number, useSudo?: boolean): Promise<void>;
+    isAlive(pid: number): Promise<boolean>;
+    isManagedOpenVpnProcess(pid: number, configPath: string): Promise<boolean>;
+    readStatus(statusFilePath: string): Promise<ParsedOpenVpnStatus | null>;
+}
+export declare function shouldIgnoreStatusReadError(error: unknown): boolean;
+export declare function buildOpenVpnArgs(options: Pick<OpenVpnStartOptions, 'configPath' | 'authFilePath' | 'pidFilePath' | 'statusFilePath' | 'logFilePath'>): string[];
+export declare function parseOpenVpnStatus(raw: string): ParsedOpenVpnStatus;
+export declare function protocolToOpenVpnFileSuffix(protocol: Protocol): string;
+export declare function findOpenVpnProcesses(): Promise<OpenVpnProcessInfo[]>;
+export declare function terminateProcess(pid: number, signal?: NodeJS.Signals): Promise<boolean>;
+interface ProcessOutput {
+    stdout: string;
+    stderr: string;
+}
+interface ChildExit {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    error?: string;
+}
+export declare function formatInitializationFailure(options: {
+    lastLog?: string;
+    processOutput?: ProcessOutput | undefined;
+    childExit?: ChildExit | null;
+}): string;
+export declare function formatDiagnosticOutput(options: {
+    lastLog?: string;
+    processOutput?: ProcessOutput | undefined;
+    childExit?: ChildExit | null;
+}): string;
+export {};