mcp-l402-gate

@powforge/mcp-l402-gate

MCP サーバー運用者向けの、アイデンティティスコアに基づく Lightning ペイウォールです。

L402 で証明できるのは、呼び出し元が 10 sats を支払ったことだけです。呼び出し元に評判があること、10 分以上活動していること、あるいはツール呼び出しの料金がその呼び出し元の経済状況を変えるかどうかまでは証明できません。新しいウォレットでも、実際のユーザーと同じ 10 sats を支払います。

このパッケージは、L402 の請求書に加えて、アイデンティティの深度（DoI）チェックを追加します。MCP ツールの手前に配置すると、呼び出し元は（a）Lightning 請求書を決済し、（b）ツール本体が実行される前に、しきい値を超える DoI スコアを持っている必要があります。安価なシビル攻撃でも通行料は支払いますが、通行料に加えて公開鍵ごとの評判要件が課されるため、どちらか一方だけの場合よりも攻略が困難になります。

動作を確認する

クローンして実行できるサンプルサーバーは、github.com/zekebuilds-lab/mcp-l402-gate-example にあります。mempool.space から BTC/USD 価格とメンプール手数料を取得する bitcoin_data というツールを 1 つ公開し、L402 + DoI でアクセスを制限しています。クローンし、LNBits の認証情報を設定して npm start を実行すれば、Lightning でアクセスを制限する MCP サーバーがローカルで起動します。

課題

Sats4AI のドキュメント自体にも、この制限が明記されています。

「自律型エージェントは、セッションをまたいで評判を築いたり、優遇措置を受けたりできません。」

@powforge/mcp-l402-gate は、L402 による支払い制限と DoI オラクルの複合アイデンティティスコアを組み合わせることで、この課題を解決します。料金を支払う呼び出し元は既知の呼び出し元でもあり、セッションをまたいで維持され、偽造には取り消せない労力を要する、公開鍵ごとの評判を持ちます。

L402 だけでは不十分な理由

L402 は優れたワイヤーフォーマットですが、不正利用の抑制には弱点があります。最近の MCP 課金ツール（sats4ai-mcp、invinoveritas、l402-kit、402-mcp、coinopai-mcp）は、いずれも同じ 402 -> macaroon -> paid -> tool body のフローを採用しており、攻撃者は毎分、新しいノードからこのフローを繰り返せます。coinopai-mcp の作者自身も、次のように述べています。「x402 は支払いのトランスポートにすぎません。エージェントのアイデンティティ、料金交渉、複数エージェント間の分割、評判には対応していません。」

PowForge は、これまで欠けていた要素を提供しています。https://identity.powforge.dev にある DoI オラクルは、任意の Nostr 公開鍵について、観測可能で取り消せない活動を、ソーシャル、アクセス、保証、経済の 4 つの側面から評価して算出したスコアを、Schnorr 署名付きで返します。このパッケージは、そのスコアを L402 のフローに組み込み、料金を支払う呼び出し元が、偽造にコストのかかる呼び出し元でもあることを保証します。

要件

• Node >= 18
• Lightning 用の LNBits ウォレット（URL + 請求書／読み取り API キー）
• アクセス可能な PowForge オラクル URL（デフォルト：https://identity.powforge.dev）

5 行で統合（Express）

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

const app = express();
app.use('/tools/expensive', mcpL402Middleware({
  secret: process.env.GATE_HMAC_SECRET,
  lnbitsUrl: process.env.LNBITS_URL,
  lnbitsApiKey: process.env.LNBITS_INVOICE_KEY,
  satsAmount: 10,
  minScore: 10, // composite >= 10 means "emerging" tier on the oracle
}));

app.post('/tools/expensive', (req, res) => {
  // Reached only when L402 paid AND req.doiScore >= 10
  res.json({ ok: true, doiScore: req.doiScore, l402: req.l402Token });
});

呼び出し元は、X-Caller-Pubkey ヘッダーまたは ?pubkey= クエリ文字列で公開鍵を渡します。v0.1.0 では呼び出し元が申告した値として扱います。v0.2.0 では NIP-98 を使って暗号学的に紐付ける予定です。

MCP ツールのラップ

const { mcpL402Tool } = require('@powforge/mcp-l402-gate');

const expensiveTool = mcpL402Tool({
  secret: process.env.GATE_HMAC_SECRET,
  lnbitsUrl: process.env.LNBITS_URL,
  lnbitsApiKey: process.env.LNBITS_INVOICE_KEY,
  satsAmount: 10,
  minScore: 10,
}, {
  name: 'image_render',
  description: 'Render an image. 10 sats. Requires DoI score >= 10.',
  inputSchema: {
    type: 'object',
    properties: {
      prompt: { type: 'string' },
      pubkey: { type: 'string' },
      auth: { type: 'object', properties: { macaroon: { type: 'string' }, preimage: { type: 'string' } } },
    },
    required: ['prompt', 'pubkey'],
  },
}, async (args, ctx) => {
  // Runs only when paid AND ctx.doiScore >= 10
  return { image_url: `https://example/r/${args.prompt}`, billed_to: ctx.doiScore };
});

// Register expensiveTool with your MCP server. On first call without args.auth,
// the tool returns { paid: false, challenge: { macaroon, invoice, ... } }.
// The MCP client pays the invoice, then re-calls with args.auth set.

設定リファレンス

フィールド	デフォルト	備考
secret	必須	マカロン署名用の HMAC キーです。定期的にローテーションしてください。
lnbitsUrl	必須	LNBits のベース URL です。
lnbitsApiKey	必須	LNBits の請求書／読み取り用キーです。管理者キーは絶対に渡さないでください。
satsAmount	10	呼び出しごとの請求額です。
minScore	10	この複合スコアを下回る有料呼び出し元を拒否します。
failClosed	true	オラクルでエラーが発生した場合、呼び出しを拒否します。req.doiScoreError を設定して処理を続行するには、false に設定してください。
oracleUrl	https://identity.powforge.dev	セルフホスト型オラクル用の上書き設定です。
scope	mcp-l402-gate:call	L402 マカロンのスコープです。
ttlSeconds	600	マカロンの有効期間です。
scoreField	composite	minScore との比較に使用するエンベロープのフィールドです。
callerPubkeyHeader	x-caller-pubkey	呼び出し元が申告した公開鍵を格納する HTTP ヘッダーです。
oracleAuth	任意	オラクル自体が L402 によるアクセス制限を受けている場合の {macaroon, preimage} です。
createInvoiceFn	任意	テスト用の差し替えポイントです。非同期の (memo) => {payment_hash, bolt11} です。
checkPaidFn	任意	テスト用の差し替えポイントです。非同期の (payment_hash) => boolean です。
lookupScoreFn	任意	テスト用の差し替えポイントです。非同期の (pubkey) => {composite, rank, depth} です。

スコアのしきい値（複合スコア）

オラクルが rank として報告するものと同じ区分です。

しきい値	ランク	使用する場面
0	不明	呼び出しを有料にするだけでよい場合です。このパッケージは使わず、L402 を直接使用してください。
10	新興	初回呼び出しの不正利用が問題になる場合です。ほとんどの公開 MCP ツールでのデフォルト値です。
40	活発	ツールが実際に GPU を稼働させる場合や、高コストな副作用がある場合です。
100	確立済み	コンプライアンスが重視されるエンドポイントや、単一テナントの SaaS 型エンドポイントの場合です。
200	信頼済み	高い信頼性が求められる管理ツールの場合です。

エラーの種類

ステータス	本文	意味
402	{error: "payment required", macaroon, invoice, payment_hash}	初回呼び出しです。請求書を支払い、Authorization: L402 <macaroon>:<preimage> を付けて再試行してください。
401	{error: "invalid macaroon", reason}	マカロンの形式が正しくない、有効期限切れ、スコープが異なる、または署名が正しくありません。
401	{error: "preimage does not match payment hash"}	プリイメージが、マカロンの支払いハッシュに対する SHA-256 検証に失敗しました。
409	{error: "macaroon already redeemed"}	リプレイ防止機能が作動しました。新しいマカロンを発行してください。
400	{error: "caller_pubkey_required"}	X-Caller-Pubkey ヘッダーまたは ?pubkey= クエリがありません。
403	{error: "score_too_low", score, min, rank}	呼び出し元は支払い済みですが、DoI スコアがしきい値を下回っています。
503	{error: "oracle_unavailable", mode: "fail_closed"}	オラクルでエラーが発生し、failClosed が有効です（デフォルト）。
502	{error: "invoice provider unavailable"}	初回呼び出し時の発行処理で LNBits に接続できません。

このパッケージが独立している理由

L402 マカロンの発行・検証コード、LNBits クライアント、オラクルクライアントは、すでにほかの PowForge パッケージに含まれています。@powforge/mcp-l402-gate の目的は、それらを簡単に組み合わせられるようにすることです。ファクトリー、設定オブジェクト、ミドルウェア、またはツールラッパーを 1 つずつ用意するだけです。運用者は、防御されたエンドポイントを実現するために 3 つのパッケージを手作業で組み合わせる必要はありません。

テスト

npm test

実際のネットワークを使用しないユニットテストが 16 件あります。マカロンの HMAC は実際に検証し、LNBits とオラクルはスタブ化しています。

ライセンス

MIT。

リンク

• PowForge オラクル（稼働中）：https://identity.powforge.dev
• Identity SDK：npm の @powforge/identity
• MCP identity tools：npm の @powforge/mcp-identity