litesoc 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LiteSOC
+
+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,388 @@
+# LiteSOC Node.js SDK
+
+Official Node.js/TypeScript SDK for [LiteSOC](https://litesoc.io) - Security event tracking and threat detection.
+
+[![npm version](https://badge.fury.io/js/litesoc.svg)](https://www.npmjs.com/package/litesoc)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🔒 **Type-safe** - Full TypeScript support with predefined event types
+- ⚡ **Batching** - Automatic event batching to reduce network calls
+- 🌐 **Universal** - Works in Node.js, Next.js (Server Side), and Edge runtimes
+- 🔄 **Auto-retry** - Automatic retry on network failures
+- 🤫 **Silent mode** - Fail silently without crashing your application
+- 📦 **Zero dependencies** - Pure TypeScript, no external dependencies
+
+## Installation
+
+```bash
+npm install litesoc
+# or
+yarn add litesoc
+# or
+pnpm add litesoc
+```
+
+## Quick Start
+
+```typescript
+import { LiteSOC } from 'litesoc';
+
+// Initialize the SDK
+const litesoc = new LiteSOC({
+  apiKey: 'your-api-key',
+});
+
+// Track a login failure
+await litesoc.track('auth.login_failed', {
+  actor: { id: 'user_123', email: 'user@example.com' },
+  userIp: '192.168.1.1',
+  metadata: { reason: 'invalid_password' },
+});
+
+// Flush remaining events before shutdown
+await litesoc.flush();
+```
+
+## Configuration
+
+```typescript
+const litesoc = new LiteSOC({
+  // Required: Your LiteSOC API key
+  apiKey: 'your-api-key',
+
+  // Optional: Custom API endpoint (default: https://www.litesoc.io/api/v1/collect)
+  endpoint: 'https://www.litesoc.io/api/v1/collect',
+
+  // Optional: Enable event batching (default: true)
+  batching: true,
+
+  // Optional: Batch size before auto-flush (default: 10)
+  batchSize: 10,
+
+  // Optional: Batch flush interval in ms (default: 5000)
+  flushInterval: 5000,
+
+  // Optional: Enable debug logging (default: false)
+  debug: false,
+
+  // Optional: Fail silently on errors (default: true)
+  silent: true,
+
+  // Optional: Custom fetch implementation for Edge runtimes
+  fetch: customFetch,
+});
+```
+
+## Usage
+
+### Basic Event Tracking
+
+```typescript
+// Track with full options
+await litesoc.track('auth.login_failed', {
+  actor: { id: 'user_123', email: 'user@example.com' },
+  userIp: '192.168.1.1',
+  metadata: { reason: 'invalid_password', attempts: 3 },
+});
+
+// Track with shorthand actor (just ID)
+await litesoc.track('user.created', {
+  actor: 'user_456',
+  actorEmail: 'newuser@example.com',
+});
+
+// Track with custom event type
+await litesoc.track('custom.event_type', {
+  actor: 'system',
+  metadata: { custom_field: 'value' },
+});
+```
+
+### Convenience Methods
+
+```typescript
+// Login events
+await litesoc.trackLoginFailed('user_123', { userIp: '192.168.1.1' });
+await litesoc.trackLoginSuccess('user_123', { userIp: '192.168.1.1' });
+
+// Security events
+await litesoc.trackPrivilegeEscalation('user_123', { 
+  userIp: '192.168.1.1' 
+});
+
+// Data events
+await litesoc.trackSensitiveAccess('user_123', 'users.ssn', { 
+  userIp: '192.168.1.1' 
+});
+
+await litesoc.trackBulkDelete('user_123', 1000, { 
+  metadata: { table: 'orders' } 
+});
+
+// Authorization events
+await litesoc.trackRoleChanged('user_123', 'user', 'admin', {
+  userIp: '192.168.1.1',
+});
+
+await litesoc.trackAccessDenied('user_123', '/admin/settings', {
+  userIp: '192.168.1.1',
+});
+```
+
+### Batching
+
+Events are automatically batched to reduce network calls:
+
+```typescript
+// These will be batched together
+litesoc.track('auth.login_failed', { actor: 'user_1' });
+litesoc.track('auth.login_failed', { actor: 'user_2' });
+litesoc.track('auth.login_failed', { actor: 'user_3' });
+
+// Manually flush when needed
+await litesoc.flush();
+
+// Check queue size
+console.log(litesoc.getQueueSize()); // 0
+
+// Clear queue without sending
+litesoc.clearQueue();
+```
+
+### Graceful Shutdown
+
+```typescript
+// Flush remaining events before shutdown
+process.on('beforeExit', async () => {
+  await litesoc.shutdown();
+});
+
+// Or in Next.js API routes
+export async function POST(request: Request) {
+  // ... your logic
+  
+  await litesoc.track('api.request', { ... });
+  await litesoc.flush(); // Ensure events are sent before response
+  
+  return Response.json({ success: true });
+}
+```
+
+## Event Types
+
+### Authentication Events
+
+| Event | Description |
+|-------|-------------|
+| `auth.login_success` | Successful login |
+| `auth.login_failed` | Failed login attempt |
+| `auth.logout` | User logged out |
+| `auth.password_changed` | Password was changed |
+| `auth.password_reset_requested` | Password reset requested |
+| `auth.password_reset_completed` | Password reset completed |
+| `auth.mfa_enabled` | MFA was enabled |
+| `auth.mfa_disabled` | MFA was disabled |
+| `auth.mfa_challenge_success` | MFA challenge passed |
+| `auth.mfa_challenge_failed` | MFA challenge failed |
+| `auth.session_created` | New session created |
+| `auth.session_revoked` | Session was revoked |
+
+### Authorization Events
+
+| Event | Description |
+|-------|-------------|
+| `authz.role_assigned` | Role was assigned |
+| `authz.role_removed` | Role was removed |
+| `authz.role_changed` | Role was changed |
+| `authz.permission_granted` | Permission was granted |
+| `authz.permission_revoked` | Permission was revoked |
+| `authz.access_denied` | Access was denied |
+| `authz.access_granted` | Access was granted |
+
+### Admin Events (Critical)
+
+| Event | Description |
+|-------|-------------|
+| `admin.privilege_escalation` | Privilege escalation detected |
+| `admin.user_impersonation` | Admin impersonated a user |
+| `admin.settings_changed` | System settings changed |
+| `admin.api_key_created` | API key was created |
+| `admin.api_key_revoked` | API key was revoked |
+
+### Data Events
+
+| Event | Description |
+|-------|-------------|
+| `data.export` | Data was exported |
+| `data.import` | Data was imported |
+| `data.bulk_delete` | Bulk data deletion |
+| `data.sensitive_access` | Sensitive data accessed |
+| `data.download` | File was downloaded |
+
+### Security Events
+
+| Event | Description |
+|-------|-------------|
+| `security.suspicious_activity` | Suspicious activity detected |
+| `security.rate_limit_exceeded` | Rate limit exceeded |
+| `security.ip_blocked` | IP was blocked |
+| `security.account_locked` | Account was locked |
+
+## Next.js Integration
+
+### Server Components / API Routes
+
+```typescript
+// app/api/login/route.ts
+import { LiteSOC } from 'litesoc';
+import { headers } from 'next/headers';
+
+const litesoc = new LiteSOC({ 
+  apiKey: process.env.LITESOC_API_KEY!,
+  batching: false, // Disable batching for API routes
+});
+
+export async function POST(request: Request) {
+  const headersList = headers();
+  const userIp = headersList.get('x-forwarded-for')?.split(',')[0] || 
+                 headersList.get('x-real-ip') || 
+                 'unknown';
+  
+  const { email, password } = await request.json();
+  
+  try {
+    // Your login logic...
+    const user = await authenticate(email, password);
+    
+    await litesoc.track('auth.login_success', {
+      actor: { id: user.id, email: user.email },
+      userIp,
+    });
+    
+    return Response.json({ success: true });
+  } catch (error) {
+    await litesoc.track('auth.login_failed', {
+      actor: email,
+      userIp,
+      metadata: { reason: error.message },
+    });
+    
+    return Response.json({ error: 'Invalid credentials' }, { status: 401 });
+  }
+}
+```
+
+### Edge Runtime
+
+```typescript
+// app/api/edge/route.ts
+import { LiteSOC } from 'litesoc';
+
+export const runtime = 'edge';
+
+const litesoc = new LiteSOC({ 
+  apiKey: process.env.LITESOC_API_KEY!,
+  batching: false,
+});
+
+export async function GET(request: Request) {
+  const userIp = request.headers.get('cf-connecting-ip') || 'unknown';
+  
+  await litesoc.track('api.request', {
+    userIp,
+    metadata: { path: '/api/edge' },
+  });
+  
+  return Response.json({ hello: 'world' });
+}
+```
+
+## Express.js Integration
+
+```typescript
+import express from 'express';
+import { LiteSOC } from 'litesoc';
+
+const app = express();
+const litesoc = new LiteSOC({ apiKey: process.env.LITESOC_API_KEY! });
+
+// Middleware to track all requests
+app.use((req, res, next) => {
+  litesoc.track('api.request', {
+    userIp: req.ip,
+    metadata: { 
+      method: req.method, 
+      path: req.path,
+      userAgent: req.get('user-agent'),
+    },
+  });
+  next();
+});
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await litesoc.shutdown();
+  process.exit(0);
+});
+```
+
+## Error Handling
+
+By default, the SDK operates in silent mode - errors are logged but don't crash your application:
+
+```typescript
+// Silent mode (default)
+const litesoc = new LiteSOC({ 
+  apiKey: 'invalid-key',
+  silent: true, // Errors are logged, not thrown
+});
+
+// Strict mode - errors are thrown
+const litesocStrict = new LiteSOC({ 
+  apiKey: 'invalid-key',
+  silent: false, // Errors are thrown
+});
+
+try {
+  await litesocStrict.track('auth.login_failed', { actor: 'user_123' });
+} catch (error) {
+  console.error('Failed to track event:', error);
+}
+```
+
+## TypeScript
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import { 
+  LiteSOC, 
+  LiteSOCOptions,
+  EventType,
+  TrackOptions,
+  Actor,
+  AuthEvent,
+  SecurityEvent,
+  // ... and more
+} from 'litesoc';
+
+// Type-safe event names
+const event: EventType = 'auth.login_failed'; // ✅
+const invalid: EventType = 'invalid'; // ❌ Type error
+
+// Custom events are also supported
+const custom: EventType = 'my.custom_event'; // ✅
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Support
+
+- 📧 Email: support@litesoc.io
+- 📖 Docs: https://litesoc.io/docs
+- 🐛 Issues: https://github.com/litesoc/litesoc-node/issues

package/dist/index.d.mts

@@ -0,0 +1,260 @@
+/**
+ * LiteSOC Node.js/TypeScript SDK
+ * Official SDK for security event tracking and threat detection
+ *
+ * @packageDocumentation
+ */
+/** Fetch function type for cross-environment compatibility */
+type FetchFunction = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/**
+ * Authentication events
+ */
+type AuthEvent = "auth.login_success" | "auth.login_failed" | "auth.logout" | "auth.password_changed" | "auth.password_reset_requested" | "auth.password_reset_completed" | "auth.mfa_enabled" | "auth.mfa_disabled" | "auth.mfa_challenge_success" | "auth.mfa_challenge_failed" | "auth.session_created" | "auth.session_revoked" | "auth.token_refreshed" | "auth.failed";
+/**
+ * User events
+ */
+type UserEvent = "user.created" | "user.updated" | "user.deleted" | "user.email_changed" | "user.email_verified" | "user.phone_changed" | "user.phone_verified" | "user.profile_updated" | "user.avatar_changed" | "user.login_failed" | "user.login.failed";
+/**
+ * Authorization events
+ */
+type AuthzEvent = "authz.role_assigned" | "authz.role_removed" | "authz.role_changed" | "authz.permission_granted" | "authz.permission_revoked" | "authz.access_denied" | "authz.access_granted";
+/**
+ * Admin events
+ */
+type AdminEvent = "admin.privilege_escalation" | "admin.user_impersonation" | "admin.settings_changed" | "admin.api_key_created" | "admin.api_key_revoked" | "admin.invite_sent" | "admin.invite_accepted" | "admin.member_removed";
+/**
+ * Data events
+ */
+type DataEvent = "data.export" | "data.import" | "data.bulk_delete" | "data.bulk_update" | "data.sensitive_access" | "data.download" | "data.upload" | "data.shared" | "data.unshared";
+/**
+ * Security events
+ */
+type SecurityEvent = "security.suspicious_activity" | "security.rate_limit_exceeded" | "security.ip_blocked" | "security.ip_unblocked" | "security.account_locked" | "security.account_unlocked" | "security.brute_force_detected" | "security.impossible_travel" | "security.geo_anomaly";
+/**
+ * API events
+ */
+type ApiEvent = "api.key_used" | "api.rate_limited" | "api.error" | "api.webhook_sent" | "api.webhook_failed";
+/**
+ * Billing events
+ */
+type BillingEvent = "billing.subscription_created" | "billing.subscription_updated" | "billing.subscription_cancelled" | "billing.payment_succeeded" | "billing.payment_failed" | "billing.invoice_created" | "billing.invoice_paid";
+/**
+ * All predefined event types
+ */
+type PredefinedEventType = AuthEvent | UserEvent | AuthzEvent | AdminEvent | DataEvent | SecurityEvent | ApiEvent | BillingEvent;
+/**
+ * Custom event type (string pattern: category.action)
+ */
+type CustomEventType = `${string}.${string}`;
+/**
+ * All supported event types
+ */
+type EventType = PredefinedEventType | CustomEventType;
+/**
+ * Event severity levels
+ */
+type EventSeverity = "low" | "medium" | "high" | "critical";
+/**
+ * Actor information
+ */
+interface Actor {
+    /** Unique identifier for the actor (user ID, API key ID, etc.) */
+    id: string;
+    /** Actor's email address (optional) */
+    email?: string;
+}
+/**
+ * Event metadata (arbitrary key-value pairs)
+ */
+type EventMetadata = Record<string, unknown>;
+/**
+ * Options for tracking an event
+ */
+interface TrackOptions {
+    /** The actor (user) performing the action */
+    actor?: Actor | string;
+    /** Actor's email address (shorthand for actor.email) */
+    actorEmail?: string;
+    /** End-user's IP address (the user making the request) */
+    userIp?: string;
+    /** Event severity (optional, auto-detected for known events) */
+    severity?: EventSeverity;
+    /** Additional metadata for the event */
+    metadata?: EventMetadata;
+    /** Custom timestamp (defaults to now) */
+    timestamp?: Date | string;
+}
+/**
+ * SDK configuration options
+ */
+interface LiteSOCOptions {
+    /** Your LiteSOC API key */
+    apiKey: string;
+    /** API endpoint (defaults to https://www.litesoc.io/api/v1/collect) */
+    endpoint?: string;
+    /** Enable batching (defaults to true) */
+    batching?: boolean;
+    /** Batch size before auto-flush (defaults to 10) */
+    batchSize?: number;
+    /** Batch flush interval in milliseconds (defaults to 5000ms) */
+    flushInterval?: number;
+    /** Enable debug logging (defaults to false) */
+    debug?: boolean;
+    /** Fail silently on errors (defaults to true) */
+    silent?: boolean;
+    /** Custom fetch implementation (for Edge runtimes) */
+    fetch?: FetchFunction;
+}
+/**
+ * LiteSOC SDK for tracking security events
+ *
+ * @example
+ * ```typescript
+ * import { LiteSOC } from 'litesoc';
+ *
+ * const litesoc = new LiteSOC({ apiKey: 'your-api-key' });
+ *
+ * // Track a login failure
+ * await litesoc.track('auth.login_failed', {
+ *   actor: { id: 'user_123', email: 'user@example.com' },
+ *   userIp: '192.168.1.1',
+ *   metadata: { reason: 'invalid_password' }
+ * });
+ *
+ * // Flush remaining events before shutdown
+ * await litesoc.flush();
+ * ```
+ */
+declare class LiteSOC {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly batching;
+    private readonly batchSize;
+    private readonly flushInterval;
+    private readonly debug;
+    private readonly silent;
+    private readonly fetchFn;
+    private queue;
+    private flushTimer;
+    private isFlushing;
+    /**
+     * Create a new LiteSOC SDK instance
+     *
+     * @param options - SDK configuration options
+     * @throws Error if apiKey is not provided
+     */
+    constructor(options: LiteSOCOptions);
+    /**
+     * Track a security event
+     *
+     * @param eventName - The event type (e.g., 'auth.login_failed')
+     * @param options - Event options including actor, IP, and metadata
+     * @returns Promise that resolves when the event is queued or sent
+     *
+     * @example
+     * ```typescript
+     * // Track with full options
+     * await litesoc.track('auth.login_failed', {
+     *   actor: { id: 'user_123', email: 'user@example.com' },
+     *   userIp: '192.168.1.1',
+     *   metadata: { reason: 'invalid_password', attempts: 3 }
+     * });
+     *
+     * // Track with shorthand actor
+     * await litesoc.track('user.created', {
+     *   actor: 'user_456',
+     *   actorEmail: 'newuser@example.com'
+     * });
+     * ```
+     */
+    track(eventName: EventType, options?: TrackOptions): Promise<void>;
+    /**
+     * Flush all queued events to the server
+     *
+     * @returns Promise that resolves when all events are sent
+     *
+     * @example
+     * ```typescript
+     * // Flush before application shutdown
+     * process.on('beforeExit', async () => {
+     *   await litesoc.flush();
+     * });
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Get the current queue size
+     *
+     * @returns Number of events in the queue
+     */
+    getQueueSize(): number;
+    /**
+     * Clear all queued events without sending
+     */
+    clearQueue(): void;
+    /**
+     * Shutdown the SDK gracefully
+     * Flushes remaining events and clears timers
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Track a login failure event
+     */
+    trackLoginFailed(actorId: string, options?: Omit<TrackOptions, "actor">): Promise<void>;
+    /**
+     * Track a login success event
+     */
+    trackLoginSuccess(actorId: string, options?: Omit<TrackOptions, "actor">): Promise<void>;
+    /**
+     * Track a privilege escalation event
+     */
+    trackPrivilegeEscalation(actorId: string, options?: Omit<TrackOptions, "actor">): Promise<void>;
+    /**
+     * Track a sensitive data access event
+     */
+    trackSensitiveAccess(actorId: string, resource: string, options?: Omit<TrackOptions, "actor">): Promise<void>;
+    /**
+     * Track a bulk delete event
+     */
+    trackBulkDelete(actorId: string, recordCount: number, options?: Omit<TrackOptions, "actor">): Promise<void>;
+    /**
+     * Track a role change event
+     */
+    trackRoleChanged(actorId: string, oldRole: string, newRole: string, options?: Omit<TrackOptions, "actor">): Promise<void>;
+    /**
+     * Track an access denied event
+     */
+    trackAccessDenied(actorId: string, resource: string, options?: Omit<TrackOptions, "actor">): Promise<void>;
+    /**
+     * Schedule a flush after the flush interval
+     */
+    private scheduleFlush;
+    /**
+     * Send events to the LiteSOC API
+     */
+    private sendEvents;
+    /**
+     * Handle errors based on silent mode
+     */
+    private handleError;
+    /**
+     * Log debug messages
+     */
+    private log;
+}
+/**
+ * Create a new LiteSOC SDK instance
+ *
+ * @param options - SDK configuration options
+ * @returns LiteSOC SDK instance
+ *
+ * @example
+ * ```typescript
+ * import { createLiteSOC } from 'litesoc';
+ *
+ * const litesoc = createLiteSOC({ apiKey: 'your-api-key' });
+ * ```
+ */
+declare function createLiteSOC(options: LiteSOCOptions): LiteSOC;
+
+export { type Actor, type AdminEvent, type ApiEvent, type AuthEvent, type AuthzEvent, type BillingEvent, type CustomEventType, type DataEvent, type EventMetadata, type EventSeverity, type EventType, LiteSOC, type LiteSOCOptions, type PredefinedEventType, type SecurityEvent, type TrackOptions, type UserEvent, createLiteSOC, LiteSOC as default };