tollbooth-authority

Tollbooth Authority

インフラを構築した機関です。

このプロジェクトの比喩は、Norton Juster著、Jules Feiffer挿絵の The Phantom Tollbooth （1961）への敬意を込めて描かれています。Milo、Tock、Tollbooth、Dictionopolis、Digitopolisは、Juster氏の並外れた想像力から生まれたものです。私たちが構築したのは、決済インフラだけです。

---

Turnpike Authority

すべてのターンパイクには、管理機関があります。料金所を運営する事業者でも、料金を支払うドライバーでもありません。コンクリートを流し込み、標識を立て、発注書に承認印を押した機関です。

Tollbooth Authorityは、Lightning経済圏のMassachusetts Turnpike Authorityです。料金所は運営しません。事業者のBTCPayストアには触れません。ユーザーの決済データを見ることもありません。役割はよりシンプルで、より重要です。

• ターンパイクで料金所を運営したい事業者を登録します。
• わずかな認定手数料を徴収します。これは各料金の2％、最低10 satsで、Lightning経由で前払いされます。
• 発注書に承認印を押します。Schnorr署名付きのNostrイベント証明書（kind 30079）により、事業者が料金を徴収する前に手数料を支払ったことを証明します。
• 料金そのものには触れません。事業者がユーザーから直接徴収します。

Authorityの署名は、ターンパイクが正規のものであることを証明します。承認印がなければ、料金所は開きません。

アーキテクチャ

v0.9.0以降、このAuthorityはtollbooth-dpycホイールを利用する薄いコンシューマーです。オンボーディングステートマシン、Schnorr証明書署名機能、リプレイトラッカー、Neonテナントプロビジョナー、Authorityのツール一式など、汎用的なAuthorityコードはすべて、ホイールの tollbooth.authorityパッケージにあります。このリポジトリのserver.pyが提供するのは、アクター固有の設定だけです。具体的には、ID名、人が読める説明、OperatorRuntimeの構築、そして2つのregister_*_tools(mcp, runtime)呼び出しです。

# The entire server.py, distilled
from fastmcp import FastMCP
from tollbooth.authority import (
    AUTHORITY_TOOL_REGISTRY,
    OPERATOR_CREDENTIAL_TEMPLATE,
    register_authority_tools,
)
from tollbooth.runtime import OperatorRuntime, register_standard_tools
from tollbooth.tool_identity import STANDARD_IDENTITIES

mcp = FastMCP("tollbooth-authority", instructions="…")
runtime = OperatorRuntime(
    tool_registry={**STANDARD_IDENTITIES, **AUTHORITY_TOOL_REGISTRY},
    vault_source="env",               # Authority arrives with its own Neon
    purchase_mode="auto",             # derive direct/certified from the registry chain
    service_name="Tollbooth Authority",
    ots_enabled=True,
    operator_credential_template=OPERATOR_CREDENTIAL_TEMPLATE,
)
register_standard_tools(mcp, "authority", runtime, ...)
register_authority_tools(mcp, runtime)

リファクタリングの履歴：

• v0.5.0ではOperatorRuntimeを導入し、標準ツールをホイールに委譲しました。約1,900行から約970行になりました。
• v0.19.0では、名前を指定するすべてのツールで証明を必須とし、検証するようにしました。ローカルの_verify_operator_proofヘルパーは、ホイール側のtollbooth.identity_proof.require_proofに移されました。
• v0.21.0（ホイール）では、6つのサポートモジュール（onboarding、nostr_signing、replay、tenant_provisioner、role_migration、settings）を、フォークしたAuthorityコードからtollbooth.authority.*に移しました。
• v0.22.0（ホイール）では、10個のAuthorityの@tool定義をregister_authority_tools(mcp, runtime)に移しました。
• v0.9.0（今回のリリース）では、不要になった8つのモジュールを削除し、server.pyを約970行から約100行に縮小しました。NorthAmericaとNewEnglandも、それぞれの0.4.0リリースで同様の変更を行いました。

3者間プロトコル

Tollboothエコシステムは、3つのリポジトリにまたがる3者間プロトコルです。

リポジトリ	役割
tollbooth-authority（このリポジトリ）	機関 — 手数料の徴収、Schnorr署名、発注書の認定
tollbooth-dpyc	料金所 — 事業者側のクレジット台帳、BTCPayクライアント、ツールの利用制御
thebrain-mcp	最初の都市 — Tollboothを利用するリファレンスMCPサーバー

DPYC フェデレーションの全容

上記の三者間プロトコルが中核ですが、Authority は、すべて同じ tollbooth-dpyc SDK を基盤とする、独立した MCP サービスのより広範なフェデレーションを認定します。

リポジトリ	役割
tollbooth-dpyc	共有 SDK — 暗号、ボールト、認証、価格設定、監査
dpyc-community	ガバナンスレジストリ — members/read-only-lookup-cache.json、GOVERNANCE.md、CI 検証
dpyc-oracle	無料のコミュニティコンシェルジュ — メンバーシップ、ガバナンス、オンボーディングに関する回答
tollbooth-authority	このリポジトリ — 認定基盤、Schnorr 証明書、手数料台帳
tollbooth-sample	新しい運営者向けのリファレンステンプレート
tollbooth-pricing-studio	価格設定エディター — ネイティブ iOS、Nostr DM
cypher-mcp	有料のグラフ回答 — Neo4j/AuraDB 上で名前付き Cypher を実行
schwab-mcp	Charles Schwab の証券口座データ
thebrain-mcp	TheBrain のナレッジグラフへのアクセス
excalibur-mcp	X/Twitter への投稿
taxsort-mcp	税務書類の仕分け＋分類
optionality-mcp	オプション分析
goodearth-mcp	小規模農場向けの気候分析
beesknees-mcp	The Bee's Knees レースゲーム
roastify-mcp	Roastify のコーヒーカタログ＋パッケージアートワーク
ChartRemotely-mcp	ペアリングされたエージェントを通じてデスクトップのチャートを操作
tollbooth-web	運営者のフロントエンド向け共有ブラウザー SDK
tollbooth-oauth2-collector	共有 OAuth2 コールバックコレクター（コミュニティ Advocate）
tollbooth-shortlinks	URL 短縮ユーティリティ

仕組み

1. 採用を申請する。 運営者は、自身の MCP で request_adoption(authority_npub=..., service_url=..., display_name=...) を呼び出し、nsec でリクエストに署名します。運営者のサービスがリクエストを Authority に送信すると、Authority はリクエストを保留中として記録し、所有者に通知します。所有者は approve_operator_request で承認するか、reject_operator_request で拒否します。承認されると、運営者の台帳エントリーが作成され、分離された Neon スキーマがプロビジョニングされ、Oracle を通じて登録されます。

2. 資金を補充する。 運営者は、事前に補充する sats の数を指定して purchase_credits を呼び出します。Authority は自身の BTCPay Server から Lightning インボイスを返します。運営者が支払い、決済後に check_payment が残高にクレジットを加算します。

3. 認定を受ける。 ユーザーが運営者からクレジットを購入しようとすると、運営者のサーバーが certify_credits を呼び出します。Authority は @runtime.paid_tool デコレーターを通じて従価手数料 2% を差し引き、Schnorr ベースの Nostr イベント証明書に署名して返します。

4. 検証する。 運営者の tollbooth-dpyc ライブラリが、Authority の Nostr npub を使って証明書を検証します。スタンプが有効な場合に限り、運営者はユーザー向けの Lightning インボイスを作成します。スタンプがなければ、料金は発生しません。

Nostr 証明書形式（kind 30079）

証明書は Ed25519 JWT ではなく、Schnorr 署名された Nostr イベント（NIP-33 のパラメーター化された置換可能イベント）です。各証明書には、p タグのオペレーターの npub、t／L タグの認定額とプロトコル、expiration タグが含まれ、content フィールドには構造化されたクレームデータが格納されます。検証には、Authority の Nostr npub に対する BIP-340 Schnorr 署名を使用します。

DPYC レジストリによる適用

Authority は認定時に、dpyc-community レジストリキャッシュ members/read-only-lookup-cache.json を確認します。オペレーターはレジストリで "status": "active" である必要があります。レジストリは設定可能な TTL で HTTP キャッシュされます。設計はフェイルクローズ方式です。レジストリにアクセスできない場合、認定は拒否されます。

上流のトポロジーはレジストリのメタデータ

親 Authority との関係は dpyc-community レジストリに記録されます。各 Authority の upstream_authority_npub は、そのスポンサーを指します。オペレーターの MCP は Oracle（resolve_authority_for(npub)）を通じて認定を行う Authority を特定し、レジストリのチェーンをたどります。上流を設定する Authority ごとの環境変数はありません。Authority 自身の certify_credits は、オペレーターのプリファンド残高から従価手数料を回収し、証明書に署名するだけです。トランザクションごとに上流へ問い合わせることはありません。

従価方式の価格設定

certify_credits は、amount_sats パラメーターに対する 2% の従価方式（最低 10 sats）で、@runtime.paid_tool として登録されます。手数料はデコレーターによって引き落とされ、コストは runtime._last_debit_cost から取得されます。二重計算は行いません。

OTS による公証

OpenTimestamps による公証が有効になっています（ランタイムで ots_enabled=True）。台帳の状態は、wheel が提供する標準ツール notarize_ledger と get_notarization_proof を通じて公証および検証できます。

リプレイ対策（ReplayTracker）

すべての証明書には一意の JTI（JWT ID）が含まれます。Authority は、TTL に基づくプルーニングを行うインメモリの順序付き辞書で、使用済みの JTI を追跡します。これにより、証明書が有効期限前に傍受された場合でも、証明書のリプレイ攻撃を防止できます。

MCP ツール

すべてのツールは wheel で定義され、server.py 内の 2 つの register_*_tools 呼び出しによって登録されるようになりました。正規の一覧表（register_authority_tools でマウントされる Authority ツール、および register_standard_tools でマウントされる標準ツール）については、tollbooth-dpyc README を参照してください。概要は次のとおりです。

• Authority ツール（Schnorr 証明書の署名、オペレーターのライフサイクル、3 ステップの Authority オンボーディング、レジストリのメンバーシップ確認）— register_authority_tools(mcp, runtime)。このセットには、所有者のリクエストキューも含まれます。receive_adoption_request（オペレーターの加入リクエストを受け取る場所）、list_operator_requests、approve_operator_request、reject_operator_request です。キューには 2 種類のリクエストが格納されます。加入リクエストと、オペレーターのレジストリエントリーの更新リクエスト（update_operator。オペレーターが呼び出し、所有者が承認します）です。deregister_operator に承認は不要です。オペレーター（脱退する場合）または Authority の所有者（登録を解除する場合）のどちらでも、単独で呼び出せます。repair_operator_schema は、テナントのテーブル所有権を修復する所有者用ツールです。
• 標準ツール（クレジット／支払い、ID、セキュアクーリエ、npub の証明、価格モデル、OpenTimestamps による公証、Oracle 委任）— register_standard_tools(mcp, "authority", runtime, ...)。

npub を受け取るすべてのツールでは、接続時にその証明が必要です。また、各リクエストは必ず 1 つの npub として動作します。その npub の nsec で署名されたリクエスト（NIP-98）によって証明されます。キーを持たないクライアントは OAuth の holder として接続し、DM への返信を経て request_npub_proof と receive_npub_proof を使用し、npub を一度だけウォレットに証明します。所有者専用ツールでは、リクエストによって Authority 自身の npub を証明する必要があります。証明をツール引数に含めることはありません。

はじめに

Horizon MCP 経由で接続する

Authority は Horizon 上で稼働しています。任意の MCP クライアント（Claude Desktop、Cursor、独自のエージェントなど）が Horizon 経由で接続できます。

https://www.fastmcp.cloud/server/lonniev/tollbooth-authority

接続に API キーは必要ありません。キーを持つクライアントは、そのキーを使って各リクエストに署名します（NIP-98）。それ以外のクライアントは、ホルダーとして OAuth で接続します。このホルダーには、Nostr DM によって npub が証明されるまで npub がありません。

初回接続の手順

接続したら、以下の順序でブートストラップを進めます。

1. request_adoption(authority_npub="npub1...", service_url="...") — 自分のオペレーター MCP で、自分のオペレーター nsec を使って署名し、呼び出します。Authority の所有者がこれを承認（approve_operator_request）すると、台帳エントリーが作成され、Neon スキーマがプロビジョニングされます。完了すると、オペレーターの adoption_status は provisioned になります。
2. purchase_credits(amount_sats=1000) — Lightning インボイスが返されます。任意の Lightning ウォレットで支払います。
3. check_payment(invoice_id="...") — 手順 2 のインボイス ID を渡します。決済の完了を確認し、残高にクレジットを追加します。
4. check_balance — 残高に資金が反映されていることを確認します。
5. operator_status — 登録情報、残高、ボールトのバックエンド、Authority の npub を確認します。tollbooth-dpyc は証明書の検証時にレジストリでこの npub を検索するため、ハードコードする必要はありません。

セルフホスト

独自の Authority インスタンスを実行するには、以下の環境変数を設定します。

必須

変数	用途	例
NEON_DATABASE_URL	オペレーターの永続台帳用 Neon Postgres URL。Authority は信頼の起点であり、環境変数からこの値を読み込みます（認定済みオペレーターは Nostr DM 経由で Authority から値を取得する点が異なります）。起動時に、Authority はスキーマごとの分離のため、接続文字列に search_path=authority を注入します。	postgresql://...
TOLLBOOTH_NOSTR_OPERATOR_NSEC	Schnorr 証明書への署名と Secure Courier DM に使用する Nostr 秘密鍵（nsec）	nsec1...

Secure Courier 経由での認証情報（環境変数ではありません）

BTCPay の認証情報は環境変数として設定せず、Secure Courier 経由で配信します。

認証情報	説明
btcpay_host	手数料の徴収に使用する Authority の BTCPay Server URL
btcpay_api_key	インボイスと支払いの権限を持つ BTCPay API キー
btcpay_store_id	Authority の手数料用ストアの BTCPay ストア ID

任意

変数	用途	デフォルト
CERTIFICATE_TTL_SECONDS	署名済み証明書の有効期間	600（10 分）
DPYC_ENFORCE_MEMBERSHIP	証明書発行時のレジストリ適用を有効にします	true
DPYC_REGISTRY_CACHE_TTL_SECONDS	DPYC コミュニティレジストリのキャッシュ期間	300

オペレーターごとのスキーマ分離

登録された各オペレーターには、専用の Postgres LOGIN ロールを持つ分離済み Neon スキーマ（op_{hash}）が割り当てられます。Authority スキーマ（authority）には Authority 自身の台帳が保存されます。オペレーターのスキーマは、所有者が導入申請を承認すると自動的にプロビジョニングされます。また、ロールベースの権限付与によってアクセスが制御されるため、オペレーター間でデータにアクセスすることはできません。

開発

python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -q

鍵の生成

Nostr 署名鍵（Schnorr 証明書）

Authority は Nostr の nsec/npub キーペアを使って証明書に署名します。任意の Nostr 鍵生成ツール（例：nak key generate）を使って生成してください。nsec は TOLLBOOTH_NOSTR_OPERATOR_NSEC に設定し、npub は operator_status を通じて tollbooth-dpyc の検証に利用できます。

DPYC ID（Nostr npub）

各 Authority は、DPYC Certification Chain 上で自身を識別する Nostr キーペアを持ちます。

pip install nostr-sdk
python -c "from nostr_sdk import Keys; k = Keys.generate(); print(f'npub: {k.public_key().to_bech32()}'); print(f'nsec (back up!): {k.secret_key().to_bech32()}')"

さらに読む

ライトニング・ターンパイクの幻の料金所 — AI API の収益化を収益化し、その後背景へと退いていくまでの全容です。

ライセンス

Apache License 2.0 — 詳細はLICENSEとNOTICEをご覧ください。

---

どのターンパイクにも管理者が必要です。道路を管理するためではなく、スタンプが本物で、通行料が適正であることを確かめるためです。