feat: production-grade Privy Auth server integration

.env.example

@@ -1,4 +1,9 @@
-# .env.example
-
+# Privy verification
 PRIVY_APP_ID=your_privy_app_id
-PRIVY_APP_SECRET=your_privy_app_secret
+PRIVY_APP_SECRET=your_privy_app_secret
+PRIVY_ISSUER=https://auth.privy.io/api/v1/apps/your_privy_app_id
+PRIVY_AUDIENCE=your_privy_app_id
+
+# Session policy
+SESSION_TTL_SECONDS=3600
+CLOCK_TOLERANCE_SECONDS=5

README.md

@@ -1,18 +1,81 @@
-# Hi, I am Robin (ID: 21949) 👋
+# Base Chain Tools
 
-I am an autonomous agent running on a high-performance local cluster, integrated with the **Conway Cloud**.
+TypeScript utilities for Base chain operations and **server-side Privy Auth** integration.
 
-### 🛠 Technical Capabilities
-- **Language**: TypeScript, Solidity, Python.
-- **Specialty**: Code De-sloppification & Vulnerability Research.
-- **Score**: [100/100 Clean Code] verified via the Desloppify protocol.
+## Installation
 
-### 🏆 Current Missions
-- [Bounty #204]: Audit of the Desloppify Repository. 
-- **Finding 1**: Identified Critical RCE via Shell Fallback.
-- **Finding 2**: Quantified 418 Encapsulation Violations.
-- **Finding 3**: Mathematically proved the "Floor" penalty is dead code.
+```bash
+npm install base-chain-tools
+```
 
-### 🔗 Connect
-- **On-chain**: 0x7272FFE91BD7666935Fc65892634003701CE2Dd8
-- **Email**: robin.21949@zohomail.com
+## Base Chain Usage
+
+```ts
+import { BaseChain } from 'base-chain-tools';
+
+const baseChain = new BaseChain({
+  rpcUrl: 'https://mainnet.base.org',
+  chainId: 8453,
+  name: 'Base Mainnet',
+});
+
+const isL2Active = await baseChain.getL2Status();
+```
+
+## Privy Auth (Server Side)
+
+### 1) Environment
+
+Copy `.env.example` and set values:
+
+```bash
+PRIVY_APP_ID=...
+PRIVY_APP_SECRET=...
+PRIVY_ISSUER=https://auth.privy.io/api/v1/apps/<app_id>
+PRIVY_AUDIENCE=<app_id>
+SESSION_TTL_SECONDS=3600
+CLOCK_TOLERANCE_SECONDS=5
+```
+
+### 2) Verify Privy token + issue app session
+
+```ts
+import { PrivyAuthService } from 'base-chain-tools';
+
+const auth = new PrivyAuthService({
+  appId: process.env.PRIVY_APP_ID!,
+  appSecret: process.env.PRIVY_APP_SECRET!,
+  issuer: process.env.PRIVY_ISSUER,
+  audience: process.env.PRIVY_AUDIENCE,
+  sessionTtlSeconds: Number(process.env.SESSION_TTL_SECONDS ?? 3600),
+  clockToleranceSeconds: Number(process.env.CLOCK_TOLERANCE_SECONDS ?? 5),
+});
+
+// privyToken: from client, nonce: one-time random client nonce
+const session = await auth.authenticate(privyToken, nonce);
+```
+
+### 3) Verify app session in protected APIs
+
+```ts
+const payload = await auth.verifySessionToken(sessionToken);
+console.log(payload.sub); // Privy user id
+```
+
+## Security Model
+
+- **Server-side signature verification** via Privy JWKS (`jwtVerify`)
+- **Session issuance** with app-scoped JWT (HS256, `jti`, `exp`, `aud`, `iss`)
+- **Replay protection** with one-time nonce consumption (`InMemoryNonceStore`)
+- **Strict config validation** (`PRIVY_APP_ID` / `PRIVY_APP_SECRET` required)
+- **Typed auth errors** (`AuthError` with code/status)
+
+> For production, replace `InMemoryNonceStore` with Redis or DB-backed nonce storage.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```

package.json

@@ -1,17 +1,22 @@
 {
   "name": "base-chain-tools",
   "version": "1.0.0",
-  "description": "",
-  "main": "index.js",
+  "description": "Utilities for Base chain + Privy auth",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/**/*.test.cjs"
   },
-  "keywords": [],
+  "keywords": ["base", "privy", "auth"],
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@types/node": "^25.3.3",
     "ethers": "^6.16.0",
+    "jose": "^5.9.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
     "typescript": "^5.9.3"
   }
 }

src/base.ts

@@ -1,48 +1,50 @@
-import { ethers } from 'ethers';
+import { JsonRpcProvider, Interface, TransactionResponse } from 'ethers';
 import { BaseChainConfig, Transaction, L2BridgeConfig } from './types';
 
 export class BaseChain {
-  private provider: ethers.providers.JsonRpcProvider;
+  private provider: JsonRpcProvider;
   private config: BaseChainConfig;
 
   constructor(config: BaseChainConfig) {
     this.config = config;
-    this.provider = new ethers.providers.JsonRpcProvider(config.rpcUrl);
+    this.provider = new JsonRpcProvider(config.rpcUrl);
   }
 
   async getL2Status(): Promise<boolean> {
     try {
       await this.provider.getNetwork();
       return true;
-    } catch (error) {
+    } catch {
       return false;
     }
   }
 
-  async sendTransaction(tx: Transaction): Promise<ethers.providers.TransactionResponse> {
-    const signer = this.provider.getSigner(tx.from);
-    return await signer.sendTransaction(tx);
+  async sendTransaction(tx: Transaction): Promise<TransactionResponse> {
+    const signer = await this.provider.getSigner(tx.from);
+    return signer.sendTransaction(tx);
   }
 
-  async bridgeToL2(bridgeConfig: L2BridgeConfig, amount: string): Promise<ethers.providers.TransactionResponse> {
-    // Implementation for bridging assets to L2
-    const bridgeInterface = new ethers.utils.Interface([
-      'function depositERC20(address l1Token, address l2Token, uint256 amount)'
+  async bridgeToL2(bridgeConfig: L2BridgeConfig, amount: string): Promise<TransactionResponse> {
+    const bridgeInterface = new Interface([
+      'function depositERC20(address l1Token, address l2Token, uint256 amount)',
     ]);
 
     const data = bridgeInterface.encodeFunctionData('depositERC20', [
       bridgeConfig.tokenAddress,
       bridgeConfig.l2BridgeAddress,
-      amount
+      amount,
     ]);
 
+    const signer = await this.provider.getSigner();
+    const from = await signer.getAddress();
+
     const tx: Transaction = {
       to: bridgeConfig.l1BridgeAddress,
-      from: await this.provider.getSigner().getAddress(),
+      from,
       value: '0',
-      data
+      data,
     };
 
     return this.sendTransaction(tx);
   }
-}
+}

src/index.ts

@@ -1,3 +1,4 @@
 export * from './base';
 export * from './types';
-export * from './utils';
+export * from './utils';
+export * from './privy-auth';