@engjts/nexus 0.1.0

package/dist/security/sanitization.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Input Sanitization Middleware
+ *
+ * Automatically sanitizes request inputs to prevent common attacks
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeInput = sanitizeInput;
+exports.strictSanitization = strictSanitization;
+exports.lenientSanitization = lenientSanitization;
+const adapter_1 = require("./adapter");
+/**
+ * Create input sanitization middleware
+ *
+ * @example
+ * ```ts
+ * app.use(sanitizeInput({
+ *   fields: ['body', 'query', 'params'],
+ *   strict: false
+ * }));
+ * ```
+ */
+function sanitizeInput(config = {}, adapter) {
+    const adapterInstance = adapter || new adapter_1.DefaultSanitizationAdapter();
+    const fields = config.fields || ['body', 'query', 'params'];
+    const enabled = config.enabled !== false;
+    return async (ctx, next) => {
+        if (!enabled) {
+            return next(ctx);
+        }
+        // Sanitize specified fields
+        for (const field of fields) {
+            if (field in ctx && ctx[field]) {
+                try {
+                    ctx[field] = adapterInstance.sanitize(ctx[field], config);
+                }
+                catch (error) {
+                    // In strict mode, adapter throws on malicious input
+                    throw new Error(`Malicious input detected in ${field}`);
+                }
+            }
+        }
+        return next(ctx);
+    };
+}
+/**
+ * Strict sanitization - throws on malicious input
+ */
+function strictSanitization(customConfig = {}) {
+    return sanitizeInput({
+        fields: ['body', 'query', 'params'],
+        strict: true,
+        ...customConfig
+    });
+}
+/**
+ * Lenient sanitization - silently removes malicious content
+ */
+function lenientSanitization(customConfig = {}) {
+    return sanitizeInput({
+        fields: ['body', 'query', 'params'],
+        strict: false,
+        ...customConfig
+    });
+}
+//# sourceMappingURL=sanitization.js.map

package/dist/security/sanitization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitization.js","sourceRoot":"","sources":["../../src/security/sanitization.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAkBH,sCA8BC;AAKD,gDAMC;AAKD,kDAMC;AAjED,uCAAuD;AAEvD;;;;;;;;;;GAUG;AACH,SAAgB,aAAa,CACzB,SAA6B,EAAE,EAC/B,OAA6B;IAE7B,MAAM,eAAe,GAAG,OAAO,IAAI,IAAI,oCAA0B,EAAE,CAAC;IACpE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,KAAK,KAAK,CAAC;IAEzC,OAAO,KAAK,EAAE,GAAY,EAAE,IAAU,EAAE,EAAE;QACtC,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QAED,4BAA4B;QAC5B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACzB,IAAI,KAAK,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC7B,IAAI,CAAC;oBACA,GAAW,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,QAAQ,CAC1C,GAAG,CAAC,KAAK,CAAC,EACV,MAAM,CACT,CAAC;gBACN,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACb,oDAAoD;oBACpD,MAAM,IAAI,KAAK,CAAC,+BAA+B,KAAK,EAAE,CAAC,CAAC;gBAC5D,CAAC;YACL,CAAC;QACL,CAAC;QAED,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC,CAAC;AACN,CAAC;AAED;;GAEG;AACH,SAAgB,kBAAkB,CAAC,eAA4C,EAAE;IAC7E,OAAO,aAAa,CAAC;QACjB,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC;QACnC,MAAM,EAAE,IAAI;QACZ,GAAG,YAAY;KAClB,CAAC,CAAC;AACP,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB,CAAC,eAA4C,EAAE;IAC9E,OAAO,aAAa,CAAC;QACjB,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC;QACnC,MAAM,EAAE,KAAK;QACb,GAAG,YAAY;KAClB,CAAC,CAAC;AACP,CAAC"}

package/dist/security/types.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Security Layer Type Definitions
+ *
+ * Core types for security features including auth, RBAC, rate limiting
+ */
+import type { Context } from '../core/types';
+/**
+ * User type for authenticated contexts
+ */
+export interface User {
+    id: string | number;
+    email?: string;
+    username?: string;
+    roles?: string[];
+    permissions?: string[];
+    [key: string]: any;
+}
+/**
+ * Context with authenticated user
+ */
+export interface AuthContext extends Context {
+    user: User;
+}
+/**
+ * Security headers configuration
+ */
+export interface SecurityHeadersConfig {
+    /** Preset mode: 'strict' | 'moderate' | 'loose' */
+    mode?: 'strict' | 'moderate' | 'loose';
+    /** Custom headers to add/override */
+    customHeaders?: Record<string, string>;
+    /** Content Security Policy configuration */
+    csp?: {
+        directives?: Record<string, string[]>;
+        reportUri?: string;
+        reportOnly?: boolean;
+    };
+    /** Enable auto-nonce generation for CSP */
+    autoNonce?: boolean;
+}
+/**
+ * Sanitization pattern configuration
+ */
+export interface SanitizationPattern {
+    name: string;
+    pattern: RegExp;
+    replacement?: string;
+}
+/**
+ * Input sanitization configuration
+ */
+export interface SanitizationConfig {
+    /** Enable auto-sanitization */
+    enabled?: boolean;
+    /** Custom patterns to detect */
+    patterns?: SanitizationPattern[];
+    /** Fields to sanitize (body, query, params) */
+    fields?: ('body' | 'query' | 'params')[];
+    /** Throw error on detection vs silent sanitization */
+    strict?: boolean;
+}
+/**
+ * JWT authentication configuration
+ */
+export interface JWTConfig {
+    /** Secret key for signing */
+    secret: string;
+    /** Algorithm (default: HS256) */
+    algorithm?: 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512';
+    /** Token expiration */
+    expiresIn?: string | number;
+    /** Refresh token configuration */
+    refresh?: {
+        enabled: boolean;
+        expiresIn?: string | number;
+        rotateSecret?: boolean;
+    };
+    /** Token extraction strategy */
+    getToken?: (ctx: Context) => string | null;
+}
+/**
+ * OAuth configuration (placeholder for future implementation)
+ */
+export interface OAuthConfig {
+    provider: 'google' | 'github' | 'facebook' | string;
+    clientId: string;
+    clientSecret: string;
+    callbackUrl: string;
+    scope?: string[];
+}
+/**
+ * Session configuration (placeholder for future implementation)
+ */
+export interface SessionConfig {
+    store: 'memory' | 'redis' | string;
+    secret: string;
+    cookie?: {
+        secure?: boolean;
+        httpOnly?: boolean;
+        sameSite?: 'strict' | 'lax' | 'none';
+        maxAge?: number;
+    };
+}
+/**
+ * Authentication strategies
+ */
+export interface AuthStrategies {
+    jwt?: JWTConfig;
+    oauth?: OAuthConfig;
+    session?: SessionConfig;
+}
+/**
+ * Role definition for RBAC
+ */
+export interface RoleDefinition {
+    name: string;
+    permissions: string[];
+    inherits?: string[];
+}
+/**
+ * Permission check result
+ */
+export interface PermissionCheckResult {
+    allowed: boolean;
+    missing?: string[];
+}
+/**
+ * Rate limit configuration
+ */
+export interface RateLimitConfig {
+    /** Time window in milliseconds or string format (e.g., '15m', '1h') */
+    window: number | string;
+    /** Maximum requests per window */
+    max: number;
+    /** Storage backend */
+    store?: 'memory' | 'redis' | string;
+    /** Key generator function */
+    keyGenerator?: (ctx: Context) => string;
+    /** Per-route limits */
+    routes?: Record<string, {
+        max: number;
+        window: number | string;
+    }>;
+    /** Suspicious behavior detection */
+    suspicious?: {
+        failedLogins?: {
+            max: number;
+            window: number | string;
+            action: 'captcha' | 'block' | 'throttle';
+        };
+        rapidRequests?: {
+            threshold: number;
+            window: number | string;
+            action: 'throttle' | 'block';
+        };
+    };
+    /** Message to send when rate limited */
+    message?: string;
+    /** Status code to send when rate limited */
+    statusCode?: number;
+}
+/**
+ * Rate limit info attached to context
+ */
+export interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: number;
+    retryAfter?: number;
+}
+/**
+ * CSRF protection configuration
+ */
+export interface CSRFConfig {
+    /** Enable automatic token generation and validation */
+    auto?: boolean;
+    /** Cookie configuration */
+    cookie?: {
+        name?: string;
+        sameSite?: 'strict' | 'lax' | 'none';
+        secure?: boolean;
+        httpOnly?: boolean;
+    };
+    /** Token field name in body */
+    tokenField?: string;
+    /** Header field name */
+    headerField?: string;
+    /** Methods to exclude from CSRF check */
+    excludeMethods?: string[];
+    /** Routes to exclude from CSRF check */
+    excludeRoutes?: string[];
+    /** Token length */
+    tokenLength?: number;
+}
+/**
+ * Security event for logging/monitoring
+ */
+export interface SecurityEvent {
+    type: 'auth_failed' | 'rate_limit' | 'csrf_failed' | 'xss_detected' | 'sql_injection_detected';
+    timestamp: number;
+    ip: string;
+    path: string;
+    details?: any;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/security/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/security/types.ts"],"names":[],"mappings":"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"}

package/dist/security/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Security Layer Type Definitions
+ *
+ * Core types for security features including auth, RBAC, rate limiting
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/security/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/security/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/dist/security/utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Security Utility Helpers
+ *
+ * Helper functions for working with security features
+ */
+import type { Context } from '../core/types';
+/**
+ * Get header value as string (handles string | string[] | undefined)
+ */
+export declare function getHeader(ctx: Context, name: string): string | null;
+/**
+ * Get all header values as array
+ */
+export declare function getHeaderValues(ctx: Context, name: string): string[];
+/**
+ * Set response header safely
+ */
+export declare function setResponseHeader(headers: Record<string, string>, name: string, value: string): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/security/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/security/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYnE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAYpE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACd,IAAI,CAEN"}

package/dist/security/utils.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Security Utility Helpers
+ *
+ * Helper functions for working with security features
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHeader = getHeader;
+exports.getHeaderValues = getHeaderValues;
+exports.setResponseHeader = setResponseHeader;
+/**
+ * Get header value as string (handles string | string[] | undefined)
+ */
+function getHeader(ctx, name) {
+    const value = ctx.headers[name.toLowerCase()];
+    if (!value) {
+        return null;
+    }
+    if (Array.isArray(value)) {
+        return value[0] || null;
+    }
+    return value;
+}
+/**
+ * Get all header values as array
+ */
+function getHeaderValues(ctx, name) {
+    const value = ctx.headers[name.toLowerCase()];
+    if (!value) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value;
+    }
+    return [value];
+}
+/**
+ * Set response header safely
+ */
+function setResponseHeader(headers, name, value) {
+    headers[name] = value;
+}
+//# sourceMappingURL=utils.js.map

package/dist/security/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/security/utils.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAOH,8BAYC;AAKD,0CAYC;AAKD,8CAMC;AA3CD;;GAEG;AACH,SAAgB,SAAS,CAAC,GAAY,EAAE,IAAY;IAChD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAE9C,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAC5B,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,GAAY,EAAE,IAAY;IACtD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAE9C,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,OAAO,EAAE,CAAC;IACd,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAC7B,OAA+B,EAC/B,IAAY,EACZ,KAAa;IAEb,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;AAC1B,CAAC"}

package/documentation/01-getting-started.md

@@ -0,0 +1,240 @@
+# Getting Started with Nexus Framework
+
+## Installation
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0.0
+
+### Setup
+
+1. **Clone or initialize your project**
+
+```bash
+mkdir my-nexus-app
+cd my-nexus-app
+npm init -y
+```
+
+2. **Install dependencies**
+
+```bash
+npm install typescript @types/node zod
+npm install -D ts-node
+```
+
+3. **Configure TypeScript**
+
+Create `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+## Your First Application
+
+### Basic Server
+
+Create `src/index.ts`:
+
+```typescript
+import { createApp } from './nexus';
+
+const app = createApp();
+
+app.get('/hello', async (ctx) => {
+  return { message: 'Hello, Nexus!' };
+});
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+### Run the Application
+
+```bash
+npx ts-node src/index.ts
+```
+
+Visit `http://localhost:3000/hello` to see your first response!
+
+## Core Concepts
+
+### 1. Unified Context
+
+Unlike Express.js which uses separate `req` and `res` objects, Nexus uses a single **Context** object:
+
+```typescript
+app.get('/user', async (ctx) => {
+  // Access request data
+  const userId = ctx.query.id;
+  const token = ctx.headers.authorization;
+  
+  // Return response (auto-converted to JSON)
+  return { userId, authenticated: !!token };
+});
+```
+
+### 2. Async-First
+
+All handlers are async functions with **automatic error handling**:
+
+```typescript
+app.get('/user/:id', async (ctx) => {
+  // Errors are automatically caught
+  const user = await database.getUser(ctx.params.id);
+  return { user };
+});
+```
+
+No need for try-catch or `next(error)` calls!
+
+### 3. Type Safety
+
+Full TypeScript support with **type inference**:
+
+```typescript
+import { z } from 'zod';
+
+app.post('/users', {
+  schema: {
+    body: z.object({
+      name: z.string(),
+      email: z.string().email()
+    })
+  },
+  handler: async (ctx) => {
+    // ctx.body is typed as { name: string, email: string }
+    const user = await createUser(ctx.body);
+    return { user };
+  }
+});
+```
+
+## HTTP Methods
+
+Nexus supports all standard HTTP methods:
+
+```typescript
+app.get('/resource', async (ctx) => { /* ... */ });
+app.post('/resource', async (ctx) => { /* ... */ });
+app.put('/resource/:id', async (ctx) => { /* ... */ });
+app.patch('/resource/:id', async (ctx) => { /* ... */ });
+app.delete('/resource/:id', async (ctx) => { /* ... */ });
+```
+
+## Response Types
+
+### JSON (Default)
+
+```typescript
+app.get('/data', async (ctx) => {
+  return { key: 'value' }; // Auto-serialized to JSON
+});
+```
+
+### HTML
+
+```typescript
+app.get('/page', async (ctx) => {
+  return ctx.html('<h1>Welcome</h1>');
+});
+```
+
+### Text
+
+```typescript
+app.get('/text', async (ctx) => {
+  return ctx.text('Plain text response');
+});
+```
+
+### Redirect
+
+```typescript
+app.get('/old', async (ctx) => {
+  return ctx.redirect('/new', 301);
+});
+```
+
+### Stream
+
+```typescript
+import { createReadStream } from 'fs';
+
+app.get('/file', async (ctx) => {
+  const stream = createReadStream('./large-file.dat');
+  return ctx.stream(stream);
+});
+```
+
+## Project Structure
+
+Recommended structure for your application:
+
+```
+my-app/
+├── src/
+│   ├── index.ts           # Application entry point
+│   ├── routes/            # Route handlers
+│   │   ├── users.ts
+│   │   └── posts.ts
+│   ├── middleware/        # Custom middleware
+│   │   └── auth.ts
+│   └── config/            # Configuration
+│       └── app.ts
+├── package.json
+└── tsconfig.json
+```
+
+## Next Steps
+
+- 📖 [Context Documentation](./02-context.md) - Learn about the Context API
+- 🛤️ [Routing Guide](./03-routing.md) - Advanced routing patterns
+- 🔌 [Middleware System](./04-middleware.md) - Create custom middleware
+- ✅ [Validation](./05-validation.md) - Schema validation with Zod
+- ⚡ [Performance](./07-performance.md) - Optimization features
+
+## Quick Reference
+
+```typescript
+import { createApp, z, logger, cors } from './nexus';
+
+const app = createApp({
+  debug: true,
+  contextPoolSize: 100
+});
+
+// Global middleware
+app.use(logger());
+app.use(cors());
+
+// Routes
+app.get('/path', handler);
+app.post('/path', { schema, handler });
+app.route({ method, path, handler, middlewares, schema });
+
+// Error handling
+app.onError((error, ctx) => {
+  return { statusCode: 500, body: 'Error' };
+});
+
+// Start server
+app.listen(3000);
+```
+
+---
+
+**Need help?** Check the [API Reference](./09-api-reference.md) for detailed documentation.