@shadow-corp/nearconnect 1.0.0

package/README.md

@@ -0,0 +1,546 @@
+# NearConnect
+
+A comprehensive NEAR Protocol wallet connector library with a four-tier architecture supporting web wallets, browser extensions, hardware wallets, and mobile wallets.
+
+> **Fork Notice:** This is an enhanced fork of [azbang/near-connect](https://github.com/azbang/near-connect) (commit c72689d). See [Enhancements](#enhancements) for details on what's been added.
+
+## Installation
+
+```bash
+npm install @shadowcorp/near-connect
+# or
+yarn add @shadowcorp/near-connect
+```
+
+## Four-Tier Wallet Architecture
+
+![Four-Tier Architecture](./assets/four-tier-architecture.png)
+
+### Why Four Tiers?
+
+The original NEAR wallet connector relied heavily on iframe sandboxing for security. While sandboxes provide isolation, they have significant limitations:
+
+The four-tier architecture addresses these limitations by treating each wallet type according to its actual trust level and capabilities:
+
+| Tier | Type | Trust Level | Security Model |
+|------|------|-------------|----------------|
+| 1 | Sandboxed (Web) | Untrusted | Iframe isolation + origin verification |
+| 2 | Injected (Extensions) | Semi-trusted | Browser extension sandbox + permission model |
+| 3 | Privileged (Hardware) | Trusted | Physical device confirmation required |
+| 4 | External (Mobile) | Verified | Cryptographic signatures + callback verification |
+
+This architecture, combined with the security layers below, provides defense-in-depth rather than relying on any single security mechanism.
+
+## Quick Start
+
+```typescript
+import { NearConnector } from "@shadowcorp/near-connect";
+
+const connector = new NearConnector({
+  network: "mainnet",
+  // Optional: hardware wallet config
+  hardware: {
+    ledger: { enabled: true }
+  },
+  // Optional: WalletConnect for mobile
+  external: {
+    walletConnect: { projectId: "your-project-id" }
+  }
+});
+
+// Listen for events
+connector.on("wallet:signIn", async ({ accounts }) => {
+  console.log("Connected:", accounts[0].accountId);
+});
+
+connector.on("wallet:signOut", () => {
+  console.log("Disconnected");
+});
+
+// Get available wallets
+const wallets = connector.getWallets();
+
+// Connect to a wallet
+await connector.connect("ledger");
+
+// Sign and send transaction
+const result = await connector.signAndSendTransaction({
+  receiverId: "example.near",
+  actions: [{ type: "Transfer", params: { deposit: "1000000000000000000000000" } }]
+});
+```
+
+## Hardware Wallet Support (Ledger)
+
+```typescript
+import { LedgerWallet, createLedgerWallet } from "@shadowcorp/near-connect";
+
+// Using the factory function
+const ledger = createLedgerWallet({
+  network: "mainnet",
+  rpcUrl: "https://rpc.mainnet.near.org"
+});
+
+// Listen for hardware events
+ledger.on("waiting", ({ action }) => {
+  console.log(`Please ${action} on your Ledger device...`);
+});
+
+ledger.on("confirm", ({ action }) => {
+  console.log(`Action confirmed: ${action}`);
+});
+
+// Connect and get accounts
+await ledger.connect();
+const accounts = ledger.getAccounts();
+
+// Sign transaction
+const result = await ledger.signAndSendTransaction({
+  receiverId: "example.near",
+  actions: [{ type: "Transfer", params: { deposit: "1000000000000000000000000" } }]
+});
+```
+
+## Mobile Wallet Support
+
+```typescript
+import { ExternalWalletManager } from "@shadowcorp/near-connect";
+
+const external = new ExternalWalletManager({
+  network: "mainnet",
+  appName: "My dApp",
+  appUrl: "https://mydapp.com",
+  callbackUrl: "https://mydapp.com/callback"
+});
+
+// Connect via deep link (Meteor, HERE wallet)
+await external.connect("meteor-mobile");
+
+// Or via WalletConnect
+await external.connect("walletconnect");
+```
+
+## Pre-built UI Components
+
+```typescript
+import {
+  WalletSelectorModal,
+  TransactionModal,
+  AccountSwitcherModal,
+  darkTheme,
+  lightTheme
+} from "@shadowcorp/near-connect";
+
+// Wallet selection modal
+const selectorModal = new WalletSelectorModal({
+  wallets: connector.getWallets(),
+  theme: darkTheme,
+  onSelect: async (walletId) => {
+    await connector.connect(walletId);
+  }
+});
+
+selectorModal.open();
+
+// Transaction confirmation modal
+const txModal = new TransactionModal({
+  transaction: { receiverId: "example.near", actions: [...] },
+  theme: darkTheme,
+  onConfirm: async () => {
+    await connector.signAndSendTransaction(tx);
+  }
+});
+```
+
+## Session Persistence
+
+```typescript
+import {
+  SessionManager,
+  LocalStorage,
+  EncryptedStorage
+} from "@shadowcorp/near-connect";
+
+// Basic persistence
+const session = new SessionManager({
+  storage: new LocalStorage(),
+  key: "near-session"
+});
+
+// Encrypted persistence
+const secureSession = new SessionManager({
+  storage: new EncryptedStorage("your-encryption-key"),
+  key: "near-session",
+  expiresIn: 24 * 60 * 60 * 1000 // 24 hours
+});
+```
+
+## Connection Reliability
+
+```typescript
+import {
+  withRetry,
+  CircuitBreaker,
+  HealthMonitor,
+  ConnectionStateMachine
+} from "@shadowcorp/near-connect";
+
+// Retry with exponential backoff
+const result = await withRetry(
+  () => connector.signAndSendTransaction(tx),
+  { maxRetries: 3, baseDelay: 1000 }
+);
+
+// Circuit breaker for failing connections
+const breaker = new CircuitBreaker({
+  failureThreshold: 5,
+  resetTimeout: 30000
+});
+
+// Health monitoring
+const health = new HealthMonitor({
+  checkInterval: 10000,
+  healthCheck: () => connector.isConnected()
+});
+
+health.on("unhealthy", () => {
+  console.log("Connection lost, attempting reconnect...");
+});
+```
+
+## Transaction Simulation
+
+```typescript
+import { TransactionSimulator, quickGasEstimate } from "@shadowcorp/near-connect";
+
+// Quick gas estimate
+const gas = await quickGasEstimate(transaction, "mainnet");
+
+// Full simulation
+const simulator = new TransactionSimulator({ network: "mainnet" });
+const result = await simulator.simulate(transaction);
+
+if (result.warnings.length > 0) {
+  console.log("Warnings:", result.warnings);
+}
+```
+
+## Trust Scoring
+
+```typescript
+import { TrustScorer, quickTrustCheck } from "@shadowcorp/near-connect";
+
+// Quick trust check
+const trust = await quickTrustCheck("meteor-wallet");
+console.log(`Trust level: ${trust.level}`); // "high", "medium", "low", "unknown"
+
+// Detailed scoring
+const scorer = new TrustScorer();
+const score = await scorer.score("meteor-wallet");
+console.log(`Score: ${score.overall}/100`);
+console.log(`Signals:`, score.signals);
+console.log(`Warnings:`, score.warnings);
+```
+
+## Analytics
+
+```typescript
+import {
+  Analytics,
+  ConsoleAnalyticsAdapter,
+  BatchingAnalyticsAdapter
+} from "@shadowcorp/near-connect";
+
+const analytics = new Analytics({
+  adapter: new BatchingAnalyticsAdapter({
+    batchSize: 10,
+    flushInterval: 5000,
+    onFlush: (events) => {
+      // Send to your analytics service
+      fetch("/api/analytics", { method: "POST", body: JSON.stringify(events) });
+    }
+  })
+});
+
+// Track events
+analytics.track("wallet:connect", { walletId: "ledger" });
+analytics.track("transaction:send", { amount: "1 NEAR" });
+```
+
+## Security Layers
+
+Since sandboxing alone isn't sufficient, NearConnect implements multiple security layers that work together to protect users:
+
+### Transaction Guard
+
+Analyzes transactions before signing to detect dangerous operations:
+
+```typescript
+import { TransactionGuard, createDefaultTransactionGuard } from "@shadowcorp/near-connect";
+
+const guard = createDefaultTransactionGuard();
+
+// Analyze transaction risk
+const risk = guard.analyzeRisk({
+  receiverId: "contract.near",
+  actions: [{ type: "FunctionCall", params: { methodName: "transfer", args: {} } }]
+});
+
+console.log(risk.level);    // "low" | "medium" | "high" | "critical"
+console.log(risk.reasons);  // ["Large transfer: 500.00 NEAR"]
+
+// Validate before signing
+const result = guard.validate(transaction);
+if (!result.valid) {
+  console.log("Blocked:", result.error);
+}
+```
+
+**What it detects:**
+- Dangerous methods (`add_full_access_key`, `delete_account`, `deploy_contract`)
+- Large transfers (configurable threshold, default 100 NEAR)
+- Known scam contracts
+- Delete account actions
+- Contract deployments
+- Custom blocklists and allowlists
+
+### Origin Guard
+
+Validates message origins to prevent cross-site attacks:
+
+```typescript
+import { OriginGuard, createSecureMessageHandler } from "@shadowcorp/near-connect";
+
+const guard = new OriginGuard({
+  appOrigins: ["https://myapp.com"],
+  walletOrigins: {
+    "custom-wallet": ["https://custom.wallet"]
+  }
+});
+
+// Check if origin is trusted
+guard.isOriginTrusted("https://wallet.meteorwallet.app"); // true
+guard.isOriginTrusted("https://evil.com"); // false
+
+// Validate callback URLs
+const result = guard.verifyCallbackUrl("https://myapp.com/callback");
+if (!result.valid) {
+  console.log("Invalid callback:", result.reason);
+}
+
+// Secure postMessage handler
+const handler = createSecureMessageHandler({
+  trustedOrigins: ["https://wallet.meteorwallet.app"],
+  onMessage: (data, origin) => {
+    // Only called for verified origins
+  }
+});
+window.addEventListener("message", handler);
+```
+
+### Rate Limiter
+
+Prevents abuse by limiting request frequency:
+
+```typescript
+import { RateLimiter, connectLimiter, signLimiter } from "@shadowcorp/near-connect";
+
+// Custom limiter
+const limiter = new RateLimiter({
+  maxRequests: 10,      // Max requests per window
+  windowMs: 60000,      // 1 minute window
+  blockDurationMs: 300000  // Block for 5 minutes if exceeded
+});
+
+const result = limiter.check("user-action");
+if (!result.allowed) {
+  console.log(`Rate limited. Retry in ${result.retryAfter}s`);
+}
+
+// Pre-configured limiters
+connectLimiter.check("wallet-connect");  // 5 per minute
+signLimiter.check("sign-tx");            // 10 per minute
+```
+
+### Audit Log
+
+Tracks all wallet actions for investigation and compliance:
+
+```typescript
+import { AuditLog, createAuditLog } from "@shadowcorp/near-connect";
+
+const auditLog = createAuditLog({
+  consoleLog: true,           // Log security events to console
+  remoteEndpoint: "/api/audit", // Optional: send to server
+  persist: true               // Persist to localStorage
+});
+
+// Log events
+auditLog.log("wallet:connect", { walletId: "ledger", accountId: "alice.near" });
+auditLog.log("tx:sign", { data: { receiverId: "bob.near" } });
+auditLog.logSecurityWarning("Large transfer detected", { amount: "500 NEAR" });
+
+// Query events
+const securityEvents = auditLog.getSecurityEvents();
+const recentTx = auditLog.getEvents({ type: ["tx:sign", "tx:broadcast"], limit: 10 });
+
+// Export for analysis
+const json = auditLog.export();
+const csv = auditLog.exportCsv();
+```
+
+**Event types tracked:**
+- `wallet:connect`, `wallet:disconnect`, `wallet:switch`
+- `tx:sign`, `tx:broadcast`, `tx:blocked`, `tx:failed`
+- `security:violation`, `security:warning`
+- `rate:limited`
+- `hardware:connect`, `hardware:disconnect`, `hardware:error`
+
+### Secure Storage
+
+AES-GCM encrypted localStorage for sensitive data:
+
+```typescript
+import { SecureStorage, createSecureStorage } from "@shadowcorp/near-connect";
+
+// Create encrypted storage (browser only)
+const storage = await createSecureStorage({
+  keyName: "my-app-key"  // Stored in non-exportable CryptoKey
+});
+
+// Store sensitive data
+await storage.set("session", JSON.stringify({ token: "..." }));
+const data = await storage.get("session");
+```
+
+### Content Security Policy
+
+Helpers for configuring CSP headers:
+
+```typescript
+import {
+  generateCSP,
+  getRecommendedCSP,
+  runSecurityChecklist
+} from "@shadowcorp/near-connect";
+
+// Generate CSP header
+const csp = generateCSP({
+  "default-src": ["'self'"],
+  "connect-src": ["'self'", "https://rpc.mainnet.near.org"],
+  "frame-src": ["https://wallet.meteorwallet.app"]
+});
+
+// Get recommended CSP for NEAR apps
+const recommended = getRecommendedCSP();
+
+// Run security checklist
+const checks = runSecurityChecklist();
+checks.forEach(check => {
+  console.log(`${check.passed ? "✓" : "✗"} ${check.name}: ${check.message}`);
+});
+```
+
+### Using Security Layers Together
+
+```typescript
+import {
+  createDefaultTransactionGuard,
+  createAuditLog,
+  RateLimiter
+} from "@shadowcorp/near-connect";
+
+// Setup security stack
+const txGuard = createDefaultTransactionGuard();
+const auditLog = createAuditLog({ consoleLog: true });
+const rateLimiter = new RateLimiter({ maxRequests: 10, windowMs: 60000 });
+
+async function secureSign(transaction) {
+  // 1. Check rate limit
+  const rateResult = rateLimiter.check("sign");
+  if (!rateResult.allowed) {
+    auditLog.log("rate:limited", { data: { retryAfter: rateResult.retryAfter } });
+    throw new Error(`Rate limited. Retry in ${rateResult.retryAfter}s`);
+  }
+
+  // 2. Validate transaction
+  const txResult = txGuard.validate(transaction);
+  if (!txResult.valid) {
+    auditLog.logTransaction("tx:blocked", {
+      receiverId: transaction.receiverId,
+      error: txResult.error,
+      risk: txResult.risk.level
+    });
+    throw new Error(txResult.error);
+  }
+
+  // 3. Log and proceed
+  auditLog.logTransaction("tx:sign", { receiverId: transaction.receiverId });
+  return await wallet.signAndSendTransaction(transaction);
+}
+```
+
+## Enhancements
+
+This fork adds the following features to the original near-connect:
+
+### Session & Storage
+- Multiple storage backends (Memory, Local, Session, IndexedDB, Encrypted)
+- SessionManager with validation and automatic expiry
+
+### Error Handling
+- Structured error system with typed error codes
+- Specific error classes for different failure modes
+- User-friendly messages and recovery suggestions
+
+### UI Components
+- WalletSelectorModal, TransactionModal, AccountSwitcherModal
+- Dark/light theme system with CSS variable generation
+- Customizable icons and styling
+
+### Connection Reliability
+- Retry logic with exponential backoff
+- Connection state machine
+- Health monitoring
+- Automatic reconnection
+- Circuit breaker pattern
+
+### Hardware Wallets (Tier 3: Privileged)
+- WebHID transport for Ledger
+- APDU protocol implementation
+- Full borsh serialization for NEAR transactions
+- NEP-413 message signing
+
+### Mobile Wallets (Tier 4: External)
+- Deep link support (Meteor, HERE)
+- WalletConnect v2 integration
+- Redirect flow handling
+- Mobile device detection
+
+### Security Layers
+- **TransactionGuard** - Risk analysis, dangerous method detection, blocklists
+- **OriginGuard** - postMessage origin validation, callback URL verification
+- **SecureStorage** - AES-GCM encrypted localStorage
+- **RateLimiter** - Request throttling with configurable windows and blocking
+- **AuditLog** - Event tracking, security monitoring, JSON/CSV export
+- **CSP Helpers** - Content Security Policy generation and security checklist
+
+### Other
+- Transaction simulation with gas estimation
+- Federated wallet manifest system
+- Trust scoring for wallet reputation
+- Pluggable analytics system
+- Multi-account support
+
+## API Reference
+
+See the [TypeScript definitions](./src/index.ts) for full API documentation.
+
+## License
+
+MIT
+
+## Credits
+
+Original library by [azbang](https://github.com/azbang/near-connect).
+Enhanced by ShadowCorp.

package/build/InjectedWallet.d.ts

@@ -0,0 +1,22 @@
+import { Account, FinalExecutionOutcome, NearWalletBase, Network, SignAndSendTransactionParams, SignAndSendTransactionsParams, SignedMessage, SignMessageParams } from "./types";
+import { NearConnector } from "./NearConnector";
+export declare class InjectedWallet {
+    readonly connector: NearConnector;
+    readonly wallet: NearWalletBase;
+    constructor(connector: NearConnector, wallet: NearWalletBase);
+    get manifest(): import("./types").WalletManifest;
+    signIn(data?: {
+        network?: Network;
+        contractId?: string;
+        methodNames?: Array<string>;
+    }): Promise<Array<Account>>;
+    signOut(data?: {
+        network?: Network;
+    }): Promise<void>;
+    getAccounts(data?: {
+        network?: Network;
+    }): Promise<Array<Account>>;
+    signAndSendTransaction(params: SignAndSendTransactionParams): Promise<FinalExecutionOutcome>;
+    signAndSendTransactions(params: SignAndSendTransactionsParams): Promise<Array<FinalExecutionOutcome>>;
+    signMessage(params: SignMessageParams): Promise<SignedMessage>;
+}

package/build/InjectedWallet.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InjectedWallet = void 0;
+const actions_1 = require("./actions");
+class InjectedWallet {
+    connector;
+    wallet;
+    constructor(connector, wallet) {
+        this.connector = connector;
+        this.wallet = wallet;
+    }
+    get manifest() {
+        return this.wallet.manifest;
+    }
+    async signIn(data) {
+        return this.wallet.signIn({
+            network: data?.network || this.connector.network,
+            contractId: data?.contractId,
+            methodNames: data?.methodNames,
+        });
+    }
+    async signOut(data) {
+        await this.wallet.signOut({ network: data?.network || this.connector.network });
+    }
+    async getAccounts(data) {
+        return this.wallet.getAccounts({ network: data?.network || this.connector.network });
+    }
+    async signAndSendTransaction(params) {
+        const actions = (0, actions_1.nearActionsToConnectorActions)(params.actions);
+        const network = params.network || this.connector.network;
+        const result = await this.wallet.signAndSendTransaction({ ...params, actions, network });
+        if (!result)
+            throw new Error("No result from wallet");
+        // @ts-ignore
+        if (Array.isArray(result.transactions))
+            return result.transactions[0];
+        return result;
+    }
+    async signAndSendTransactions(params) {
+        const network = params.network || this.connector.network;
+        const transactions = params.transactions.map((transaction) => ({
+            actions: (0, actions_1.nearActionsToConnectorActions)(transaction.actions),
+            receiverId: transaction.receiverId,
+        }));
+        const result = await this.wallet.signAndSendTransactions({ ...params, transactions, network });
+        if (!result)
+            throw new Error("No result from wallet");
+        // @ts-ignore
+        if (Array.isArray(result.transactions))
+            return result.transactions;
+        return result;
+    }
+    async signMessage(params) {
+        return this.wallet.signMessage({ ...params, network: params.network || this.connector.network });
+    }
+}
+exports.InjectedWallet = InjectedWallet;
+//# sourceMappingURL=InjectedWallet.js.map

package/build/InjectedWallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InjectedWallet.js","sourceRoot":"","sources":["../src/InjectedWallet.ts"],"names":[],"mappings":";;;AAWA,uCAA0D;AAE1D,MAAa,cAAc;IACJ;IAAmC;IAAxD,YAAqB,SAAwB,EAAW,MAAsB;QAAzD,cAAS,GAAT,SAAS,CAAe;QAAW,WAAM,GAAN,MAAM,CAAgB;IAAG,CAAC;IAElF,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAA8E;QACzF,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;YACxB,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO;YAChD,UAAU,EAAE,IAAI,EAAE,UAAU;YAC5B,WAAW,EAAE,IAAI,EAAE,WAAW;SAC/B,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAA4B;QACxC,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,IAA4B;QAC5C,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,KAAK,CAAC,sBAAsB,CAAC,MAAoC;QAC/D,MAAM,OAAO,GAAG,IAAA,uCAA6B,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QAEzD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QACzF,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAEtD,aAAa;QACb,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC;YAAE,OAAO,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACtE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,uBAAuB,CAAC,MAAqC;QACjE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QACzD,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;YAC7D,OAAO,EAAE,IAAA,uCAA6B,EAAC,WAAW,CAAC,OAAO,CAAC;YAC3D,UAAU,EAAE,WAAW,CAAC,UAAU;SACnC,CAAC,CAAC,CAAC;QAEJ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,uBAAuB,CAAC,EAAE,GAAG,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC;QAC/F,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAEtD,aAAa;QACb,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC;YAAE,OAAO,MAAM,CAAC,YAAY,CAAC;QACnE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,MAAyB;QACzC,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;IACnG,CAAC;CACF;AArDD,wCAqDC"}