@fiber-pay/sdk 0.1.0-rc.7 → 0.1.1

package/README.md

@@ -48,7 +48,17 @@ console.log(facts);
 This helper aligns with upstream Fiber Biscuit permission mapping (method -> read/write resource),
 and can be used to prepare `permissions.bc` inputs before signing tokens.
 
+## L402 Protocol
+
+The SDK includes L402 payment-gating primitives for Express APIs:
+
+- `MacaroonService` — mint and verify L402 tokens
+- `createL402Middleware()` — Express middleware for 402 challenge-response flow
+
+See [docs/l402-agent-guide.md](../../docs/l402-agent-guide.md) for usage.
+
 ## Compatibility
 
 - Node.js `>=20`
 - Fiber target: `v0.7.1`
+

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Request, Response, NextFunction } from 'express';
 import { z } from 'zod';
 
 /**
@@ -1028,6 +1029,231 @@ declare class LiquidityAnalyzer {
     }>;
 }
 
+/**
+ * MacaroonService
+ *
+ * Handles L402 macaroon minting, verification, and caveat management.
+ * Uses the `macaroon` npm package for cryptographic operations and
+ * Node.js built-in `crypto` for SHA-256 hashing.
+ */
+interface MacaroonCaveat {
+    condition: string;
+    value: string;
+}
+interface MintParams {
+    identifier: string;
+    paymentHash: string;
+    resourceId?: string;
+    resourceType?: string;
+    expirySeconds?: number;
+    location?: string;
+}
+interface VerifyResult {
+    valid: boolean;
+    error?: string;
+    caveats?: Record<string, string>;
+}
+declare class MacaroonService {
+    private rootKey;
+    constructor(rootKey?: string);
+    /**
+     * Mint a new macaroon with embedded caveats.
+     *
+     * The macaroon identifier encodes the payment hash, resource info, and
+     * version. First-party caveats are added for payment_hash, expiry, and
+     * optionally resource_id / resource_type.
+     */
+    mint(params: MintParams): {
+        macaroon: string;
+        caveats: MacaroonCaveat[];
+    };
+    /**
+     * Verify a macaroon with a payment preimage.
+     *
+     * Validates:
+     * 1. SHA-256(preimage) === payment_hash in the macaroon identifier
+     * 2. Macaroon signature against root key
+     * 3. Expiry caveat is not past
+     */
+    verify(macaroonB64: string, preimage: string): VerifyResult;
+    /**
+     * Verify macaroon signature and caveats without requiring a preimage.
+     *
+     * Used in the "connected-node" flow where the middleware verifies
+     * invoice settlement via Fiber RPC instead of requiring the client
+     * to provide the preimage directly.
+     */
+    verifyWithoutPreimage(macaroonB64: string): VerifyResult;
+    /** Extract caveats from a macaroon without full verification. */
+    extractCaveats(macaroonB64: string): Record<string, string>;
+    private generateRootKey;
+}
+
+/**
+ * L402 Protocol Types
+ *
+ * Type definitions for the L402 (HTTP 402 + Macaroon + Lightning Invoice)
+ * payment protocol. These types are framework-agnostic where possible;
+ * Express-specific types are isolated behind optional peer dependency.
+ */
+
+/** Fiber Network invoice used in L402 challenges. */
+interface L402Invoice {
+    paymentHash: string;
+    invoiceAddress: string;
+    amount: string;
+    description: string;
+    expiry: number;
+    createdAt: number;
+}
+/** Authorization token combining macaroon + payment preimage. */
+interface L402Token {
+    macaroon: string;
+    preimage: string;
+}
+/** Data returned in a 402 response. */
+interface L402Challenge {
+    macaroon: string;
+    invoice: string;
+}
+/** Core L402 configuration. */
+interface L402Config {
+    /** Hex string for macaroon signing (32 bytes / 64 hex chars). Falls back to L402_ROOT_KEY env or a secure random key. */
+    rootKey?: string;
+    /** Default expiry for macaroon + invoice in seconds. Default: 3600. */
+    expirySeconds: number;
+    /** Default price in CKB. */
+    priceCkb: number;
+}
+/** Express request augmented with L402 validation result. */
+interface L402Request extends Request {
+    l402?: {
+        valid: boolean;
+        preimage?: string;
+        paymentHash?: string;
+        token?: L402Token;
+    };
+}
+/** Full middleware configuration including rate limiting. */
+interface L402MiddlewareConfig extends L402Config {
+    rateLimitWindowMs: number;
+    rateLimitMaxRequests: number;
+}
+/** In-memory challenge store interface. */
+interface ChallengeStore {
+    get(key: string): L402Challenge | undefined;
+    set(key: string, value: L402Challenge): void;
+    delete(key: string): void;
+    has(key: string): boolean;
+}
+/** Metadata about a protected resource (used for dynamic pricing). */
+interface ProtectedResourceInfo {
+    id?: string;
+    type?: string;
+    priceCkb?: number;
+}
+/** Resolves request → resource info for dynamic pricing. */
+interface ResourceResolver {
+    name: string;
+    matches(req: Request): boolean;
+    resolve(req: Request): Promise<ProtectedResourceInfo | undefined>;
+}
+/** Registry that matches requests to the appropriate resolver. */
+interface ResourceResolverRegistry {
+    register(resolver: ResourceResolver): void;
+    resolve(req: Request): Promise<ProtectedResourceInfo | undefined>;
+}
+
+/**
+ * L402 Middleware for Express
+ *
+ * Protects routes with the L402 payment protocol. On unauthenticated
+ * requests it issues a 402 challenge (macaroon + Fiber invoice); on
+ * subsequent requests it verifies the L402 token.
+ *
+ * Two verification paths are supported:
+ *   Path A — client provides macaroon:preimage (legacy / manual flow)
+ *   Path B — client provides macaroon only; middleware checks invoice
+ *            settlement via Fiber RPC (connected-node flow)
+ *
+ * Uses `FiberRpcClient` from `@fiber-pay/sdk` directly for invoice
+ * creation and settlement checks, eliminating the intermediate
+ * InvoiceService abstraction from the upstream fiber-l402 SDK.
+ */
+
+interface L402ResourceResolver {
+    resolve(req: Request): Promise<ProtectedResourceInfo | undefined>;
+}
+type LegacyResourceProvider = (req: Request) => Promise<ProtectedResourceInfo | undefined> | ProtectedResourceInfo | undefined;
+declare class L402Middleware {
+    private config;
+    private rateLimitStore;
+    private macaroonService;
+    private rpcClient;
+    private resourceResolver?;
+    private currency;
+    constructor(config?: Partial<L402MiddlewareConfig> & {
+        /** Pre-configured RPC client. Takes precedence over rpcUrl. */
+        rpcClient?: FiberRpcClient;
+        /** Fiber node RPC URL. Used when rpcClient is not provided. */
+        rpcUrl?: string;
+        /** Biscuit token for Fiber RPC authentication. */
+        biscuitToken?: string;
+        /** Invoice currency. Default: 'Fibt' (testnet). */
+        currency?: Currency;
+        /** Resource resolver registry for dynamic pricing. */
+        resourceResolver?: L402ResourceResolver;
+        /** @deprecated Use resourceResolver instead. */
+        resourceProvider?: LegacyResourceProvider;
+    });
+    handle(req: L402Request, res: Response, next: NextFunction): Promise<void>;
+    private validateResourceCaveats;
+    private validatePaymentHashHeader;
+    private checkRateLimit;
+    private issueChallenge;
+    private createChallenge;
+}
+/**
+ * Create an L402 middleware function for Express.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { createL402Middleware } from '@fiber-pay/sdk';
+ *
+ * const app = express();
+ *
+ * app.get('/api/premium/*', createL402Middleware({
+ *   rootKey: process.env.L402_ROOT_KEY,
+ *   priceCkb: 0.1,
+ *   expirySeconds: 3600,
+ * }));
+ * ```
+ */
+declare function createL402Middleware(config?: Partial<L402MiddlewareConfig> & {
+    rpcClient?: FiberRpcClient;
+    rpcUrl?: string;
+    biscuitToken?: string;
+    currency?: Currency;
+    resourceResolver?: L402ResourceResolver;
+    resourceProvider?: LegacyResourceProvider;
+}): (req: L402Request, res: Response, next: NextFunction) => Promise<void>;
+
+/**
+ * Default Resource Resolver Registry
+ *
+ * Iterates registered resolvers to match incoming requests to protected
+ * resource metadata (id, type, price). Used by L402Middleware for
+ * dynamic per-resource pricing.
+ */
+
+declare class DefaultResourceResolverRegistry implements ResourceResolverRegistry {
+    private resolvers;
+    constructor(resolvers?: ResourceResolver[]);
+    register(resolver: ResourceResolver): void;
+    resolve(req: Request): Promise<ProtectedResourceInfo | undefined>;
+}
+
 /**
  * Biscuit policy helpers for Fiber RPC.
  *
@@ -1251,4 +1477,4 @@ declare class InvoiceVerifier {
     private calculateTrustScore;
 }
 
-export { AUTH_TAG_LENGTH, type AbandonChannelParams, type AcceptChannelParams, type AcceptChannelResult, type AgentSession, type Attribute, type AuditAction, type AuditLogEntry, type BiscuitAction, type BiscuitMethodRule, type BiscuitPermission, type BuildRouterParams, type BuildRouterResult, type CancelInvoiceParams, type CancelInvoiceResult, type CchInvoice, type CchOrderStatus, type CellOutput, type Channel, type ChannelId, type ChannelPolicy, ChannelPolicySchema, ChannelState, type ChannelStateFlags, type ChannelUpdateInfo, type CkbInvoice, type CkbInvoiceStatus, type ConnectPeerParams, type ConnectPeerResult, type Currency, DEFAULT_SECURITY_POLICY, type DisconnectPeerParams, ENCRYPTED_MAGIC, FiberRpcClient, FiberRpcError, type GetInvoiceParams, type GetInvoiceResult, type GetPaymentParams, type GetPaymentResult, type GraphChannelInfo, type GraphChannelsParams, type GraphChannelsResult, type GraphNodeInfo, type GraphNodesParams, type GraphNodesResult, type Hash256, type HashAlgorithm, type HexString, type HopHint, type HopRequire, type Htlc, IV_LENGTH, type InvoiceData, type InvoiceSignature, type InvoiceVerificationResult, InvoiceVerifier, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, KEY_LENGTH, type KeyConfig, type KeyInfo, LiquidityAnalyzer, type LiquidityReport, type ListChannelsParams, type ListChannelsResult, type ListPeersResult, type Multiaddr, type NewInvoiceParams, type NewInvoiceResult, type NodeInfo, type NodeInfoResult, type OpenChannelParams, type OpenChannelResult, type OutPoint, type ParseInvoiceParams, type ParseInvoiceResult, type PaymentCustomRecords, type PaymentHash, type PaymentInfo, type PaymentStatus, type PeerId, type PeerInfo, type PolicyCheckResult, PolicyEngine, type PolicyViolation, type Privkey, type Pubkey, type RateLimit, RateLimitSchema, type RecipientPolicy, RecipientPolicySchema, type RemoveTlcReason, type RevocationData, type RouterHop, SALT_LENGTH, SCRYPT_N, SCRYPT_P, SCRYPT_R, type Script$1 as Script, type SecurityPolicy, SecurityPolicySchema, type SendPaymentParams, type SendPaymentResult, type SendPaymentWithRouterParams, type SessionRoute, type SessionRouteNode, type SettleInvoiceParams, type SettlementData, type SettlementTlc, type ShutdownChannelParams, type SpendingLimit, SpendingLimitSchema, type TLCId, type TlcStatus, type UdtArgInfo, type UdtCellDep, type UdtCfgInfos, type UdtDep, type UdtScript, type UpdateChannelParams, type ViolationType, buildMultiaddr, buildMultiaddrFromNodeId, buildMultiaddrFromRpcUrl, ckbHash, ckbToShannons, collectBiscuitPermissions, decryptKey, derivePublicKey, fromHex, generatePreimage, generatePrivateKey, getBiscuitRuleForMethod, hashPreimage, isEncryptedKey, listSupportedBiscuitMethods, nodeIdToPeerId, randomBytes32, renderBiscuitFactsForMethods, renderBiscuitPermissionFacts, scriptToAddress, sha256Hash, shannonsToCkb, toHex, verifyPreimageHash };
+export { AUTH_TAG_LENGTH, type AbandonChannelParams, type AcceptChannelParams, type AcceptChannelResult, type AgentSession, type Attribute, type AuditAction, type AuditLogEntry, type BiscuitAction, type BiscuitMethodRule, type BiscuitPermission, type BuildRouterParams, type BuildRouterResult, type CancelInvoiceParams, type CancelInvoiceResult, type CchInvoice, type CchOrderStatus, type CellOutput, type ChallengeStore, type Channel, type ChannelId, type ChannelPolicy, ChannelPolicySchema, ChannelState, type ChannelStateFlags, type ChannelUpdateInfo, type CkbInvoice, type CkbInvoiceStatus, type ConnectPeerParams, type ConnectPeerResult, type Currency, DEFAULT_SECURITY_POLICY, DefaultResourceResolverRegistry, type DisconnectPeerParams, ENCRYPTED_MAGIC, FiberRpcClient, FiberRpcError, type GetInvoiceParams, type GetInvoiceResult, type GetPaymentParams, type GetPaymentResult, type GraphChannelInfo, type GraphChannelsParams, type GraphChannelsResult, type GraphNodeInfo, type GraphNodesParams, type GraphNodesResult, type Hash256, type HashAlgorithm, type HexString, type HopHint, type HopRequire, type Htlc, IV_LENGTH, type InvoiceData, type InvoiceSignature, type InvoiceVerificationResult, InvoiceVerifier, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, KEY_LENGTH, type KeyConfig, type KeyInfo, type L402Challenge, type L402Config, type L402Invoice, L402Middleware, type L402MiddlewareConfig, type L402Request, type L402Token, LiquidityAnalyzer, type LiquidityReport, type ListChannelsParams, type ListChannelsResult, type ListPeersResult, type MacaroonCaveat, MacaroonService, type MintParams, type Multiaddr, type NewInvoiceParams, type NewInvoiceResult, type NodeInfo, type NodeInfoResult, type OpenChannelParams, type OpenChannelResult, type OutPoint, type ParseInvoiceParams, type ParseInvoiceResult, type PaymentCustomRecords, type PaymentHash, type PaymentInfo, type PaymentStatus, type PeerId, type PeerInfo, type PolicyCheckResult, PolicyEngine, type PolicyViolation, type Privkey, type ProtectedResourceInfo, type Pubkey, type RateLimit, RateLimitSchema, type RecipientPolicy, RecipientPolicySchema, type RemoveTlcReason, type ResourceResolver, type ResourceResolverRegistry, type RevocationData, type RouterHop, SALT_LENGTH, SCRYPT_N, SCRYPT_P, SCRYPT_R, type Script$1 as Script, type SecurityPolicy, SecurityPolicySchema, type SendPaymentParams, type SendPaymentResult, type SendPaymentWithRouterParams, type SessionRoute, type SessionRouteNode, type SettleInvoiceParams, type SettlementData, type SettlementTlc, type ShutdownChannelParams, type SpendingLimit, SpendingLimitSchema, type TLCId, type TlcStatus, type UdtArgInfo, type UdtCellDep, type UdtCfgInfos, type UdtDep, type UdtScript, type UpdateChannelParams, type VerifyResult, type ViolationType, buildMultiaddr, buildMultiaddrFromNodeId, buildMultiaddrFromRpcUrl, ckbHash, ckbToShannons, collectBiscuitPermissions, createL402Middleware, decryptKey, derivePublicKey, fromHex, generatePreimage, generatePrivateKey, getBiscuitRuleForMethod, hashPreimage, isEncryptedKey, listSupportedBiscuitMethods, nodeIdToPeerId, randomBytes32, renderBiscuitFactsForMethods, renderBiscuitPermissionFacts, scriptToAddress, sha256Hash, shannonsToCkb, toHex, verifyPreimageHash };

package/dist/index.js

@@ -534,6 +534,166 @@ var LiquidityAnalyzer = class {
   }
 };
 
+// src/l402/macaroon.ts
+import { createHash } from "crypto";
+import * as macaroon from "macaroon";
+var MacaroonService = class {
+  rootKey;
+  constructor(rootKey) {
+    const keyHex = rootKey || process.env.L402_ROOT_KEY || this.generateRootKey();
+    this.rootKey = Buffer.from(keyHex.replace(/^0x/, ""), "hex");
+    if (this.rootKey.length !== 32) {
+      throw new Error("Root key must be 32 bytes (64 hex characters)");
+    }
+  }
+  /**
+   * Mint a new macaroon with embedded caveats.
+   *
+   * The macaroon identifier encodes the payment hash, resource info, and
+   * version. First-party caveats are added for payment_hash, expiry, and
+   * optionally resource_id / resource_type.
+   */
+  mint(params) {
+    const expiryTimestamp = Math.floor(Date.now() / 1e3) + (params.expirySeconds || 3600);
+    const caveats = [
+      { condition: "payment_hash", value: params.paymentHash },
+      { condition: "expiry", value: expiryTimestamp.toString() }
+    ];
+    if (params.resourceId) {
+      caveats.push({ condition: "resource_id", value: params.resourceId });
+    }
+    if (params.resourceType) {
+      caveats.push({ condition: "resource_type", value: params.resourceType });
+    }
+    const identifier = JSON.stringify({
+      v: 0,
+      pid: params.paymentHash,
+      rid: params.resourceId,
+      rtype: params.resourceType,
+      loc: params.location || "fiber-l402"
+    });
+    const m = macaroon.newMacaroon({
+      rootKey: this.rootKey,
+      identifier,
+      location: params.location || "fiber-l402"
+    });
+    for (const caveat of caveats) {
+      m.addFirstPartyCaveat(`${caveat.condition}=${caveat.value}`);
+    }
+    const exported = m.exportJSON();
+    const macaroonB64 = Buffer.from(JSON.stringify(exported)).toString("base64");
+    return { macaroon: macaroonB64, caveats };
+  }
+  /**
+   * Verify a macaroon with a payment preimage.
+   *
+   * Validates:
+   * 1. SHA-256(preimage) === payment_hash in the macaroon identifier
+   * 2. Macaroon signature against root key
+   * 3. Expiry caveat is not past
+   */
+  verify(macaroonB64, preimage) {
+    try {
+      const exported = JSON.parse(Buffer.from(macaroonB64, "base64").toString());
+      const m = macaroon.importMacaroon(exported);
+      const identifierBytes = m.identifier;
+      const identifier = Buffer.from(identifierBytes).toString("utf-8");
+      const idData = JSON.parse(identifier);
+      const paymentHash = idData.pid;
+      const preimageHash = createHash("sha256").update(Buffer.from(preimage.replace(/^0x/, ""), "hex")).digest("hex");
+      if (preimageHash !== paymentHash.replace(/^0x/, "")) {
+        return { valid: false, error: "Invalid preimage: hash mismatch" };
+      }
+      const caveatCheck = (caveat) => {
+        if (caveat.startsWith("expiry=")) {
+          const expiry = parseInt(caveat.split("=")[1], 10);
+          if (expiry < Math.floor(Date.now() / 1e3)) {
+            return "Macaroon expired";
+          }
+        }
+        return null;
+      };
+      m.verify(this.rootKey, caveatCheck, []);
+      const caveats = {};
+      for (const caveat of m.caveats) {
+        const caveatStr = Buffer.from(caveat.identifier).toString("utf-8");
+        const [key, value] = caveatStr.split("=");
+        if (key && value) {
+          caveats[key] = value;
+        }
+      }
+      return { valid: true, caveats };
+    } catch (error) {
+      return {
+        valid: false,
+        error: error instanceof Error ? error.message : "Verification failed"
+      };
+    }
+  }
+  /**
+   * Verify macaroon signature and caveats without requiring a preimage.
+   *
+   * Used in the "connected-node" flow where the middleware verifies
+   * invoice settlement via Fiber RPC instead of requiring the client
+   * to provide the preimage directly.
+   */
+  verifyWithoutPreimage(macaroonB64) {
+    try {
+      const exported = JSON.parse(Buffer.from(macaroonB64, "base64").toString());
+      const m = macaroon.importMacaroon(exported);
+      const caveatCheck = (caveat) => {
+        if (caveat.startsWith("expiry=")) {
+          const expiry = parseInt(caveat.split("=")[1], 10);
+          if (expiry < Math.floor(Date.now() / 1e3)) {
+            return "Macaroon expired";
+          }
+        }
+        return null;
+      };
+      m.verify(this.rootKey, caveatCheck, []);
+      const caveats = {};
+      for (const caveat of m.caveats) {
+        const caveatStr = Buffer.from(caveat.identifier).toString("utf-8");
+        const [key, value] = caveatStr.split("=");
+        if (key && value) {
+          caveats[key] = value;
+        }
+      }
+      return { valid: true, caveats };
+    } catch (error) {
+      return {
+        valid: false,
+        error: error instanceof Error ? error.message : "Verification failed"
+      };
+    }
+  }
+  /** Extract caveats from a macaroon without full verification. */
+  extractCaveats(macaroonB64) {
+    try {
+      const exported = JSON.parse(Buffer.from(macaroonB64, "base64").toString());
+      const m = macaroon.importMacaroon(exported);
+      const caveats = {};
+      for (const caveat of m.caveats) {
+        const caveatStr = Buffer.from(caveat.identifier).toString("utf-8");
+        const parts = caveatStr.split("=");
+        if (parts.length === 2) {
+          caveats[parts[0]] = parts[1];
+        }
+      }
+      return caveats;
+    } catch {
+      return {};
+    }
+  }
+  generateRootKey() {
+    const bytes = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return Buffer.from(bytes).toString("hex");
+  }
+};
+
 // src/rpc/client.ts
 var HASH_ALGORITHM_MAP = {
   CkbHash: "ckb_hash",
@@ -991,6 +1151,237 @@ var FiberRpcClient = class {
   }
 };
 
+// src/l402/middleware.ts
+var L402Middleware = class {
+  config;
+  rateLimitStore;
+  macaroonService;
+  rpcClient;
+  resourceResolver;
+  currency;
+  constructor(config = {}) {
+    this.config = {
+      rootKey: config.rootKey || process.env.L402_ROOT_KEY,
+      expirySeconds: config.expirySeconds || 3600,
+      priceCkb: config.priceCkb || 0.1,
+      rateLimitWindowMs: config.rateLimitWindowMs || 6e4,
+      rateLimitMaxRequests: config.rateLimitMaxRequests || 100
+    };
+    this.rateLimitStore = /* @__PURE__ */ new Map();
+    this.macaroonService = new MacaroonService(this.config.rootKey);
+    this.currency = config.currency || "Fibt";
+    this.rpcClient = config.rpcClient || new FiberRpcClient({
+      url: config.rpcUrl || process.env.FIBER_RPC_URL || "http://127.0.0.1:8227",
+      biscuitToken: config.biscuitToken || process.env.FIBER_BISCUIT_TOKEN
+    });
+    if (config.resourceResolver) {
+      this.resourceResolver = config.resourceResolver;
+    } else if (config.resourceProvider) {
+      this.resourceResolver = {
+        resolve: async (req) => config.resourceProvider?.(req)
+      };
+    }
+  }
+  async handle(req, res, next) {
+    const clientIp = req.ip || req.socket.remoteAddress || "unknown";
+    if (!this.checkRateLimit(clientIp)) {
+      res.status(429).json({
+        error: "Rate limit exceeded",
+        retryAfter: Math.ceil(this.config.rateLimitWindowMs / 1e3)
+      });
+      return;
+    }
+    const resource = this.resourceResolver ? await this.resourceResolver.resolve(req) : void 0;
+    const authHeader = req.headers.authorization;
+    if (!authHeader?.startsWith("L402 ")) {
+      return this.issueChallenge(req, res, 402, void 0, resource);
+    }
+    const [, token] = authHeader.split(" ");
+    if (!token) {
+      return this.issueChallenge(req, res);
+    }
+    const splitIndex = token.indexOf(":");
+    const macaroonToken = splitIndex >= 0 ? token.slice(0, splitIndex) : token;
+    const preimage = splitIndex >= 0 ? token.slice(splitIndex + 1) : void 0;
+    if (!macaroonToken) {
+      return this.issueChallenge(req, res);
+    }
+    if (preimage) {
+      const result = this.macaroonService.verify(macaroonToken, preimage);
+      if (!result.valid) {
+        return this.issueChallenge(req, res, 401, result.error, resource);
+      }
+      const headerError2 = this.validatePaymentHashHeader(req, result.caveats || {});
+      if (headerError2) {
+        return this.issueChallenge(req, res, 401, headerError2, resource);
+      }
+      const validateError2 = this.validateResourceCaveats(result.caveats || {}, resource);
+      if (validateError2) {
+        return this.issueChallenge(req, res, 401, validateError2, resource);
+      }
+      req.l402 = { valid: true, preimage };
+      next();
+      return;
+    }
+    const verifyResult = this.macaroonService.verifyWithoutPreimage(macaroonToken);
+    if (!verifyResult.valid) {
+      return this.issueChallenge(req, res, 401, verifyResult.error, resource);
+    }
+    const caveats = verifyResult.caveats || {};
+    const paymentHash = caveats.payment_hash;
+    if (!paymentHash) {
+      return this.issueChallenge(req, res, 401, "Missing payment hash caveat", resource);
+    }
+    const headerError = this.validatePaymentHashHeader(req, caveats);
+    if (headerError) {
+      return this.issueChallenge(req, res, 401, headerError, resource);
+    }
+    const validateError = this.validateResourceCaveats(caveats, resource);
+    if (validateError) {
+      return this.issueChallenge(req, res, 401, validateError, resource);
+    }
+    try {
+      const invoiceResult = await this.rpcClient.getInvoice({
+        payment_hash: paymentHash
+      });
+      if (invoiceResult.status !== "Paid") {
+        return this.issueChallenge(
+          req,
+          res,
+          401,
+          `Invoice not settled (status: ${invoiceResult.status})`,
+          resource
+        );
+      }
+    } catch {
+      return this.issueChallenge(req, res, 401, "Failed to verify invoice status", resource);
+    }
+    req.l402 = { valid: true, paymentHash };
+    next();
+  }
+  // ─── Private Helpers ───────────────────────────────────────
+  validateResourceCaveats(caveats, resource) {
+    if (!resource) {
+      return void 0;
+    }
+    if (resource.id && caveats.resource_id && caveats.resource_id !== resource.id) {
+      return "Resource id mismatch";
+    }
+    if (resource.type && caveats.resource_type && caveats.resource_type !== resource.type) {
+      return "Resource type mismatch";
+    }
+    if (resource.id && !caveats.resource_id) {
+      return "Missing resource_id in macaroon";
+    }
+    if (resource.type && !caveats.resource_type) {
+      return "Missing resource_type in macaroon";
+    }
+    return void 0;
+  }
+  validatePaymentHashHeader(req, caveats) {
+    const rawHeader = req.headers["x-l402-payment-hash"];
+    const headerPaymentHash = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+    if (!headerPaymentHash) {
+      return void 0;
+    }
+    const caveatPaymentHash = caveats.payment_hash;
+    if (!caveatPaymentHash) {
+      return "Missing payment hash caveat";
+    }
+    if (headerPaymentHash !== caveatPaymentHash) {
+      return "Payment hash header mismatch";
+    }
+    return void 0;
+  }
+  checkRateLimit(ip) {
+    const now = Date.now();
+    const record = this.rateLimitStore.get(ip);
+    if (!record) {
+      this.rateLimitStore.set(ip, {
+        count: 1,
+        resetTime: now + this.config.rateLimitWindowMs
+      });
+      return true;
+    }
+    if (now > record.resetTime) {
+      this.rateLimitStore.set(ip, {
+        count: 1,
+        resetTime: now + this.config.rateLimitWindowMs
+      });
+      return true;
+    }
+    if (record.count >= this.config.rateLimitMaxRequests) {
+      return false;
+    }
+    record.count++;
+    return true;
+  }
+  async issueChallenge(req, res, statusCode = 402, errorMessage, resource) {
+    try {
+      const { macaroon: macaroon2, invoice } = await this.createChallenge(req, resource);
+      const wwwAuthenticate = `L402 macaroon="${macaroon2}", invoice="${invoice}"`;
+      res.status(statusCode).set("WWW-Authenticate", wwwAuthenticate).json({
+        error: errorMessage || "Payment Required",
+        macaroon: macaroon2,
+        invoice
+      });
+    } catch (error) {
+      res.status(500).json({
+        error: "Failed to create payment challenge",
+        message: error instanceof Error ? error.message : "Unknown error"
+      });
+    }
+  }
+  async createChallenge(req, resource) {
+    const priceCkb = resource?.priceCkb ?? this.config.priceCkb;
+    const amountShannons = `0x${(priceCkb * 1e8).toString(16)}`;
+    const invoiceResult = await this.rpcClient.newInvoice({
+      amount: amountShannons,
+      description: `L402 Payment ${resource?.type ?? "resource"}`,
+      currency: this.currency,
+      expiry: `0x${this.config.expirySeconds.toString(16)}`,
+      hash_algorithm: "Sha256"
+    });
+    const paymentHash = invoiceResult.invoice.data.payment_hash;
+    const { macaroon: macaroon2 } = this.macaroonService.mint({
+      identifier: `l402-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+      paymentHash,
+      expirySeconds: this.config.expirySeconds,
+      resourceId: resource?.id,
+      resourceType: resource?.type,
+      location: req.headers.host || "fiber-l402"
+    });
+    return { macaroon: macaroon2, invoice: invoiceResult.invoice_address };
+  }
+};
+function createL402Middleware(config = {}) {
+  const middleware = new L402Middleware(config);
+  return middleware.handle.bind(middleware);
+}
+
+// src/l402/resources.ts
+var DefaultResourceResolverRegistry = class {
+  resolvers;
+  constructor(resolvers = []) {
+    this.resolvers = [...resolvers];
+  }
+  register(resolver) {
+    this.resolvers.push(resolver);
+  }
+  async resolve(req) {
+    for (const resolver of this.resolvers) {
+      if (!resolver.matches(req)) {
+        continue;
+      }
+      const resource = await resolver.resolve(req);
+      if (resource) {
+        return resource;
+      }
+    }
+    return void 0;
+  }
+};
+
 // src/security/biscuit-policy.ts
 var RULES = {
   // Cch
@@ -1863,13 +2254,16 @@ var InvoiceVerifier = class {
 export {
   AUTH_TAG_LENGTH,
   ChannelState,
+  DefaultResourceResolverRegistry,
   ENCRYPTED_MAGIC,
   FiberRpcClient,
   FiberRpcError,
   IV_LENGTH,
   InvoiceVerifier,
   KEY_LENGTH,
+  L402Middleware,
   LiquidityAnalyzer,
+  MacaroonService,
   PolicyEngine,
   SALT_LENGTH,
   SCRYPT_N,
@@ -1881,6 +2275,7 @@ export {
   ckbHash,
   ckbToShannons,
   collectBiscuitPermissions,
+  createL402Middleware,
   decryptKey,
   derivePublicKey,
   fromHex,