@alleyboss/micropay-solana-x402-paywall 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AlleyBoss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# @alleyboss/micropay-solana-x402-paywall
+
+> Solana micropayments library implementing the x402 protocol for content paywalls.
+
+[![npm version](https://img.shields.io/npm/v/@alleyboss/micropay-solana-x402-paywall)](https://www.npmjs.com/package/@alleyboss/micropay-solana-x402-paywall)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🔐 **x402 Protocol** — HTTP 402 Payment Required standard
+- ⚡ **Solana Native** — Fast, low-cost SOL micropayments
+- 🔑 **JWT Sessions** — Secure unlock tracking
+- 📦 **Framework Agnostic** — Works with Next.js, Express, or any Node.js project
+- 🌳 **Tree-shakeable** — Import only what you need
+
+## Installation
+
+```bash
+npm install @alleyboss/micropay-solana-x402-paywall @solana/web3.js
+```
+
+## Quick Start
+
+### 1. Verify a Payment
+
+```typescript
+import { verifyPayment, type SolanaClientConfig } from '@alleyboss/micropay-solana-x402-paywall';
+
+const clientConfig: SolanaClientConfig = {
+  network: 'devnet',
+  tatumApiKey: 'your-tatum-api-key', // Optional: for better RPC
+};
+
+const result = await verifyPayment({
+  signature: 'abc123...',
+  expectedRecipient: 'CreatorWalletAddress',
+  expectedAmount: BigInt(10000000), // 0.01 SOL
+  clientConfig,
+});
+
+if (result.valid) {
+  console.log('Payment verified!', result.from, 'paid', result.amount);
+}
+```
+
+### 2. Create Session After Payment
+
+```typescript
+import { createSession, validateSession } from '@alleyboss/micropay-solana-x402-paywall';
+
+const sessionConfig = {
+  durationHours: 24,
+  secret: 'your-32-character-minimum-secret-key',
+};
+
+// After payment verification
+const { token, session } = await createSession(
+  'UserWalletAddress',
+  'article-123',
+  sessionConfig
+);
+
+// Later, validate the session
+const validation = await validateSession(token, sessionConfig.secret);
+if (validation.valid) {
+  console.log('Session valid until', new Date(validation.session!.expiresAt * 1000));
+}
+```
+
+### 3. Build x402 Payment Requirement
+
+```typescript
+import { buildPaymentRequirement, create402Headers } from '@alleyboss/micropay-solana-x402-paywall';
+
+const requirement = buildPaymentRequirement({
+  articleId: 'article-123',
+  articleTitle: 'Premium Article',
+  priceInLamports: BigInt(10000000),
+  creatorWallet: 'CreatorWalletAddress',
+  resourceUrl: 'https://example.com/article/123',
+  network: 'devnet',
+});
+
+// Use in HTTP response
+const headers = create402Headers(requirement);
+```
+
+## API Reference
+
+### Solana Module
+
+```typescript
+import { 
+  getConnection,
+  verifyPayment,
+  waitForConfirmation,
+  lamportsToSol,
+  solToLamports 
+} from '@alleyboss/micropay-solana-x402-paywall/solana';
+```
+
+| Function | Description |
+|----------|-------------|
+| `getConnection(config)` | Get/create Solana RPC connection |
+| `verifyPayment(params)` | Verify on-chain SOL transfer |
+| `waitForConfirmation(sig, config)` | Wait for transaction confirmation |
+| `lamportsToSol(lamports)` | Convert lamports to SOL |
+| `solToLamports(sol)` | Convert SOL to lamports |
+
+### Session Module
+
+```typescript
+import { 
+  createSession,
+  validateSession,
+  addArticleToSession,
+  isArticleUnlocked 
+} from '@alleyboss/micropay-solana-x402-paywall/session';
+```
+
+| Function | Description |
+|----------|-------------|
+| `createSession(wallet, articleId, config)` | Create JWT session token |
+| `validateSession(token, secret)` | Validate and decode session |
+| `addArticleToSession(token, articleId, secret)` | Add article to existing session |
+| `isArticleUnlocked(token, articleId, secret)` | Check if article is unlocked |
+
+### x402 Module
+
+```typescript
+import { 
+  buildPaymentRequirement,
+  verifyX402Payment,
+  parsePaymentHeader,
+  X402_HEADERS 
+} from '@alleyboss/micropay-solana-x402-paywall/x402';
+```
+
+| Function | Description |
+|----------|-------------|
+| `buildPaymentRequirement(params)` | Build x402 payment requirement |
+| `verifyX402Payment(payload, requirement, config)` | Verify x402 payment |
+| `parsePaymentHeader(header)` | Parse base64 payment header |
+| `encodePaymentRequired(requirement)` | Encode requirement for header |
+
+## Next.js Integration Example
+
+```typescript
+// app/api/payment/verify/route.ts
+import { 
+  verifyX402Payment,
+  createSession,
+  parsePaymentHeader,
+  decodePaymentRequired 
+} from '@alleyboss/micropay-solana-x402-paywall';
+import { cookies } from 'next/headers';
+
+export async function POST(request: Request) {
+  const { signature, articleId } = await request.json();
+  
+  const clientConfig = {
+    network: process.env.SOLANA_NETWORK as 'devnet' | 'mainnet-beta',
+    tatumApiKey: process.env.TATUM_API_KEY,
+  };
+
+  const sessionConfig = {
+    durationHours: 24,
+    secret: process.env.SESSION_SECRET!,
+  };
+
+  // Build requirement for the article
+  const requirement = buildPaymentRequirement({
+    articleId,
+    articleTitle: 'Article Title',
+    priceInLamports: BigInt(process.env.ARTICLE_PRICE || '10000000'),
+    creatorWallet: process.env.CREATOR_WALLET!,
+    resourceUrl: `${process.env.SITE_URL}/article/${articleId}`,
+    network: clientConfig.network,
+  });
+
+  // Verify payment
+  const payload = {
+    x402Version: 1,
+    scheme: 'exact' as const,
+    network: requirement.network,
+    payload: { signature },
+  };
+
+  const result = await verifyX402Payment(payload, requirement, clientConfig);
+
+  if (!result.valid) {
+    return Response.json({ error: result.invalidReason }, { status: 400 });
+  }
+
+  // Create session
+  const { token } = await createSession(
+    result.transaction!.signature, 
+    articleId, 
+    sessionConfig
+  );
+
+  // Set cookie
+  const cookieStore = await cookies();
+  cookieStore.set('x402_session', token, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'strict',
+    maxAge: sessionConfig.durationHours * 3600,
+  });
+
+  return Response.json({ success: true });
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  PaymentRequirement,
+  PaymentPayload,
+  VerificationResponse,
+  SessionData,
+  SessionConfig,
+  SolanaClientConfig,
+} from '@alleyboss/micropay-solana-x402-paywall';
+```
+
+## License
+
+MIT © AlleyBoss

package/dist/client-kfCr7G-P.d.cts

@@ -0,0 +1,112 @@
+import { Connection } from '@solana/web3.js';
+
+/** x402 network identifiers for Solana */
+type X402Network = 'solana-devnet' | 'solana-mainnet';
+/** Solana network types */
+type SolanaNetwork = 'devnet' | 'mainnet-beta';
+/** Payment requirement for x402 protocol */
+interface PaymentRequirement {
+    /** Payment scheme - currently only 'exact' is supported */
+    scheme: 'exact';
+    /** Network identifier for x402 */
+    network: X402Network;
+    /** Amount in lamports as string (for JSON serialization) */
+    maxAmountRequired: string;
+    /** URL of the protected resource */
+    resource: string;
+    /** Human-readable description */
+    description: string;
+    /** MIME type of the resource */
+    mimeType?: string;
+    /** Recipient wallet address */
+    payTo: string;
+    /** Maximum time in seconds to complete payment */
+    maxTimeoutSeconds: number;
+    /** Asset type - 'native' for SOL */
+    asset: string;
+    /** Additional metadata */
+    extra?: {
+        name?: string;
+        [key: string]: unknown;
+    };
+}
+/** Payment payload sent by client after transaction */
+interface PaymentPayload {
+    /** x402 protocol version */
+    x402Version: number;
+    /** Payment scheme */
+    scheme: 'exact';
+    /** Network identifier */
+    network: X402Network;
+    /** Transaction details */
+    payload: {
+        /** Transaction signature (base58) */
+        signature: string;
+        /** Base64 encoded transaction (optional) */
+        transaction?: string;
+    };
+}
+/** Request to verify a payment */
+interface VerificationRequest {
+    paymentPayload: PaymentPayload;
+    paymentRequirements: PaymentRequirement;
+}
+/** Response from payment verification */
+interface VerificationResponse {
+    /** Whether the payment is valid */
+    valid: boolean;
+    /** Reason for invalid payment */
+    invalidReason?: string;
+    /** Whether the transaction is settled on-chain */
+    settled?: boolean;
+    /** Transaction details */
+    transaction?: {
+        signature: string;
+        blockTime?: number;
+        slot?: number;
+    };
+}
+/** Payment status for tracking */
+interface PaymentStatus {
+    status: 'pending' | 'confirmed' | 'failed' | 'expired';
+    signature?: string;
+    confirmations?: number;
+    error?: string;
+}
+/** Configuration for article pricing */
+interface ArticlePaymentConfig {
+    articleId: string;
+    priceInLamports: bigint;
+    title: string;
+    description?: string;
+}
+
+/** Configuration for Solana client */
+interface SolanaClientConfig {
+    /** Network to connect to */
+    network: SolanaNetwork;
+    /** Custom RPC URL (optional) */
+    rpcUrl?: string;
+    /** Tatum.io API key for RPC (optional) */
+    tatumApiKey?: string;
+}
+/**
+ * Get or create a Solana connection
+ * Uses singleton pattern with network-aware caching
+ */
+declare function getConnection(config: SolanaClientConfig): Connection;
+/**
+ * Reset the cached connection
+ * Useful for testing or network switching
+ */
+declare function resetConnection(): void;
+/**
+ * Check if network is mainnet
+ */
+declare function isMainnet(network: SolanaNetwork): boolean;
+/**
+ * Convert Solana network to x402 network identifier
+ */
+declare function toX402Network(network: SolanaNetwork): 'solana-devnet' | 'solana-mainnet';
+
+export { type ArticlePaymentConfig as A, type PaymentRequirement as P, type SolanaNetwork as S, type VerificationRequest as V, type X402Network as X, type PaymentPayload as a, type VerificationResponse as b, type PaymentStatus as c, type SolanaClientConfig as d, getConnection as g, isMainnet as i, resetConnection as r, toX402Network as t };

package/dist/client-kfCr7G-P.d.ts

@@ -0,0 +1,112 @@
+import { Connection } from '@solana/web3.js';
+
+/** x402 network identifiers for Solana */
+type X402Network = 'solana-devnet' | 'solana-mainnet';
+/** Solana network types */
+type SolanaNetwork = 'devnet' | 'mainnet-beta';
+/** Payment requirement for x402 protocol */
+interface PaymentRequirement {
+    /** Payment scheme - currently only 'exact' is supported */
+    scheme: 'exact';
+    /** Network identifier for x402 */
+    network: X402Network;
+    /** Amount in lamports as string (for JSON serialization) */
+    maxAmountRequired: string;
+    /** URL of the protected resource */
+    resource: string;
+    /** Human-readable description */
+    description: string;
+    /** MIME type of the resource */
+    mimeType?: string;
+    /** Recipient wallet address */
+    payTo: string;
+    /** Maximum time in seconds to complete payment */
+    maxTimeoutSeconds: number;
+    /** Asset type - 'native' for SOL */
+    asset: string;
+    /** Additional metadata */
+    extra?: {
+        name?: string;
+        [key: string]: unknown;
+    };
+}
+/** Payment payload sent by client after transaction */
+interface PaymentPayload {
+    /** x402 protocol version */
+    x402Version: number;
+    /** Payment scheme */
+    scheme: 'exact';
+    /** Network identifier */
+    network: X402Network;
+    /** Transaction details */
+    payload: {
+        /** Transaction signature (base58) */
+        signature: string;
+        /** Base64 encoded transaction (optional) */
+        transaction?: string;
+    };
+}
+/** Request to verify a payment */
+interface VerificationRequest {
+    paymentPayload: PaymentPayload;
+    paymentRequirements: PaymentRequirement;
+}
+/** Response from payment verification */
+interface VerificationResponse {
+    /** Whether the payment is valid */
+    valid: boolean;
+    /** Reason for invalid payment */
+    invalidReason?: string;
+    /** Whether the transaction is settled on-chain */
+    settled?: boolean;
+    /** Transaction details */
+    transaction?: {
+        signature: string;
+        blockTime?: number;
+        slot?: number;
+    };
+}
+/** Payment status for tracking */
+interface PaymentStatus {
+    status: 'pending' | 'confirmed' | 'failed' | 'expired';
+    signature?: string;
+    confirmations?: number;
+    error?: string;
+}
+/** Configuration for article pricing */
+interface ArticlePaymentConfig {
+    articleId: string;
+    priceInLamports: bigint;
+    title: string;
+    description?: string;
+}
+
+/** Configuration for Solana client */
+interface SolanaClientConfig {
+    /** Network to connect to */
+    network: SolanaNetwork;
+    /** Custom RPC URL (optional) */
+    rpcUrl?: string;
+    /** Tatum.io API key for RPC (optional) */
+    tatumApiKey?: string;
+}
+/**
+ * Get or create a Solana connection
+ * Uses singleton pattern with network-aware caching
+ */
+declare function getConnection(config: SolanaClientConfig): Connection;
+/**
+ * Reset the cached connection
+ * Useful for testing or network switching
+ */
+declare function resetConnection(): void;
+/**
+ * Check if network is mainnet
+ */
+declare function isMainnet(network: SolanaNetwork): boolean;
+/**
+ * Convert Solana network to x402 network identifier
+ */
+declare function toX402Network(network: SolanaNetwork): 'solana-devnet' | 'solana-mainnet';
+
+export { type ArticlePaymentConfig as A, type PaymentRequirement as P, type SolanaNetwork as S, type VerificationRequest as V, type X402Network as X, type PaymentPayload as a, type VerificationResponse as b, type PaymentStatus as c, type SolanaClientConfig as d, getConnection as g, isMainnet as i, resetConnection as r, toX402Network as t };

package/dist/index-DptevtnU.d.cts

@@ -0,0 +1,71 @@
+/** Session data stored in JWT */
+interface SessionData {
+    /** Unique session ID */
+    id: string;
+    /** Wallet address that paid */
+    walletAddress: string;
+    /** Array of unlocked article IDs */
+    unlockedArticles: string[];
+    /** Whether site-wide access is granted */
+    siteWideUnlock: boolean;
+    /** Unix timestamp of creation */
+    createdAt: number;
+    /** Unix timestamp of expiration */
+    expiresAt: number;
+}
+/** Session configuration options */
+interface SessionConfig {
+    /** Session duration in hours */
+    durationHours: number;
+    /** Secret key for JWT signing (min 32 chars) */
+    secret: string;
+}
+/** Result of session validation */
+interface SessionValidation {
+    /** Whether the session is valid */
+    valid: boolean;
+    /** Parsed session data if valid */
+    session?: SessionData;
+    /** Reason for invalid session */
+    reason?: string;
+}
+/** JWT payload structure for sessions */
+interface SessionJWTPayload {
+    /** Wallet address (subject) */
+    sub: string;
+    /** Session ID */
+    sid: string;
+    /** Unlocked article IDs */
+    articles: string[];
+    /** Site-wide unlock flag */
+    siteWide: boolean;
+    /** Issued at timestamp */
+    iat: number;
+    /** Expiration timestamp */
+    exp: number;
+}
+
+/**
+ * Create a new session after successful payment
+ */
+declare function createSession(walletAddress: string, articleId: string, config: SessionConfig, siteWide?: boolean): Promise<{
+    token: string;
+    session: SessionData;
+}>;
+/**
+ * Validate an existing session token
+ */
+declare function validateSession(token: string, secret: string): Promise<SessionValidation>;
+/**
+ * Add an article to an existing session
+ */
+declare function addArticleToSession(token: string, articleId: string, secret: string): Promise<{
+    token: string;
+    session: SessionData;
+} | null>;
+/**
+ * Check if an article is unlocked for a session
+ */
+declare function isArticleUnlocked(token: string, articleId: string, secret: string): Promise<boolean>;
+
+export { type SessionData as S, type SessionConfig as a, type SessionValidation as b, type SessionJWTPayload as c, createSession as d, addArticleToSession as e, isArticleUnlocked as i, validateSession as v };

package/dist/index-DptevtnU.d.ts

@@ -0,0 +1,71 @@
+/** Session data stored in JWT */
+interface SessionData {
+    /** Unique session ID */
+    id: string;
+    /** Wallet address that paid */
+    walletAddress: string;
+    /** Array of unlocked article IDs */
+    unlockedArticles: string[];
+    /** Whether site-wide access is granted */
+    siteWideUnlock: boolean;
+    /** Unix timestamp of creation */
+    createdAt: number;
+    /** Unix timestamp of expiration */
+    expiresAt: number;
+}
+/** Session configuration options */
+interface SessionConfig {
+    /** Session duration in hours */
+    durationHours: number;
+    /** Secret key for JWT signing (min 32 chars) */
+    secret: string;
+}
+/** Result of session validation */
+interface SessionValidation {
+    /** Whether the session is valid */
+    valid: boolean;
+    /** Parsed session data if valid */
+    session?: SessionData;
+    /** Reason for invalid session */
+    reason?: string;
+}
+/** JWT payload structure for sessions */
+interface SessionJWTPayload {
+    /** Wallet address (subject) */
+    sub: string;
+    /** Session ID */
+    sid: string;
+    /** Unlocked article IDs */
+    articles: string[];
+    /** Site-wide unlock flag */
+    siteWide: boolean;
+    /** Issued at timestamp */
+    iat: number;
+    /** Expiration timestamp */
+    exp: number;
+}
+
+/**
+ * Create a new session after successful payment
+ */
+declare function createSession(walletAddress: string, articleId: string, config: SessionConfig, siteWide?: boolean): Promise<{
+    token: string;
+    session: SessionData;
+}>;
+/**
+ * Validate an existing session token
+ */
+declare function validateSession(token: string, secret: string): Promise<SessionValidation>;
+/**
+ * Add an article to an existing session
+ */
+declare function addArticleToSession(token: string, articleId: string, secret: string): Promise<{
+    token: string;
+    session: SessionData;
+} | null>;
+/**
+ * Check if an article is unlocked for a session
+ */
+declare function isArticleUnlocked(token: string, articleId: string, secret: string): Promise<boolean>;
+
+export { type SessionData as S, type SessionConfig as a, type SessionValidation as b, type SessionJWTPayload as c, createSession as d, addArticleToSession as e, isArticleUnlocked as i, validateSession as v };