Initial release of LnBot.L402

L402 Lightning payment middleware for .NET:
- LnBot.L402: Client-side HttpClient handler with auto-pay, token caching, and budget tracking
- LnBot.L402.AspNetCore: Server-side middleware, [L402] attribute, and endpoint filter

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: realbub

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        dotnet-version: ["8.0.x", "9.0.x"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET ${{ matrix.dotnet-version }}
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: ${{ matrix.dotnet-version }}
+
+      - name: Restore
+        run: dotnet restore
+
+      - name: Build
+        run: dotnet build --no-restore --warnaserror
+
+      - name: Test
+        run: dotnet test --no-build --verbosity normal

.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 8.0.x
+
+      - name: Test
+        run: dotnet test --verbosity normal
+
+      - name: Pack LnBot.L402
+        run: dotnet pack src/LnBot.L402/LnBot.L402.csproj -c Release -o ./nupkg
+
+      - name: Pack LnBot.L402.AspNetCore
+        run: dotnet pack src/LnBot.L402.AspNetCore/LnBot.L402.AspNetCore.csproj -c Release -o ./nupkg
+
+      - name: Publish to NuGet
+        run: dotnet nuget push ./nupkg/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json

.gitignore

@@ -0,0 +1,6 @@
+bin/
+obj/
+*.user
+*.suo
+.vs/
+*.DotSettings.user

README.md

@@ -0,0 +1,220 @@
+# LnBot.L402
+
+[![NuGet](https://img.shields.io/nuget/v/LnBot.L402)](https://www.nuget.org/packages/LnBot.L402)
+[![NuGet](https://img.shields.io/nuget/v/LnBot.L402.AspNetCore)](https://www.nuget.org/packages/LnBot.L402.AspNetCore)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+
+**L402 Lightning payment middleware for .NET** — paywall any API in one line. Built on [ln.bot](https://ln.bot).
+
+Two NuGet packages:
+
+- **`LnBot.L402`** — Client-side. Auto-pay L402-protected APIs with any `HttpClient`. Works in console apps, background services, MAUI — anything with `HttpClient`.
+- **`LnBot.L402.AspNetCore`** — Server-side. Protect ASP.NET Core routes behind L402 paywalls with middleware, `[L402]` attributes, or endpoint filters.
+
+Both packages are thin glue layers. All L402 logic — macaroon creation, signature verification, preimage checking — lives in the [ln.bot API](https://ln.bot/docs) via the [`LnBot` SDK](https://www.nuget.org/packages/LnBot). Zero crypto dependencies.
+
+---
+
+## What is L402?
+
+[L402](https://github.com/lightninglabs/L402) is a protocol built on HTTP `402 Payment Required`. It enables machine-to-machine micropayments over the Lightning Network:
+
+1. **Client** requests a protected resource
+2. **Server** returns `402` with a Lightning invoice and a macaroon token
+3. **Client** pays the invoice, obtains the preimage as proof of payment
+4. **Client** retries the request with `Authorization: L402 <macaroon>:<preimage>`
+5. **Server** verifies the token and grants access
+
+L402 is ideal for API monetization, AI agent tool access, pay-per-request data feeds, and any scenario where you want instant, permissionless, per-request payments without subscriptions or API key provisioning.
+
+---
+
+## Install
+
+```bash
+dotnet add package LnBot.L402.AspNetCore   # Server (includes client package)
+dotnet add package LnBot.L402              # Client only (no ASP.NET Core dependency)
+```
+
+---
+
+## Server — Protect Routes with L402
+
+### Middleware pipeline
+
+```csharp
+using LnBot;
+using LnBot.L402.AspNetCore;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddSingleton(new LnBotClient("key_..."));
+
+var app = builder.Build();
+
+app.UseL402Paywall("/api/premium", new L402Options
+{
+    Price = 10,
+    Description = "API access",
+});
+
+app.MapGet("/api/premium/data", () => Results.Ok(new { data = "premium content" }));
+app.MapGet("/api/free/health", () => Results.Ok(new { status = "ok" }));
+
+app.Run();
+```
+
+### Controller attribute
+
+```csharp
+[ApiController]
+[Route("api/[controller]")]
+public class WeatherController : ControllerBase
+{
+    [L402(Price = 50, Description = "Weather forecast")]
+    [HttpGet("forecast")]
+    public IActionResult GetForecast()
+        => Ok(new { forecast = "sunny" });
+}
+```
+
+### Minimal API endpoint filter
+
+```csharp
+app.MapGet("/api/premium/data", () => Results.Ok(new { data = "premium" }))
+   .AddEndpointFilter(new L402EndpointFilter(price: 10, description: "API access"));
+```
+
+### Dynamic pricing
+
+```csharp
+app.UseL402Paywall("/api/dynamic", new L402Options
+{
+    PriceFactory = context =>
+    {
+        if (context.Request.Path.StartsWithSegments("/api/dynamic/bulk"))
+            return Task.FromResult(50);
+        return Task.FromResult(5);
+    }
+});
+```
+
+---
+
+## Client — Auto-Pay L402 APIs
+
+### With ASP.NET Core DI
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddSingleton(new LnBotClient("key_..."));
+
+builder.Services.AddHttpClient("paid-apis")
+    .AddL402Handler(new L402ClientOptions
+    {
+        MaxPrice = 100,
+        BudgetSats = 50_000,
+        BudgetPeriod = BudgetPeriod.Day,
+    });
+
+var app = builder.Build();
+
+app.MapGet("/proxy", async (IHttpClientFactory factory) =>
+{
+    var http = factory.CreateClient("paid-apis");
+    var data = await http.GetStringAsync("https://api.example.com/premium/data");
+    return Results.Ok(data);
+});
+```
+
+### Console app (no ASP.NET Core)
+
+```csharp
+using LnBot;
+using LnBot.L402;
+using Microsoft.Extensions.DependencyInjection;
+
+var services = new ServiceCollection();
+services.AddSingleton(new LnBotClient("key_..."));
+services.AddSingleton<ITokenStore, MemoryTokenStore>();
+services.AddHttpClient("paid-apis").AddL402Handler();
+
+var provider = services.BuildServiceProvider();
+var http = provider.GetRequiredService<IHttpClientFactory>().CreateClient("paid-apis");
+
+// Auto-pays any 402 responses transparently
+var response = await http.GetStringAsync("https://api.example.com/premium/data");
+Console.WriteLine(response);
+```
+
+---
+
+## Header Utilities
+
+```csharp
+using LnBot.L402;
+
+// Parse Authorization: L402 <macaroon>:<preimage>
+var auth = L402Headers.ParseAuthorization("L402 mac_base64:preimage_hex");
+// → (Macaroon: "mac_base64", Preimage: "preimage_hex")
+
+// Parse WWW-Authenticate: L402 macaroon="...", invoice="..."
+var challenge = L402Headers.ParseChallenge("L402 macaroon=\"abc\", invoice=\"lnbc1...\"");
+// → (Macaroon: "abc", Invoice: "lnbc1...")
+
+// Format headers
+L402Headers.FormatAuthorization("mac", "pre");     // → "L402 mac:pre"
+L402Headers.FormatChallenge("mac", "lnbc1...");    // → "L402 macaroon=\"mac\", invoice=\"lnbc1...\""
+```
+
+---
+
+## Custom Token Store
+
+Implement `ITokenStore` for Redis, file system, or any persistence layer:
+
+```csharp
+public class RedisTokenStore : ITokenStore
+{
+    public Task<L402Token?> GetAsync(string url) { /* ... */ }
+    public Task SetAsync(string url, L402Token token) { /* ... */ }
+    public Task DeleteAsync(string url) { /* ... */ }
+}
+
+// Register in DI
+services.AddSingleton<ITokenStore, RedisTokenStore>();
+```
+
+---
+
+## How It Works
+
+**Server middleware** makes two SDK calls:
+- `client.L402.CreateChallengeAsync()` — creates an invoice + macaroon when a client needs to pay
+- `client.L402.VerifyAsync()` — verifies an L402 authorization token when a client presents one
+
+**Client handler** makes one SDK call:
+- `client.L402.PayAsync()` — pays a Lightning invoice and returns a ready-to-use Authorization header
+
+---
+
+## Requirements
+
+- **.NET 8+**
+- An [ln.bot](https://ln.bot) API key — [create a wallet](https://ln.bot/docs) to get one
+
+## Related packages
+
+- [`LnBot`](https://www.nuget.org/packages/LnBot) — The .NET SDK this package is built on
+- [`@lnbot/l402`](https://www.npmjs.com/package/@lnbot/l402) — TypeScript/Express.js equivalent
+- [`@lnbot/sdk`](https://www.npmjs.com/package/@lnbot/sdk) — TypeScript SDK
+
+## Links
+
+- [ln.bot](https://ln.bot) — website
+- [Documentation](https://ln.bot/docs)
+- [L402 specification](https://github.com/lightninglabs/L402)
+- [GitHub](https://github.com/lnbotdev)
+
+## License
+
+MIT

csharp-l402.slnx

@@ -0,0 +1,10 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/LnBot.L402.AspNetCore/LnBot.L402.AspNetCore.csproj" />
+    <Project Path="src/LnBot.L402/LnBot.L402.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/LnBot.L402.AspNetCore.Tests/LnBot.L402.AspNetCore.Tests.csproj" />
+    <Project Path="tests/LnBot.L402.Tests/LnBot.L402.Tests.csproj" />
+  </Folder>
+</Solution>

src/LnBot.L402.AspNetCore/L402Attribute.cs

@@ -0,0 +1,32 @@
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Filters;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace LnBot.L402.AspNetCore;
+
+/// <summary>
+/// Protects a controller action with an L402 paywall.
+/// Requires LnBotClient to be registered in DI.
+/// </summary>
+[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
+public class L402Attribute : Attribute, IAsyncActionFilter
+{
+    public int Price { get; set; }
+    public string? Description { get; set; }
+
+    public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
+    {
+        var client = context.HttpContext.RequestServices.GetRequiredService<LnBotClient>();
+
+        if (await L402Handler.HandleAsync(client, context.HttpContext, Price, Description))
+        {
+            await next();
+        }
+        else
+        {
+            // L402Handler already wrote the 402 response body.
+            // Set an empty result to prevent MVC from overwriting it.
+            context.Result = new EmptyResult();
+        }
+    }
+}

src/LnBot.L402.AspNetCore/L402EndpointFilter.cs

@@ -0,0 +1,35 @@
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace LnBot.L402.AspNetCore;
+
+/// <summary>
+/// Endpoint filter for minimal APIs that adds L402 paywall protection.
+/// </summary>
+public class L402EndpointFilter : IEndpointFilter
+{
+    private readonly int _price;
+    private readonly string? _description;
+
+    public L402EndpointFilter(int price, string? description = null)
+    {
+        _price = price;
+        _description = description;
+    }
+
+    public async ValueTask<object?> InvokeAsync(
+        EndpointFilterInvocationContext context,
+        EndpointFilterDelegate next)
+    {
+        var httpContext = context.HttpContext;
+        var client = httpContext.RequestServices.GetRequiredService<LnBotClient>();
+
+        if (await L402Handler.HandleAsync(client, httpContext, _price, _description))
+        {
+            return await next(context);
+        }
+
+        // L402Handler already wrote the 402 response — return empty to avoid double-write
+        return Results.Empty;
+    }
+}

src/LnBot.L402.AspNetCore/L402Extensions.cs

@@ -0,0 +1,21 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace LnBot.L402.AspNetCore;
+
+public static class L402Extensions
+{
+    /// <summary>
+    /// Adds L402 paywall middleware that protects all routes under the given path prefix.
+    /// Requires LnBotClient to be registered in DI.
+    /// </summary>
+    public static IApplicationBuilder UseL402Paywall(
+        this IApplicationBuilder app,
+        string path,
+        L402Options options)
+    {
+        var client = app.ApplicationServices.GetRequiredService<LnBotClient>();
+        return app.UseMiddleware<L402Middleware>(client, options, new PathString(path));
+    }
+}