Skip to main content

​
ペイメントレイヤー

l402-kit は ソベラノミドルウェア であり、3 行のコードで任意の HTTP エンドポイントに Bitcoin Lightning ペイウォールを追加します。Lightning プロバイダーはご自身でご用意ください — 資金は仲介業者を介さず直接あなたのウォレットに届きます。

​
プロトコル: L402

L402 は HTTP/1.1 にネイティブの決済ハンドシェイクを追加するオープン標準です: 
Client → GET /api/data
Server ← 402 Payment Required
         WWW-Authenticate: L402 <macaroon>, invoice="<BOLT11>"

Client pays invoice via Lightning wallet
Client → GET /api/data
         Authorization: L402 <macaroon>:<preimage>
Server ← 200 OK + data
macaroon はインボイスの paymentHash に紐付けられたケイパビリティトークンです。preimage は決済が確定したときに Lightning ノードが解放する暗号的シークレットです。サーバーは以下を検証します: 
SHA256(preimage) == paymentHash ✓
アカウント不要、セッション不要、JWT 不要 — preimage そのものが 支払証明です。

​
インボイス作成フロー

Your API receives a request without valid Authorization
     │
     ▼
l402-kit middleware calls lightning.createInvoice(priceSats)
     │  (your provider: Blink, Alby, OpenNode, BTCPay, LNbits…)
     ▼
Provider returns BOLT11 invoice + paymentHash
     │
     ▼
Middleware builds macaroon: base64({ hash: paymentHash, exp: now+1h })
     │
     ▼
Your API returns 402 + invoice + macaroon to client

​
決済検証フロー

Client pays BOLT11 invoice via any Lightning wallet
     │
     ▼
Lightning node releases preimage (32-byte secret)
     │
     ▼
Client sends Authorization: L402 <macaroon>:<preimage>
     │
     ▼
Middleware verifies locally — no network call:
  1. Decode macaroon (base64 → JSON { hash, exp })
  2. Check exp > now()
  3. SHA256(preimage) === hash ✓
     │
     ▼
Request passes through to your API handler → 200 OK
検証は O(1) です — 純粋な暗号演算であり、ホットパスでのデータベース検索は発生しません。リプレイ防止（Supabase payment_hash ロギング）は非同期で実行され、リクエストをブロックしません。

​
Macaroon フォーマット

l402-kit は軽量なカスタム macaroon を使用しています — libmacaroon ではありません。トークンは base64url エンコードされた JSON オブジェクトです: 
{ "hash": "<paymentHash hex>", "exp": <unix timestamp> }
これは外部ライブラリなしでシンプルかつ監査可能な形式です。Authorization ヘッダーのフォーマットは次のとおりです: 
Authorization: L402 <base64url-macaroon>:<preimage-hex>

​
手数料モデル

モード手数料セットアップ
ソベラノ（任意のプロバイダー）0% — 100% あなたの収益ご自身のプロバイダー認証情報をご用意ください
マネージド (ManagedProvider)l402kit.com へ 0.3%Lightning ノード不要 — すぐに使用可能
ソベラノモードがデフォルトです。マネージドモードは明示的なオプトインが必要です: 
// Soberano — 0% fee, you keep 100%
import { AlbyProvider } from 'l402-kit';
const lightning = new AlbyProvider(process.env.ALBY_TOKEN!);

// Managed — 0.3% fee, no Lightning node needed
import { ManagedProvider } from 'l402-kit';
const lightning = ManagedProvider.fromAddress('you@yourdomain.com');

​
データストレージ（オプション — Supabase）

SUPABASE_URL と SUPABASE_ANON_KEY を設定すると、決済を自動的に記録します: 
create table payments (
  id            uuid primary key default gen_random_uuid(),
  payment_hash  text unique not null,  -- SHA256(preimage) — safe to store
  endpoint      text,
  amount_sats   integer,
  paid_at       timestamptz default now()
);
preimage ではなく payment_hash を使用する理由は？ payment_hash はすべての BOLT11 インボイスにすでに埋め込まれており、設計上パブリックな情報です。秘密なのは preimage のみです。ハッシュを保存することで、追加の情報漏洩なしにリプレイ防止が実現できます。

​
Lightning プロバイダー

l402-kit はプロバイダーに依存しません。LightningProvider を実装する任意のバックエンドが利用できます:
プロバイダー備考
Alby Hubセルフカストディアル、手数料 0%
Blink無料カストディアル、少額なら KYC 不要
BTCPay Serverセルフホスト型、完全なソベラノティ
OpenNodeカストディアル、セットアップ不要
LNbitsセルフホストまたはクラウド
プロバイダーのセットアップについては TypeScript SDK または Python SDK をご覧ください。

​
セキュリティ保証

脅威対策
リプレイ攻撃Preimage は初回検証後に使用済みとしてマーク — インメモリまたは Redis アダプター
偽造 preimageSHA256(preimage) === paymentHash は暗号的に偽造不可能
トークン有効期限Macaroon に exp タイムスタンプが埋め込まれ — すべてのリクエストで検証
Webhook スプーフィングHMAC-SHA256(secret, body) を処理前に検証