Authentication & Security documentation

packages/plugin-nft-collections/README.md

@@ -1078,3 +1078,285 @@ graph TD
     L --> P
     M --> P
 ```
+
+## Authentication & Security
+
+### API Key Management
+
+```typescript
+// Configure API keys with rotation and fallback
+const apiConfig = plugin.auth.configureAPI({
+    primary: {
+        key: process.env.PRIMARY_API_KEY,
+        rotationSchedule: "0 0 * * *", // Daily rotation
+        rotationCallback: async (oldKey) => {
+            await notifyKeyExpiry(oldKey);
+        },
+    },
+    fallback: {
+        key: process.env.FALLBACK_API_KEY,
+        useCondition: (error) => error.status === 429 || error.status === 503,
+    },
+    rotation: {
+        enabled: true,
+        interval: 86400000, // 24 hours in ms
+        strategy: "gradual", // or "immediate"
+    },
+});
+
+// Key rotation handlers
+plugin.auth.onKeyRotation(async (newKey, oldKey) => {
+    await updateKeyInVault(newKey);
+    await invalidateOldKey(oldKey);
+});
+
+// Automatic key validation
+await plugin.auth.validateKeys({
+    checkInterval: 3600000, // 1 hour
+    healthEndpoint: "/health",
+    timeout: 5000,
+});
+```
+
+### Rate Limiting
+
+```typescript
+// Configure rate limits
+const rateLimiter = plugin.security.configureRateLimits({
+    global: {
+        maxRequests: 1000,
+        windowMs: 60000, // 1 minute
+        retryAfter: 60000,
+    },
+    endpoints: {
+        "/collections": {
+            maxRequests: 100,
+            windowMs: 60000,
+            retryAfter: 30000,
+        },
+        "/market-data": {
+            maxRequests: 50,
+            windowMs: 60000,
+            retryAfter: 60000,
+        },
+    },
+    strategies: {
+        type: "sliding-window",
+        errorHandling: "queue", // or "reject"
+    },
+});
+
+// Custom rate limit handlers
+rateLimiter.onLimitReached(async (context) => {
+    await notifyRateLimitExceeded(context);
+    return plugin.security.getBackoffStrategy(context);
+});
+
+// Distributed rate limiting with Redis
+const distributedLimiter = plugin.security.createDistributedRateLimiter({
+    redis: {
+        host: process.env.REDIS_HOST,
+        port: 6379,
+        password: process.env.REDIS_PASSWORD,
+    },
+    sync: {
+        interval: 1000,
+        strategy: "eventual-consistency",
+    },
+});
+```
+
+### Security Features
+
+```typescript
+// Enable security features
+const security = plugin.security.configure({
+    encryption: {
+        algorithm: "aes-256-gcm",
+        keyRotation: true,
+        rotationInterval: 7776000000, // 90 days
+    },
+    authentication: {
+        type: "jwt",
+        expiresIn: "24h",
+        refreshToken: true,
+    },
+    headers: {
+        helmet: true,
+        cors: {
+            origin: ["https://yourdomain.com"],
+            methods: ["GET", "POST"],
+        },
+    },
+});
+
+// Request signing
+const signedRequest = plugin.security.signRequest({
+    method: "POST",
+    url: "/api/v1/trades",
+    body: tradeData,
+    nonce: Date.now(),
+    expiry: "5m",
+});
+
+// Payload encryption
+const encryptedData = await plugin.security.encryptPayload(sensitiveData, {
+    algorithm: "aes-256-gcm",
+    keyId: "current",
+    metadata: {
+        purpose: "api-communication",
+    },
+});
+```
+
+### Access Control
+
+```typescript
+// Configure access control
+const accessControl = plugin.security.configureAccess({
+    roles: {
+        admin: {
+            permissions: ["read", "write", "delete"],
+            rateLimit: { multiplier: 2 },
+        },
+        user: {
+            permissions: ["read"],
+            rateLimit: { multiplier: 1 },
+        },
+    },
+    resources: {
+        collections: ["read", "write"],
+        trades: ["read", "write", "delete"],
+        analytics: ["read"],
+    },
+});
+
+// Role-based middleware
+const authMiddleware = plugin.security.createAuthMiddleware({
+    validateToken: true,
+    checkPermissions: true,
+    auditLog: true,
+});
+
+// IP allowlisting
+const ipFilter = plugin.security.createIPFilter({
+    allowlist: ["192.168.1.0/24"],
+    denylist: ["10.0.0.0/8"],
+    mode: "strict",
+});
+```
+
+### Audit Logging
+
+```typescript
+// Configure audit logging
+const auditLogger = plugin.security.configureAuditLog({
+    storage: {
+        type: "elasticsearch",
+        config: {
+            node: process.env.ELASTICSEARCH_URL,
+            index: "nft-audit-logs",
+        },
+    },
+    retention: {
+        duration: "90d",
+        archival: true,
+    },
+    events: {
+        "api.request": true,
+        "auth.login": true,
+        "data.modification": true,
+    },
+});
+
+// Log security events
+await auditLogger.log({
+    action: "api.request",
+    actor: "user-123",
+    resource: "collection-456",
+    details: {
+        method: "GET",
+        path: "/api/v1/collections",
+        status: 200,
+    },
+});
+
+// Query audit logs
+const auditTrail = await auditLogger.query({
+    timeRange: {
+        start: "2024-01-01",
+        end: "2024-01-07",
+    },
+    filters: {
+        action: ["api.request", "auth.login"],
+        actor: "user-123",
+    },
+});
+```
+
+### Security Configuration
+
+```typescript
+interface SecurityConfig {
+    api: {
+        keys: {
+            rotation: {
+                enabled: boolean;
+                interval: number;
+                strategy: "gradual" | "immediate";
+            };
+            validation: {
+                interval: number;
+                timeout: number;
+            };
+        };
+        rateLimit: {
+            global: RateLimitConfig;
+            endpoints: Record<string, RateLimitConfig>;
+            distributed: boolean;
+        };
+    };
+    encryption: {
+        algorithm: string;
+        keyRotation: boolean;
+        rotationInterval: number;
+    };
+    access: {
+        roles: Record<string, RoleConfig>;
+        resources: Record<string, string[]>;
+        audit: {
+            enabled: boolean;
+            retention: string;
+        };
+    };
+}
+```
+
+### Security Architecture
+
+```mermaid
+graph TD
+    A[Plugin Core] --> B[Auth Manager]
+    A --> C[Rate Limiter]
+    A --> D[Security Manager]
+
+    B --> E[Key Rotation]
+    B --> F[Key Validation]
+
+    C --> G[Request Counter]
+    C --> H[Rate Rules]
+
+    D --> I[Encryption]
+    D --> J[Access Control]
+    D --> K[Audit Logger]
+
+    E --> L[Key Storage]
+    F --> L
+
+    G --> M[Redis Cache]
+    H --> M
+
+    I --> N[Key Management]
+    J --> O[Role Manager]
+    K --> P[Log Storage]
+```