拡張機能開発者APIをお試しください

Chastify拡張機能を作成したり、iframe拡張機能ページをホストしたり、独自のバックエンドから開発者APIを呼び出したりする場合は、このガイドを使用してください。

このページは出発点です。どのモードを選択すべきか、最初に何に電話をかけるべきか、そして次にどこへ進むべきかが分かります。

ロック解除ブロッカー、定期的な必須アクション、報酬、罰則などの具体的な拡張機能の動作については、拡張機能 API の機能 を参照してください。

ヒント

自分の鍵だけを操作したいですか？

公開拡張機能を作成する必要がない場合は、外部 API とプログラム ページが最も簡単に始められる方法です。DEV トークンを作成し、シンプルな REST エンドポイントを呼び出すだけで済みます。拡張機能の設定、iframe、セッション管理は不要です。時間の追加/削除、フリーズ、タスク、デバイスコマンドなどに対応しています。

このAPIの用途

Extensions Developer API を使用すると、Chastify ロックセッション内で実行されるサードパーティ製の拡張機能エクスペリエンスを構築できます。

これを使えば、以下のことが可能です。

• セッションとロックのコンテキストを読み取ります（拡張機能の場合はsession.get、独自のロック自動化の場合は/api/apps/v1/session）。
• ロックセッションごとに拡張機能が所有するデータを読み取り（state.get）、バックエンドから書き込みます（PUT/PATCH /state）。
• 拡張機能が所有するイメージファイルを、Chastifyが管理するR2ストレージ（files.*）に保存します。
• ロックカードに拡張機能UIアクションを追加する（metadata.homeActions）
• 拡張機能が所有するロック解除ブロッカーを使用したゲートロック解除フロー（metadata.unlockBlockers）
• 信頼できるバックエンドからロック操作をトリガーする（時間の追加/削除、フリーズ/フリーズ解除、設定パッチ）
• タスクと衛生アクションをトリガーします（task.assign、task.start_timer、task.complete、hygienic_unlock.start）
• カウンター/ケイデンスサポート付きの定期的なアクションを送信
• サポートされているデバイスコマンドが利用可能な場合は送信します。
• 履歴をロックするために、カスタム拡張機能のログエントリを書き込む

あなたが作れるもの

適切な機能セットは、信頼がどこに存在するかによって決まります。

フロントエンド専用のiframe拡張機能を使用すると、信頼できるロックの変更を必要としないUI優先のエクスペリエンスを構築できます。

• 拡張機能の設定を収集するセットアップページ
• セッションコンテキストを読み取るダッシュボード
• セッション状態を読み取り、検証済みの進行状況をバックエンド経由で送信するパズル、チェックリスト、またはゲームのUI
• Chastifyによって既に保存されている拡張ファイルを読み取るメディアベースのフロー
• iframeを意図を持って開くホームアクションエントリポイント

サーバーベースの拡張機能は、バックエンドが特権APIを呼び出す前に結果を検証するため、ロックに影響を与える機能を構築できます。

• ロック解除条件付きのタスクまたは習慣システム
• 日次または週次の要件と、期限を過ぎた場合の罰則が定められている。
• ロック時間の変更によって成功を報い、失敗を罰するゲーム
• サーバー側検証後にロック解除ブロッカーをクリアする検証フロー
• サポートされているデバイスコマンドを使用したデバイス制御コンパニオンフロー
• iframe の外で拡張機能の状態を保持する Webhook/データベース ワークフロー

外部プログラムは、ご自身のアクティブなロックを個人的に自動化するためのものです。

• ローカルスクリプト
• パーソナルダッシュボード
• ユーザー全体でDEVキーを使用する自動化ツール

モードを選択してください

以下のモードからいずれかを選択してください。

1. Hosted iframe extension: Cloudflare Pagesまたは同様のサービスで静的なiframe UIをホストします。セットアップ、セッションコンテキスト、および安全な読み取りにはブリッジを使用してください。状態の書き込み、報酬、罰則、ロック解除の完了、または信頼できる要件の進捗状況には、このモードのみを使用しないでください。
2. Server-backed extension: iframe UI をホストし、独自のバックエンドを実行します。iframe は起動時の mainToken をバックエンドに送信し、バックエンドはアプリスコープの開発者 API キーと x-chastify-main-token を使用して Chastify 拡張 API を呼び出します。このモードは、特権アクション、ブロッカーのロック解除、信頼できる進捗状況、報酬、罰則、Webhook、および外部データベースに使用します。
3. External API & Programs: スクリプト、ローカルプログラム、または自身のアクティブなロックを制御する自動化には、ユーザー全体で共通の DEV キーを使用します。これは、拡張機能をインストールするサードパーティユーザーには適したモードではありません。

迅速なテストを行う場合は、UIと安全な読み取りにはiframeモードから始めてください。状態の書き込み、信頼できる報酬、時間の変更、スケジュールされた要件の進捗状況、またはロック解除ブロッカーの完了を実装する前に、バックエンドを追加してください。

注意

iframeコードは信頼境界ではありません。ハッシュペイロードや起動トークンなど、iframeから見えるものはすべて、ユーザーが検査したり、再生したりすることができます。

最初の10分間（iframeモード）

1. Chastify iframe から location.hash ペイロードを読み取ります。
2. session.get のブリッジ要求を作成します。
3. type: "chastify:ext:resp"とok: trueで応答を確認してください。
4. テスト状態はstate.getで読み取られます。
5. iframeがUI上で正しく動作するように、自動サイズ変更機能とテーマサポートを追加します。

テーマサポートは、本番環境に対応したiframeの一部です。Chastifyは起動ハッシュにuiの値を渡して、iframeが開いている間、リアルタイムのテーマ更新を送信します。iframeテーマ設定で、ライト/ダークの例とコントラストセーフなTailwindパターンを参照してください。

必要なペイロード値:

• bridge.nonce
• bridge.parentOrigin
• sessionId
• lockId

ブリッジリクエストの例：

{
  "type": "chastify:ext:req",
  "v": 1,
  "id": "request-id", // unique id per request
  "nonce": "nonce-from-hash",
  "action": "session.get",
  "payload": {}
}

橋梁応答の例：

{
  "type": "chastify:ext:resp",
  "v": 1,
  "id": "request-id",
  "ok": true,
  "data": {}
}

まず最初に学ぶべき重要な行動

• session.get
• state.get
  ロックセッションの拡張機能が所有するJSONストレージを読み取ります。開発者API認証情報を使用して、バックエンドから状態を書き込みます。
• files.capabilities, files.list, files.get パズル画像や生成されたプレビューなどのバイナリメディアには、ファイルストレージの読み取りを使用します。バックエンドで書き込まれた状態にはファイルIDを保存し、署名付きURLをfiles.getで更新します。
• metadata.get ロックセッション解除ブロッカーと拡張カードホームアクション/インテントを読み取ります。
• regularActions.get

セッションの状態書き込み、通常のアクション送信、実行時ファイルのアップロード/削除、時刻変更、ロック解除ブロッカーの更新、タスク完了、衛生管理の開始、デバイスコマンドなどのセッション変更は、開発者APIキーを使用してバックエンドから呼び出す必要があります。これらのアクションには、ブラウザのiframeコードは信頼されません。

完全なAPI URL（サポート対象）

基本ドメイン: https://chastify.net

拡張セッションAPI（/api/extensions/*）

これらのルートはアクセスモードが異なります。/api/extensions/* のサーフェス全体を iframe セーフとして扱わないでください。

安全なiframeブリッジルートは、postMessageブリッジ要求の後、Chastify親を経由してルーティングされます。

• GET https://chastify.net/api/extensions/sessions/:sessionId
• GET https://chastify.net/api/extensions/sessions/:sessionId/state
• GET https://chastify.net/api/extensions/sessions/:sessionId/metadata
• GET https://chastify.net/api/extensions/sessions/:sessionId/regular-actions
• GET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilities
• GET https://chastify.net/api/extensions/sessions/:sessionId/files
• GET https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId

バックエンド専用のインストール済み拡張機能ルートには、アプリスコープの開発者APIキーとiframe起動トークンが必要です。

Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH

備考

この2トークンモデルでは、バックエンドリクエストを拡張機能開発者（Authorization）と現在開いている拡張機能セッション（x-chastify-main-token）の両方に紐付けます。

• PATCH https://chastify.net/api/extensions/sessions/:sessionId/metadata
• PUT https://chastify.net/api/extensions/sessions/:sessionId/state
• PATCH https://chastify.net/api/extensions/sessions/:sessionId/state
• PATCH https://chastify.net/api/extensions/sessions/:sessionId/regular-actions/config
• POST https://chastify.net/api/extensions/sessions/:sessionId/regular-actions
• POST https://chastify.net/api/extensions/sessions/:sessionId/files
• DELETE https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId
• POST https://chastify.net/api/extensions/sessions/:sessionId/logs/custom
• POST https://chastify.net/api/extensions/sessions/:sessionId/notifications/custom
• POST https://chastify.net/api/extensions/sessions/:sessionId/device-command
• POST https://chastify.net/api/extensions/sessions/:sessionId/action
• POST https://chastify.net/api/extensions/sessions/:sessionId/requirements/progress

バックエンドトークンAPI（/api/apps/v1/*）

Authorization: Bearer <user-wide DEV token>を使用してください。これらのエンドポイントはトークン所有者自身の有効なロックセッションを管理するものであり、インストール済みのサードパーティ製拡張機能セッションではなく、外部APIスクリプト/プログラムを対象としています。

• GET https://chastify.net/api/apps/v1/session
• GET https://chastify.net/api/apps/v1/state
• PUT https://chastify.net/api/apps/v1/state
• PATCH https://chastify.net/api/apps/v1/state
• GET https://chastify.net/api/apps/v1/metadata
• PATCH https://chastify.net/api/apps/v1/metadata
• POST https://chastify.net/api/apps/v1/action
• POST https://chastify.net/api/apps/v1/lock/apply-time
• POST https://chastify.net/api/apps/v1/lock/freeze
• POST https://chastify.net/api/apps/v1/lock/unfreeze
• POST https://chastify.net/api/apps/v1/logs/custom

iframeブリッジコマンド

ブリッジコマンドのペイロードはiframe（chastify:ext:req）によって送信され、Chastifyの親プロセスによってルーティングされます。ブリッジは意図的に安全なセッションUI操作のみに限定されています。

• session.get -> GET https://chastify.net/api/extensions/sessions/:sessionId
• state.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/state
• files.capabilities -> GET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilities
• files.list -> GET https://chastify.net/api/extensions/sessions/:sessionId/files
• files.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId と { "fileId": "file_record_id" }
• metadata.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/metadata
• regularActions.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/regular-actions

セッション変更エンドポイントは、iframeブリッジコマンドではなく、バックエンドAPIへの直接呼び出しです。これには、状態書き込み、通常のアクション送信、実行時ファイルのアップロード/削除などが含まれます。これは、iframeコードはユーザーが制御できるためです。

バックエンドセッションAPIの例

バックエンドは、インストール済み拡張機能の特権呼び出しに対して、以下の2つのヘッダーを送信する必要があります。

Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH

バックエンドアクションの例：

• metadata.patch -> PATCH /api/extensions/sessions/:sessionId/metadata
• regularActions.submit -> POST /api/extensions/sessions/:sessionId/regular-actions
• files.upload -> POST /api/extensions/sessions/:sessionId/files
• files.delete -> DELETE /api/extensions/sessions/:sessionId/files/:fileId
• lock.applyTime -> POST /api/extensions/sessions/:sessionId/action と { "name": "add_time", "params": <deltaSeconds> }
• lock.freeze -> POST /api/extensions/sessions/:sessionId/action と { "name": "freeze", "params": { "durationSeconds": 900 } }
• lock.unfreeze -> POST /api/extensions/sessions/:sessionId/action と { "name": "unfreeze", "params": {} }
• lock.settings.patch -> POST /api/extensions/sessions/:sessionId/action と { "name": "settings.patch", "params": { ... } }
• task.assign -> POST /api/extensions/sessions/:sessionId/action
• task.start_timer -> POST /api/extensions/sessions/:sessionId/action と { "name": "task.start_timer", "params": {} }
• task.complete -> POST /api/extensions/sessions/:sessionId/action と { "name": "task.complete", "params": { "successful": true } }
• hygienic_unlock.start -> POST /api/extensions/sessions/:sessionId/action と { "name": "hygienic_unlock.start", "params": { "durationSeconds": 900 } }
• pillory.end -> POST /api/extensions/sessions/:sessionId/action と { "name": "pillory.end", "params": {} }
• device.command -> POST /api/extensions/sessions/:sessionId/device-command
• logs.custom -> POST /api/extensions/sessions/:sessionId/logs/custom
• notifications.custom -> POST /api/extensions/sessions/:sessionId/notifications/custom
• requirements.progress -> POST /api/extensions/sessions/:sessionId/requirements/progress

トークン、スコープ、失効、および監査動作

適切な信頼境界には、適切なトークンを使用してください。

警告

開発者APIキーは機密情報です。ブラウザコードに漏洩した場合は、直ちにキーを無効化し、バックエンドの環境変数を更新してください。

iframe起動トークン（mainToken）

• ユーザーがインストール済みの拡張機能ページを開いた際に、iframeハッシュに含まれて配信されます。
• ブラウザ上で表示されるように設計されています。開いている拡張機能セッションを識別するためのものであり、バックエンドの秘密情報ではありません。
• 有効期限は短めです。現在の起動トークンは10時間後に期限切れになります。拡張機能ページを再度開いて更新してください。
• バックエンドがインストール済みの拡張機能セッションルートを呼び出す際に、x-chastify-main-token として必須となります。これにより、Chastify はバックエンドのリクエストを拡張機能を開いたユーザー/セッションにバインドできます。
• 時間変更の承認、ブロッカー完了のロック解除、タスク完了、デバイスコマンド、ランタイムアップロード/削除、カスタムログ、またはカスタム通知を単独で使用してはなりません。

アプリスコープの開発者APIキー

• ある拡張機能アプリの開発者UIから作成されました。
• バックエンド専用のシークレットです。iframeのJavaScript、モバイルアプリのバンドル、静的ホスティングの設定、ブラウザで読み取れるログには絶対に含めないでください。
• Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEYおよびx-chastify-main-tokenと併用します。
• インストール済み拡張機能のセッションAPIは、拡張機能アプリと起動トークンに一致するセッションに対してのみ呼び出すことができます。
• 自動的に期限切れになることはありません。漏洩した場合は直ちに無効化し、バックエンドの環境変数を更新してください。

ユーザー共通の開発者APIキー

• 拡張機能アプリを選択せず​​に、開発者UIから作成されました。
• /api/apps/v1/* のバックエンド専用シークレット。
• キー所有者自身の現在および将来のアクティブなロックセッションを制御します。
• インストール済みのサードパーティ製拡張機能のバックエンド認証情報として使用することはできません。

取り消し

• 失効した開発者APIキーは、新規リクエストの承認を停止します。
• 失効したキーは、開発者UIから完全に削除できます。
• 新規のiframe起動には、新しい起動トークンが発行されます。mainTokenを長期的な認証情報として保存しないでください。

業務範囲と役割

• 拡張機能アプリのスコープは、アプリが要求できる内容を定義します。
• 安全な iframe ブリッジ呼び出しは、UI のブートストラップ、セッションの読み取り、拡張機能が所有する状態、メタデータの読み取り、通常のアクションの読み取り、およびファイルの読み取りに限定されます。
• 特権付きインストール済みセッションの変更には、拡張機能が一致するスコープを持っている場合でも、バックエンドの認証情報が必要です。
• 役割に応じた操作は、起動が着用者またはキーホルダーのどちらに属するかに基づいて拒否される場合があります。

監査と制限

• 開発者APIキーの最終使用メタデータは、キーが使用された際に更新されます。
• 特権アクションのルートはレート制限があり、誤った認証情報が使用された場合は、server_credentials_required や user_wide_dev_key_required などの明示的なエラーを返します。
• カスタムログには、目に見えるロック履歴エントリが書き込まれます。
• カスタム通知は、要求されたターゲットに対してChastify通知を作成します。
• 特権拡張機能のすべての変更に対する完全な監査カバレッジは、本番環境の強化項目として追跡されます。

サポートされているコマンド値

/api/extensions/sessions/:sessionId/actionと/api/apps/v1/action

name は以下をサポートしています:

• add_time
• remove_time
• freeze
• pillory
• unfreeze
• toggle_freeze
• settings.patch
• task.assign
• task.start_timer
• task.complete
• hygienic_unlock.start
• pillory.end

行動制約​​:

• タスク操作を実行するには、ロック上でタスク拡張機能/モジュールが有効になっている必要があります。
• hygienic_unlock.startでは、衛生的な開封機能が有効になっており、かつアクティブな衛生セッションがないことが条件となります。

session.get ロックデータヘルパー

session.get / GET /api/apps/v1/session には、ルールエンジン向けに実行時に扱いやすいブール値、数値、文字列を含む lockData も含まれています。

例：

• ブール値: frozen、unlockable、trusted、taskAssigned (TaskRun が開いている場合は true)
• 番号: timeLockedSeconds、timeRemainingSeconds、maxTimeRemainingSeconds、taskPoints
• 文字列: lockTitle、着用者/キーホルダーのプロファイルフィールド

プライバシー：

• wearerLastSeenTimestampとkeyholderLastSeenTimestampは、ユーザーがオンライン状態（showOnlineStatus === false）を無効にした場合、nullになります。

デバイスコマンド

拡張セッションでは、セッションベースのエンドポイントを使用できます。

POST /api/extensions/sessions/:sessionId/device-command

DEVトークンを持つ外部プログラムは、よりシンプルなv1エンドポイントを使用できます（セッションIDは不要です）。

POST /api/apps/v1/device-command

どちらも同じリクエストボディを受け入れ、同じレスポンスを返します。詳細については、外部APIとプログラムを参照してください。

設定ページ（オプション、推奨）

拡張機能にセットアップ/設定UIがある場合：

1. 親はchastify:ext:setup:init（保存された設定＋コンテキスト）を送信します。
2. セットアップiframeはchastify:ext:setup:configというエラーメッセージを含む更新情報を返します。
3. 親はchastify:ext:setup:get_configを使用して現在の設定を要求できます。

バックエンドトークンフロー（サーバーサイド呼び出しが必要な場合）

シンプルなスクリプトや外部プログラムの場合は、開発者APIページからユーザー全体で使用できるDEVトークンを使用してください。外部APIとプログラムを参照してください。

拡張機能のiframeモードでのデフォルトフロー：

1. Chastifyは、アクティブな拡張機能セッションに対して、ブラウザに表示される一時的な起動トークンを発行します。
2. 起動トークンは、mainTokenとしてiframeハッシュペイロードに埋め込まれます。
3. あなたのiframeはmainTokenをバックエンドに転送します。
4. バックエンドは、Authorization: Bearer <app-scoped Developer API key>とx-chastify-main-token: <mainToken>を使用してhttps://chastify.net/api/extensions/sessions/:sessionId/*を呼び出します。

開発者APIキーをiframe/ブラウザコードに送信しないでください。mainTokenは開いている拡張機能セッションを識別するものであり、バックエンドシークレットではないため、単独で特権操作に使用することはできません。

手動フォールバック:

• ファーストパーティUIからiframe起動トークンを明示的に取得/回転させる必要がある場合は、GET https://chastify.net/api/extensions/sessions/:sessionId/authを呼び出してください。

Chastify ページが開いていない間にスケジュールされたジョブ、Webhook、または自動化が必要な場合は、バックエンド モードを使用してください。現在インストールされている拡張機能のセッション変更には、有効な 10 時間有効の iframe 起動トークンが引き続き必要となるため、バックグラウンド実行用に設計されたファーストパーティ/組み込みのサーバー フローを使用していない限り、無人ジョブは保留中の証明を保存し、次の有効な起動時に送信する必要があります。

備考

完全に無人で運用するには、組み込みのサーバーフローまたはファーストパーティサーバーフローを使用するか、明示的なバックグラウンド拡張機能の許可をお待ちください。アプリスコープのセッションAPIは現在、起動トークンに依存しています。

バックエンド vs Cloudflare Pages (サーバーなし)

Cloudflare Pages（バックエンドサーバーなし）を使用するべきケース：

• 最も簡単で安価なセットアップ（無料でホスティングできるもの）を希望する。
• ユーザーが拡張機能ページをアクティブに閲覧している間だけ、UI主導のアクションが必要になります。
• サーバーに永続的に保存される拡張状態への書き込みは必要ありません。
• あなたはプロトタイプを作成したり、軽量な拡張機能を迅速に構築したりしています。

ローカルテストの例（PowerShell）：

cloudflared tunnel --url http://localhost:5174

テスト中は、生成された公開URLをiframeのURLとして使用してください。

バックエンドサーバーを使用するべき状況：

• スケジュールされたジョブ（cronのような動作）が必要です。
• ウェブフックまたは外部連携が必要です。
• 拡張機能ページに誰もアクセスしていないときは、自動化/バックグラウンド処理が必要です。
• 継続的に実行される、サーバー制御型のワークフローが必要です。

バックエンドがない場合の重要な制限事項：

• バックグラウンドでの実行はありません。 拡張機能は、ユーザーが拡張機能のiframeを開いて操作している間のみ、アクションを実行できます。

よくある問題

• 403 extension_not_enabled: このロックでは拡張機能が有効になっていません。
• 409 lock_ended: ロックが無効になりました。
• 429: レート制限に達しました。
• iframe に応答がありません: nonce、targetOrigin (parentOrigin)、および許可されたオリジンを確認してください。

次のガイド

• iframe クイックスタート
• iframeのテーマ設定
• APIの例
• 外部APIとプログラム
• ウェブフック
• レート制限
• トラブルシューティング