mcp-pay-gate

@powforge/mcp-pay-gate

MCP サーバー向けの、すぐに使える Express ミドルウェアです。L402 Lightning（レガシークライアント）と x402 bip122/exact（将来互換クライアント）に対応し、両方の決済方式で実際に動作する10段階の検証を行います。どちらも同じ LNBits バックエンドを利用します。v0.2.0 では、スタブなしの完全な x402 検証（BOLT11 のデコード、リプレイ保護、LNBits による支払い確認）を提供します。

デュアルレールを採用する理由

従量課金型の MCP 分野では、方式の統合が進んでいます。Coinbase の x402 仕様では、bip122/exact を追加する PR（coinbase/x402 #2258）が公開されており、これにより Bitcoin Lightning による決済が x402 に組み込まれます。つまり、今後30〜60日で、有料 MCP エンドポイントの決済方式はウォレットの対応状況に基づく選択へと集約されます。

今すぐ提供を開始して決済方式を1つだけ選ぶと、将来のクライアントの半数が利用できなくなります。サービスを2つ用意すると、同じ収益に対して運用の負担が倍増します。

このミドルウェアは、3つ目の選択肢です。402 チャレンジで両方の決済方式を提示し、呼び出し元が送信したいずれかを受け付けて、どちらの決済も同じ LNBits Lightning ウォレットで処理します。既存の L402 クライアントは引き続き動作し、新しい x402 クライアントも動作します。一度導入するだけです。

ステータス

v0.2.0 時点で、両方の決済方式が利用可能です。

• L402 方式：デフォルトでは、検証を ${POW_GATE_URL}/v1/verify に転送します。完全な互換性を実現するには、@powforge/mcp-l402-gate をプロセス内で使用した本番環境向けの検証を推奨します（このパッケージでは、マカロンの発行や HMAC のコードを重複して実装していません）。
• x402 方式：x402-foundation/x402 PR #1311 の仕様に準拠した、完全な10段階の bip122/exact 検証を行います。PR #1873 の Python リファレンス実装とも照合済みです。設定済みの LNBits バックエンドで実際の BOLT11 インボイスを発行し、light-bolt11-decoder でデコードしたうえで、scheme／network／asset／payTo／paymentMethod／インボイスの整合性／有効期限／正確な msat 額を検証します。インメモリの決済キャッシュでリプレイを早期に検出し、LNBits による支払い確認も行います。成功すると、base64 エンコードされた SettlementResponse を PAYMENT-RESPONSE ヘッダーで返します。テスト29件が合格しています（ミドルウェア12件、検証ユニットテスト17件）。

v0.3.0 への延期項目：処理中の HTLC の検出、BOLT12 オファー、マルチインスタンス対応の決済キャッシュ（Redis バックエンド）。

現在 L402 専用のゲートが必要な場合は、@powforge/mcp-l402-gate が特化型の製品です。完全な L402 検証、リプレイ保護、DoI スコアによる制御を提供します。このパッケージは、レガシー L402 クライアントと将来互換の x402 クライアントの両方に、1つの LNBits ウォレットでサービスを提供する運用者向けのデュアルレール版です。

必要条件

• Node >= 18
• 実際に決済を行うための LNBits ウォレット（URL とインボイス／読み取り用 API キー）
• デフォルトの L402 検証転送機能を使う場合、アクセス可能な POW_GATE_URL

Express への5行での統合

const express = require('express');
const { mcpPayGateMiddleware } = require('@powforge/mcp-pay-gate');

const app = express();
app.use('/tools/expensive', mcpPayGateMiddleware({
  satsAmount: 10,
}));

app.post('/tools/expensive', (req, res) => {
  // Reached only when the caller settled via L402 or x402.
  res.json({ ok: true, rail: req.payAuth.rail });
});

動作

呼び出し元からの送信内容	ミドルウェアの動作
Authorization ヘッダーなし	2つの WWW-Authenticate ヘッダー（L402 用と x402 用）を含む402と、両方の決済方式を列挙した JSON ボディを返します
Authorization: L402 <token>	verifyL402Fn(token) を呼び出します。成功時：req.payAuth = { rail: 'l402', payload } を設定して next() を呼び出します。失敗時：401を返します
Authorization: x402 <payload> または X-PAYMENT: <payload>	base64 の PaymentPayload をデコードし、10段階の bip122/exact 検証（scheme／network／asset／payTo／paymentMethod／インボイスの整合性／BOLT11 のデコード／有効期限／正確な msat 額／リプレイキャッシュと LNBits による支払い確認）を実行します。成功時：req.payAuth = { rail: 'x402-bip122-exact', paymentHash, amountMsat, payload } を設定し、PAYMENT-RESPONSE ヘッダーを付けて next() を呼び出します。失敗時：呼び出し元が再試行またはフォールバックできるよう、両方のチャレンジを含む402を返します
不明な方式	両方のチャレンジを含む402を返します

設定リファレンス

フィールド	デフォルト	備考
gateUrl	process.env.POW_GATE_URL or https://gate.powforge.dev	デフォルトの L402 検証フォワーダーで使用されます
priceMsat	3000 (3 sats)	x402 PaymentRequirements で通知されるミリサトシ単位の正確な金額です
network	bip122:000000000019d6689c085ae165831e93 (mainnet CAIP-2)	x402 チャレンジのネットワークです
scheme	exact	x402 チャレンジのスキームです（PR #1311 に準拠）
payTo	anonymous	x402 PaymentRequirements の payTo です（チャレンジ時点では Lightning にオンチェーンの送金先がありません）
lnbits.url, lnbits.apiKey	none	デフォルトの x402 インボイス発行と支払い確認に必要です。カスタムの invoiceFn と checkPaidFn の接続ポイントを渡すことで置き換えられます
verifyL402Fn	gate /v1/verify に転送	@powforge/mcp-l402-gate のインプロセス検証を組み込む場合にオーバーライドします
verifyX402Fn	完全な 10 ステップの bip122/exact 検証（BOLT11 デコード＋リプレイキャッシュ＋LNBits 支払い確認）	LNBits 以外のバックエンドに置き換える必要がある場合にのみオーバーライドします
settlementCache	TTL 24 時間で、機会に応じて整理されるメモリ内 Map	複数インスタンスのデプロイでは、Redis ベースのキャッシュで置き換えます（v0.3.0 に延期）

これは何ではないか

• これは macaroon の発行機能ではありません。PowForge に L402 をインプロセスで発行・検証させたい場合は、@powforge/mcp-l402-gate と組み合わせてください。
• これは LNBits クライアントではありません。インボイスの作成や支払い状況の確認は行いません。それらは検証関数が担当します。
• これは DoI スコアによるアクセス制御ではありません。支払いに加えてアイデンティティスコアに基づくアクセス制御を行いたい場合は、@powforge/mcp-l402-gate または @powforge/mcp-identity と組み合わせてください。

このパッケージの目的は、2 つの方式によるチャレンジ応答とリクエストルーティングの形を提供することです。実際の検証処理を組み込んでください。

ロードマップ

• v0.1（リリース済み）：足場。2 つの方式によるチャレンジ、L402 検証フォワーダー、x402 スタブ。
• v0.2（現行）：PR #1311 の仕様に準拠した完全な x402 bip122/exact 検証。実際の LNBits インボイス発行、BOLT11 デコード、メモリ内リプレイキャッシュ、10 ステップの検証、29 件のテスト。
• v0.3（予定）：処理中の HTLC 検出（Retry-After）、BOLT12 オファー、複数インスタンスのデプロイ向け Redis ベースの決済キャッシュ。

ライセンス

MIT。