wegoft/bellwire

bellwire は何をしますか？

リポジトリの状態とイベントを、ユーザーのBellwireカード、受信箱、iPhoneに接続します。新しいプロジェクトはデフォルトでプライベートになります。Bellwireは不透明なウェイクのみを中継し、電話はユーザーのHTTPSサービスから直接コンテンツをフェッチします。ホスト型ストレージはオプトインであり、アプリでの承認が必要です。

ワークフロー

1. リポジトリ、そのシークレット管理の慣行、テスト、およびイベントをトリガーする正確な成功または失敗状態を調査します。

2. コードでは答えられない製品上の決定事項のみを明確にします。通知頻度、機密値、および高優先度の割り込みが正当化されるかどうか。

3. BELLWIRE_AGENT_TOKEN が追跡ファイルの外部で利用可能であることを確認します。不足している場合は、iOSアプリに表示されている6桁のコードをユーザーに尋ね、以下を実行します。

   bellwire_secret_dir="$(mktemp -d)"
   node <skill-dir>/scripts/bellwire.mjs bind \
     --code 123456 \
     --name "Codex on Mac" \
     --secret-output "$bellwire_secret_dir/agent-token"
   

   CLIはモード 0600 でファイルを作成し、トークンを決して表示しません。表示せずにユーザーの承認されたシークレットストアにインポートし、一時ファイルを削除します。決してコミットしないでください。

4. list-projects を実行し、Bellwireプロジェクトを作成するか再利用します。別のプロジェクトを作成する前に、既存の設定を検索してください。配信モードを変更するためだけに2番目のプロジェクトを作成しないでください。

5. ユーザーが明示的にBellwire Cloudにイベント、受信箱、およびSurfaceコンテンツを保存したい場合を除き、プロジェクトをプライベートに保ちます。

   • Private: 署名付きDirect v2通知、受信箱、およびSurfaceエンドポイントを実装し、デバイスキー、ワンタイムnonce、不透明参照の送信箱、および24時間の参照有効期限をユーザーの実際のデータベースに永続化します。direct-connections.md を参照してください。
   • Hosted: request-mode-change を使用して変更を要求し、署名済みユーザーがBellwireで承認するまで停止します。その後、Hostedスキーマ、Surface、およびインジェストトークンを作成します。

6. Privateランタイム配信の場合、ウェイク専用トークンを作成し、ソースアプリの実際のシークレットマネージャーに保存し、ソーストランザクションと送信箱レコードのコミット後、ベストエフォートで private-wakes を呼び出します。Bellwireはタイトル、本文、データ、ロゴURL、プロジェクト名、サービスホスト名を決して受信してはなりません。

7. 表示プリミティブを選択します。

   • Surface: その場で更新される現在の状態。surfaces.md を参照してください。
   • Inboxイベント: 永続的な履歴、完了、失敗、復旧、または決定境界。Privateモードではユーザーのサービスに残ります。Hostedモードでは event-spec.md を使用します。

8. 安定したSurfaceキーと不透明なランダム参照を使用します。同じウェイクまたはHosted書き込みの再試行には、安定した冪等性キーを再利用します。

9. 最も小さな信頼できるトリガーポイントを変更します。基盤となるビジネス操作がコミットされた後にのみ送信します。

   • アプリケーションがビジネス操作を所有している場合は、コミット後の直接Bellwire呼び出しを優先します。
   • 支払い、コマース、デプロイメント、または自動化プロバイダーが信頼できる情報源である場合は、webhooks.md を読み、プロバイダー固有のウェブフックアダプターを追加します。

10. 署名、タイムスタンプ、不明なキー、改ざんされたターゲット、およびアトミックnonceリプレイの単体テストを実行し、その後 conformance-direct.mjs を実行します。データベースがアトミックにnonceを消費できない場合は、停止して安全性の問題を説明します。

11. リポジトリの既存のテストと、フォーカスされたトリガーテストを実行します。Bellwireを通すためにビジネステストを弱めないでください。

12. ソース側アダプターとそのシークレットを、リポジトリの実際の信頼できる情報源を通じて永続化およびデプロイします。

13. 1つの実際のソース操作を完了し、production-verification.md を使用して、送信箱、ウェイクの受付、配信、署名済み電話フェッチ、および表示結果を検証します。手動によるウェイクは本番検証ではありません。

統合ステータス

進捗状況および最終報告では、以下の正確な境界を使用します。

• 設定済み: Bellwireプロジェクト、スキーマ、トークン、Surface、またはテストイベントが存在します。これは本番統合ではありません。
• 統合済み、本番検証待ち: ソース側アダプターコード、ランタイムシークレット、フォーカスされたテスト、およびデプロイメントは存在しますが、実際のソース操作がパスを完了していません。
• 本番検証済み: 実際のビジネス操作が期待されるイベントまたはSurfaceを作成し、配信が確認され、主張されたデバイス表示がユーザーによって確認されました。

send-test、手動で更新されたSurface、またはシークレット作成を実際の本番統合として説明しないでください。

コマンド

API操作には scripts/bellwire.mjs を使用します。デフォルトでは公式のホスト型APIに接続し、セルフホストインストールには BELLWIRE_API_URL を受け入れます。

bellwire_secret_dir="$(mktemp -d)"
node <skill-dir>/scripts/bellwire.mjs list-projects
node <skill-dir>/scripts/bellwire.mjs create-project --name "VideoSays" --logo-url "https://videosays.com/logo.png"
node <skill-dir>/scripts/bellwire.mjs create-wake-token --project <id> --name production --secret-output "$bellwire_secret_dir/wake-token"
node <skill-dir>/scripts/bellwire.mjs generate-reference
node <skill-dir>/scripts/bellwire.mjs send-wake --project <id> --reference <opaque-ref> --idempotency-key <stable-key>
node <skill-dir>/scripts/bellwire.mjs request-mode-change --project <id> --to hosted
node <skill-dir>/scripts/bellwire.mjs update-project --project <id> --logo-url "https://cdn.example.com/logo.png"
node <skill-dir>/scripts/bellwire.mjs set-project-order --project <id> --order 10
node <skill-dir>/scripts/bellwire.mjs delete-project --project <id>
node <skill-dir>/scripts/bellwire.mjs create-schema --project <id> --file event-spec.json
node <skill-dir>/scripts/bellwire.mjs create-token --project <id> --name production --secret-output "$bellwire_secret_dir/ingest-token"
node <skill-dir>/scripts/bellwire.mjs upsert-surface --project <id> --key prod-api --file surface.json
node <skill-dir>/scripts/bellwire.mjs list-surfaces --project <id>
node <skill-dir>/scripts/bellwire.mjs list-direct-recoveries
node <skill-dir>/scripts/bellwire.mjs set-surface-order --project <id> --key prod-api --order 20
node <skill-dir>/scripts/bellwire.mjs send-test --project <id> --file test-event.json
node <skill-dir>/scripts/bellwire.mjs event --event <event-id>
node <skill-dir>/scripts/bellwire.mjs health --project <id>
node <skill-dir>/scripts/bellwire.mjs publish-direct-connection \
  --device-key-id <id> \
  --agreement-public-key <base64> \
  --file direct-connection.json
node <skill-dir>/scripts/conformance-direct.mjs \
  --manifest direct-connection.json \
  --device-key-id <id> \
  --reference <known-test-reference>

検証、失効、削除、および暗号化コマンドについては node <skill-dir>/scripts/bellwire.mjs --help を実行してください。シークレットを返すコマンドは --secret-output が必要です。トークンをチャットやコマンド出力に読み取らないでください。

delete-project は永続的であり、プロジェクトのスキーマ、トークン、イベント、配信、およびライブSurfaceにカスケードします。正確なプロジェクトIDを確認し、実行する前に明示的なユーザーの意図を必要とします。

機械可読な非シークレット出力には --json を使用します。別の操作を追加したり、エラーレスポンスを診断したりする場合は api.md を参照してください。

アダプタールーティング

• Node.js、Cloudflare Worker、Shell、およびGitHub Actionsのパターンについては adapters.md を参照してください。
• Stripeのような支払いイベントや、Bellwireを更新する前のサードパーティコールバックを受信する場合は webhooks.md を参照してください。
• プロジェクトの既存のHTTPクライアントを優先してください。1回のリクエストのためにSDK依存関係を追加しないでください。
• イベント送信を境界のある副作用として扱います。タイムアウトを設定し、ペイロードのログ記録を避け、通知の失敗がビジネス操作に影響を与える可能性があるかどうかを明示的に決定します。デフォルトはビジネス操作成功後のベストエフォートです。
• トークン値を生成された差分、テストスナップショット、CIログ、エラーテレメトリから排除します。

プライベートルール

• 各参照に対して少なくとも128ランダムビットを生成し、22～200のURLセーフ文字としてエンコードします。注文、メール、タスク、顧客、タイムスタンプから派生させないでください。
• ウェイクを送信する前に、通知詳細をデータベースバックアップの送信箱に書き込みます。参照は最大24時間で期限切れにします。
• ウェイク呼び出しはコミット後、境界がありベストエフォートです。Bellwireが利用できないために実際のビジネス操作をロールバックしないでください。
• MONTHLY_SIGNAL_LIMIT_REACHED は、返されたUTCリセット時間またはアップグレードまで終端状態です。ループや再試行はしないでください。
• プライベート詳細と受信箱の応答はユーザーのサービスから送信され、電話で最大30日間キャッシュされる場合があります。Bellwire Cloudはそれらを受信しません。

ホスト型イベントルール

• payment.success、deployment.failed、agent.waiting などの小文字のドット区切り名を使用します。
• 受信箱、通知、ディープリンク、または診断に必要なフィールドのみを含めます。
• 通知テンプレート内で機密フィールドを参照しないでください。APIはそれを拒否します。
• ホスト型の冪等性には、注文ID、デプロイメントID、タスクID、またはランIDを使用します。これらの識別子をプライベート参照として公開しないでください。
• 高頻度の進捗イベントは避けてください。完了、失敗、復旧、および決定が必要な境界を優先します。
• priority: high を要求する前に、明示的なユーザーの承認を求めてください。

Surfaceルール

• sales-today、prod-api、nightly-backup などの意味のある安定したキーを再利用します。
• 定期的な更新中は、割り当てられた displayOrder を保持します。ユーザーがカードの並べ替えを明示的に要求した場合にのみ変更します。
• 表示可能な値を送信します。たとえば、ソースシステムで収益を計算し ¥2,430 を送信します。Bellwireは生のイベントからビジネス集計を推測しません。
• プライベートまたは顧客由来のメトリクスの場合、署名付きBellwire Directエンドポイントを優先して、カードペイロードがBellwireストレージに入らないようにします。
• サポートされているネイティブタイプのいずれかを選択します。HTML、JavaScript、Swift、CSS、または任意のレンダリング指示を埋め込まないでください。
• 頻繁な進捗とメトリクスの更新にはSurfaceを優先し、イベント受信箱をあふれさせないようにします。
• open_url アクションは、送信先がユーザーにとって期待され安全である場合にのみ使用します。
• プロジェクトのロゴは、5MB以下の公開HTTPS画像である必要があります。Bellwireはそれらをネイティブアバターと拡張リッチ通知で使用し、画像がないかダウンロードできない場合はプロジェクトのモノグラムにフォールバックします。

検証と復旧

セットアップに失敗した場合は、troubleshooting.md を参照してください。以下の順序で確認します。

1. API到達可能性と管理トークンのスコープ。
2. プロジェクトIDとアクティブなスキーマバージョン。
3. 実際のランタイムでのシークレットの可用性。
4. ペイロードのタイプと必須フィールド。
5. 安定した Idempotency-Key の動作。
6. デプロイされたバージョンと実際のソース操作におけるソースアダプターの存在。
7. イベント詳細、Surface状態、および配信ステータス。
8. iOS通知の許可、デバイス登録、およびサンドボックスと本番APNs環境。

ユーザーが要求した場合、または侵害が疑われる場合を除き、動作中のトークンをローテーション、失効、または置き換えないでください。