chanjing-auth

Chanjing OAuth 認証

Chanjing プラットフォームのすべての機能（デジタルヒューマン、TTS、BGM、効果音）の認証を一元管理します。

使用する場面

• ユーザーが Chanjing プラットフォームに認証されているか確認する
• OAuth ログインの手順をユーザーに案内する
• 認証情報やトークンの問題をトラブルシューティングする
• CI/CD またはヘッドレス環境向けに認証を設定する

使用しない場面： Chanjing サービスへの実際の API 呼び出し → 機能固有のスキル（chanjing-digital-human など）に委任してください。

---

クイックスタート

# Check current auth status
npx framevideo auth status

# Check if authenticated (exit code)
npx framevideo auth status --check

# Get status as JSON
npx framevideo auth status --json

認証されていない場合は、以下の認証方法のいずれかを使用してください。

---

基本概念

OAuth CLI Web ログイン

標準的な認証フローです。

1. ユーザーが framevideo auth login を実行するか、Studio でログインをクリックします
2. CLI がブラウザーで Chanjing の認証ページを開きます
3. ユーザーがブラウザーで承認します
4. ブラウザーがローカルのコールバックサーバーにリダイレクトします
5. CLI がトークンを受け取り、認証情報ストアに保存します
6. これですべての Chanjing 機能がプラットフォームにアクセスできるようになります

認証情報の保存先

トークンは ~/.chanjing/credentials（CHANJING_CONFIG_DIR 環境変数に従います）の oauth ブロックに保存されます。

{
  "oauth": {
    "access_token": "...",
    "refresh_token": "...",
    "expires_at": 1234567890
  }
}

これらのトークンを読み取ったり、表示、ログ出力、コミットしたりしないでください。 packages/cli/src/auth/store.ts の共有認証ストア API を使用してください。

プラグイン API クライアント

すべての Chanjing API リクエストでは、Authorization: Bearer <access_token> ヘッダーを使用します。クライアントは以下を処理します。

• トークンの有効期限切れ時の更新
• 401 エラー時の自動再試行
• エラー報告

場所：packages/cli/src/tts/chanjingOpenapi.ts

---

認証方法

方法 1：インタラクティブログイン（推奨）

開発時やローカルでの使用向けです。

npx framevideo auth login

OAuth フローのためにブラウザーを開きます。ユーザーによる操作が必要です。

方法 2：Studio ログイン（エージェントに適しています）

エージェントで作業していて、OAuth 認証がない場合：

1. npx framevideo preview を起動するか、既存のプレビューサーバーを再利用します
2. ブラウザーで Studio プロジェクトの URL を開きます
3. デジタルヒューマン、音声、またはアカウントのパネルに移動します
4. ログインボタンをクリックして OAuth フローを開始します
5. ブラウザーで認証を完了します
6. npx framevideo auth status で確認します

CLI のみの案内よりもこちらが優れている理由：

• ユーザーが視覚的に状況を確認できます
• 自然なワークフローに組み込まれています
• エージェントがステータスエンドポイントをポーリングできます

方法 3：CI/CD またはヘッドレス環境

ブラウザーを使用しない自動化環境向けです。

1. インタラクティブログインセッションからリフレッシュトークンを取得します
2. CHANJING_REFRESH_TOKEN 環境変数を設定します
3. CLI がリフレッシュトークンを使用してアクセストークンを取得します

セキュリティ上の注意： リフレッシュトークンはシークレットとして扱ってください。安全なシークレット管理（GitHub Secrets、CI の Vault など）を使用してください。

---

認証情報がない場合の UX

エージェントが作成したワークフローで Chanjing の機能が必要なのに、認証がない場合：

プレビューが利用できる場合（推奨）：

1. npx framevideo preview を起動するか、既存のプレビューサーバーを再利用します
2. アプリ内ブラウザーで Studio プロジェクトの URL を開きます
3. Chanjing を必要とするパネル（デジタルヒューマン、音声、アカウント）に移動します
4. ログインをクリックして OAuth CLI Web ログインを開始します
5. ユーザーがブラウザーで認証を完了します
6. 認証状態を再確認してから、ワークフローを続行します

プレビューが利用できない場合：

CLI のみの案内に切り替えます。

npx framevideo auth login

その後、ワークフローを続行します。

禁止事項：

• ❌ プレビューが利用できる場合に、環境変数の案内だけで終わらせる
• ❌ 認証情報ストア以外にトークンを表示または保存する
• ❌ ~/.chanjing/credentials を手動で編集するようユーザーに依頼する
• ❌ 非推奨の app_id、secret_key、CHANJING_OPENAPI_ACCESS_TOKEN を使用する

---

Studio との連携

Studio では、プラグインルートを通じて認証状態の確認とログイン UI を利用できます。

認証ステータスエンドポイント

GET /api/projects/:id/chanjing/auth/status

以下が返されます。

{
  "authenticated": true,
  "user": {
    "id": "...",
    "name": "..."
  }
}

ユーザーに Studio へのログインを案内した後、認証状態のポーリングに使用します。

ログインボタン

以下で利用できます。

• デジタルヒューマンパネル（Studio → デジタルヒューマン → ログイン）
• 音声パネル（Studio → 音声 → ログイン）
• アカウント設定（Studio → 設定 → Chanjing アカウント）

いずれかのログインボタンをクリックすると、同じ OAuth CLI Web ログインフローが開始されます。

---

トラブルシューティング

「認証されていません」エラー

確認事項：

npx framevideo auth status

解決方法：

npx framevideo auth login

トークンの有効期限切れ

クライアントはトークンを自動的に更新します。更新に失敗した場合：

# Clear credentials and re-login
rm ~/.chanjing/credentials
npx framevideo auth login

「Invalid token」または401エラー

認証情報ストアが破損している可能性があります。

# Inspect (redacted output)
npx framevideo auth status --json

# Clear and re-login
rm ~/.chanjing/credentials
npx framevideo auth login

CI/CDの認証に失敗する場合

1. CHANJING_REFRESH_TOKEN が設定されていることを確認します
2. トークンの有効期限が切れていないことを確認します（リフレッシュトークンの有効期間は通常30～90日です）
3. 対話型セッションから新しいリフレッシュトークンを取得します

---

他のスキルとの連携

chanjing-digital-human

この認証を使用して、以下を行います。

• デジタルヒューマンと音声の一覧表示
• ウェブサイトプロジェクトの合成を送信
• タスクのステータスをポーリング
• 生成された動画をダウンロード

chanjing-media（予定）

この認証を使用して、以下を行います。

• BGMの一覧表示とダウンロード
• 効果音の一覧表示とダウンロード

framevideo-media

この認証は使用しません。 ローカルのKokoro TTSはオフラインで動作し、認証情報は不要です。

---

セキュリティのベストプラクティス

1. トークンを決して出力しない - ログ、エラーメッセージ、エージェントの応答のいずれにも出力しないでください
2. 認証情報ストアのAPIを使用する - ~/.chanjing/credentials を直接読み取らないでください
3. Gitにトークンを含めない - 認証情報ファイルを .gitignore に追加してください
4. CIのシークレットを安全に管理する - CHANJING_REFRESH_TOKEN の管理にはシークレット管理機能を使用してください
5. スタンドアロンスクリプトをコピーしない - 共有認証クライアントを再利用し、複製しないでください

---

検証

認証後、以下を実行します。

# Should show "authenticated: true"
npx framevideo auth status

# Should list available resources
npx framevideo chanjing music categories --json

両方が成功すれば、認証は正しく機能しています。

---

参考資料

• 認証ストアの実装：packages/cli/src/auth/store.ts
• プラグインAPIクライアント：packages/cli/src/tts/chanjingOpenapi.ts
• Studioの認証ルート：chanjing-digital-human スキルの references/studio-routes.md を参照してください