npm package: @iota-big3/sdk-auth
Description: Enterprise-grade authentication with Zero Trust architecture
Author: IOTA Big3 Team
Latest version: 1.0.0

# @iota-big3/sdk-auth

Enterprise-grade authentication with Zero Trust architecture for the IOTA Big3 SDK.

## Features

- 🔐 **JWT Authentication** - Secure token-based authentication
- 🔑 **OAuth 2.0 / OIDC** - Support for Google, Microsoft, Okta, and more
- 🏢 **SAML 2.0** - Enterprise SSO integration
- 📱 **Multi-Factor Authentication** - TOTP, SMS, Email, WebAuthn
- 🛡️ **Zero Trust Security** - Continuous verification and risk scoring
- 👥 **RBAC & ABAC** - Role and attribute-based access control
- 🔒 **API Key Management** - Secure API key generation and validation
- 📊 **Audit Trail** - Comprehensive authentication event logging
- ⚡ **High Performance** - Redis-backed sessions and caching
- 🔄 **Token Refresh** - Automatic token renewal

## Installation

```bash
npm install @iota-big3/sdk-auth @iota-big3/sdk-core
```

## SDK Integrations

The auth SDK integrates seamlessly with other IOTA Big3 SDKs to provide a complete authentication solution:

### Database Integration (@iota-big3/sdk-database)

Store users, sessions, and auth data persistently:

```typescript
import { AuthManager } from "@iota-big3/sdk-auth";

const auth = new AuthManager({
  jwtSecret: "your-secret",
  database: {
    type: "postgres",
    host: "localhost",
    database: "myapp",
    user: "dbuser",
    password: "dbpass",
  },
});

// Auth data is now persisted to database
// Falls back to in-memory storage if database is unavailable
```

### Event Bus Integration (@iota-big3/sdk-events)

Emit and listen to authentication events across your application:

```typescript
import { EventBus } from "@iota-big3/sdk-events";
import { AuthManager } from "@iota-big3/sdk-auth";

const eventBus = new EventBus();
const auth = new AuthManager({
  jwtSecret: "your-secret",
  eventBus,
});

// Listen to auth events
eventBus.on("auth:user.created", (event) => {
  console.log("New user:", event.userId, event.email);
});

eventBus.on("auth:login.success", (event) => {
  console.log("User logged in:", event.userId, event.method);
});

eventBus.on("auth:security.anomaly_detected", (event) => {
  console.log("Security alert:", event.type, event.riskScore);
});

// Auth SDK also listens to events from other SDKs
eventBus.emit("security:threat.detected", {
  userId: "user123",
  threatType: "credential_stuffing",
  severity: "critical",
});
// This will automatically lock the user account
```

### Logging Integration (@iota-big3/sdk-observability)

Comprehensive logging for security and debugging:

```typescript
const auth = new AuthManager({
  jwtSecret: "your-secret",
  logging: {
    level: "info",
    format: "json",
    enabled: true,
  },
});

// All auth operations are now logged
// Includes structured logging for security events
```

### Cache Integration (@iota-big3/sdk-performance)

High-performance session management and rate limiting:

```typescript
const auth = new AuthManager({
  jwtSecret: "your-secret",
  cache: {
    type: "redis",
    redis: {
      host: "localhost",
      port: 6379,
    },
  },
});

// Sessions are cached in Redis for fast access
// Rate limiting uses Redis for distributed tracking
```

### Combined Integration Example

```typescript
import { EventBus } from "@iota-big3/sdk-events";
import { AuthManager } from "@iota-big3/sdk-auth";

// Initialize with all integrations
const eventBus = new EventBus();

const auth = new AuthManager({
  jwtSecret: process.env.JWT_SECRET,

  // Database for persistence
  database: {
    type: "postgres",
    host: process.env.DB_HOST,
    database: process.env.DB_NAME,
  },

  // Event bus for real-time events
  eventBus,

  // Logging for monitoring
  logging: {
    level: "info",
    enabled: true,
  },

  // Cache for performance
  cache: {
    type: "redis",
    redis: {
      host: process.env.REDIS_HOST,
    },
  },

  // Enable features
  enableRateLimiting: true,
  enableRefreshTokens: true,
});

// Set up cross-SDK event handling
eventBus.on("user:profile.updated", async (event) => {
  // Sync user metadata in auth system
  await auth.updateUserMetadata(event.userId, event.changes);
});

eventBus.on("security:anomaly.detected", async (event) => {
  if (event.riskScore > 90) {
    // Force re-authentication for high-risk sessions
    await auth.requireReAuthentication(event.userId);
  }
});

// Auth events are automatically emitted
const user = await auth.registerUser({
  email: "user@example.com",
  password: "SecurePass123!",
});
// Emits: auth:user.created

const result = await auth.authenticate("user@example.com", "SecurePass123!");
// Emits: auth:login.success, auth:session.created
```

### Event Reference

Auth SDK emits the following events:

- `auth:user.created` - New user registered
- `auth:user.updated` - User profile updated
- `auth:user.deleted` - User account deleted
- `auth:user.locked` - User account locked
- `auth:login.success` - Successful authentication
- `auth:login.failed` - Failed authentication attempt
- `auth:logout.success` - User logged out
- `auth:mfa.enabled` - MFA method enabled
- `auth:mfa.verified` - MFA challenge completed
- `auth:security.anomaly_detected` - Suspicious activity detected
- `auth:security.access_blocked` - Access blocked by security rules
- `auth:permission.granted` - Permission check passed
- `auth:permission.denied` - Permission check failed
- `auth:session.created` - New session started
- `auth:session.terminated` - Session ended

Auth SDK listens to these external events:

- `user:account.deleted` - Clean up auth data when user deleted
- `security:threat.detected` - Lock account on critical threats
- `security:anomaly.detected` - Force re-auth on high risk
- `compliance:audit.required` - Enable detailed audit logging

## Quick Start

```typescript
import { AuthManager, createDefaultAuthConfig } from "@iota-big3/sdk-auth";
import { SDK } from "@iota-big3/sdk-core";

// Initialize SDK
const sdk = new SDK({
  serviceName: "my-service",
  industry: "education",
});

// Create auth configuration
const authConfig = createDefaultAuthConfig();

// Initialize AuthManager
const auth = new AuthManager(authConfig, sdk);

// Authenticate user
const tokens = await auth.authenticate("user@example.com", "password");
console.log(tokens.accessToken);

// Validate token
const payload = await auth.validateToken(tokens.accessToken);
console.log(payload.email);

// Check permissions
const user = await auth.findUserById(payload.sub);
const canRead = auth.hasPermission(user, "documents", "read");

// NEW Phase 2g Features:

// 1. Role-based permissions
auth.setRolePermissions({
  admin: ["*:*"],
  editor: ["read:*", "write:documents"],
  viewer: ["read:documents"],
});

// 2. API Key Management
const apiKey = await auth.createAPIKey(user.id, "Production API", {
  permissions: ["read:api", "write:api"],
  expiresIn: 30 * 24 * 60 * 60, // 30 days
});

// 3. OAuth Integration
import { GoogleOAuthProvider } from "@iota-big3/sdk-auth";
const googleAuth = new GoogleOAuthProvider(clientId, clientSecret);

// 4. Express Middleware
import { requireAuth, requirePermissions } from "@iota-big3/sdk-auth";
app.get("/api/secure", requireAuth(auth), handler);
app.post("/api/admin", requirePermissions(auth, "admin:*"), handler);
```

## Integration with Other SDKs

### With sdk-database

```typescript
import { AuthManager } from "@iota-big3/sdk-auth";

const auth = new AuthManager({
  jwtSecret: "your-secret",
  database: {
    type: "postgres",
    host: "localhost",
    database: "myapp",
    user: "dbuser",
    password: "dbpass",
  },
});

// Auth data will be persisted to database automatically
```

### With sdk-events

```typescript
import { EventBus } from "@iota-big3/sdk-events";
import { AuthManager } from "@iota-big3/sdk-auth";

const eventBus = new EventBus();
const auth = new AuthManager(config, eventBus);

// Listen to auth events
eventBus.on("auth:user.registered", (event) => {
  console.log("New user registered:", event.data.userId);
});

eventBus.on("auth:user.authenticated", (event) => {
  console.log("User logged in:", event.data.userId);
});
```

### With sdk-performance (Caching)

```typescript
const auth = new AuthManager({
  jwtSecret: "your-secret",
  cache: {
    type: "redis",
    host: "localhost",
    port: 6379,
    ttl: 3600, // 1 hour
  },
});

// Sessions and rate limiting will use Redis cache
```

### Redis Session Management

```typescript
// When Redis is configured, AuthManager automatically:
// 1. Stores sessions in Redis with TTL
// 2. Uses Redis for distributed rate limiting
// 3. Enables session sharing across instances

const auth = new AuthManager({
  jwtSecret: "your-secret",
  cache: {
    type: "redis",
    host: process.env.REDIS_HOST,
    port: 6379,
    password: process.env.REDIS_PASSWORD,
  },
});

// Sessions are automatically synced across all instances
// Rate limiting works across distributed systems
// Perfect for microservices and serverless deployments
```

### Enhanced Rate Limiting

The SDK now includes advanced rate limiting features:

```typescript
// Configure enhanced rate limiting
const auth = new AuthManager({
  jwtSecret: "your-secret",
  enableRateLimiting: true,
  rateLimitConfig: {
    windowMs: 15 * 60 * 1000, // 15 minutes
    maxRequests: 100,
    strategy: "sliding-window", // 'fixed-window' | 'sliding-window'
    headers: true, // Include rate limit headers
    keyGenerator: (identifier, context) => {
      // Custom key generation
      if (context?.userId) {
        return `user:${context.userId}:${context.endpoint}`;
      }
      return `ip:${context.ipAddress}:${context.endpoint}`;
    },
  },
});
```

#### Rate Limiting Strategies

1. **Fixed Window**: Traditional approach, resets at fixed intervals
2. **Sliding Window**: More accurate, prevents burst attacks at window boundaries

#### Rate Limiting Middleware

```typescript
import {
  createRateLimitMiddleware,
  createAuthenticatedRateLimitMiddleware,
  createApiKeyRateLimitMiddleware,
} from "@iota-big3/sdk-auth";

// IP-based rate limiting
app.use(createRateLimitMiddleware(auth));

// User-based rate limiting
app.use(
  "/api/protected",
  createAuthenticatedRateLimitMiddleware(auth, {
    skip: (req) => req.user?.roles?.includes("admin"), // Skip for admins
  })
);

// API key rate limiting
app.use("/api/v1", createApiKeyRateLimitMiddleware(auth));
```

#### Response Headers

When rate limiting is enabled with headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1234567890
Retry-After: 60 (only when rate limited)
```

#### Custom Rate Limit Context

```typescript
const rateLimitResult = await auth.checkRateLimit("identifier", {
  ipAddress: "192.168.1.1",
  userId: "user123",
  endpoint: "/api/data",
  method: "POST",
});

console.log(rateLimitResult.info); // { limit, remaining, resetAt, retryAfter }
```

### With sdk-observability

```typescript
const auth = new AuthManager({
  jwtSecret: "your-secret",
  logging: {
    level: "info",
    format: "json",
    enabled: true,
  },
});

// All auth operations will be logged
```

### Complete Integration Example

```typescript
import { EventBus } from "@iota-big3/sdk-events";
import { AuthManager } from "@iota-big3/sdk-auth";

// Initialize with all integrations
const eventBus = new EventBus();
const auth = new AuthManager(
  {
    jwtSecret: process.env.JWT_SECRET,
    database: {
      type: "postgres",
      host: process.env.DB_HOST,
      database: process.env.DB_NAME,
      user: process.env.DB_USER,
      password: process.env.DB_PASSWORD,
    },
    cache: {
      type: "redis",
      host: process.env.REDIS_HOST,
      port: 6379,
    },
    logging: {
      level: "info",
      format: "json",
    },
  },
  eventBus
);

// The SDK automatically:
// - Persists users and sessions to PostgreSQL
// - Caches sessions in Redis for fast validation
// - Logs all operations with structured logging
// - Emits events for other SDKs to react to
```

## Event Integration

sdk-auth emits the following events that other SDKs can listen to:

- `auth:initialized` - Auth manager initialized with integrations
- `auth:user.registered` - New user registered
- `auth:user.authenticated` - User successfully logged in
- `auth:user.logout` - User logged out
- `auth:user.cleanup` - User data cleaned up (on deletion)
- `auth:user.force_logout` - User forcefully logged out (security)
- `auth:token.refreshed` - Token refreshed
- `auth:failed_login` - Failed login attempt
- `auth:api_key.created` - API key created
- `auth:api_key.revoked` - API key revoked

sdk-auth listens to these events from other SDKs:

- `user:deleted` - Cleans up all auth data for deleted user
- `security:threat.detected` - Forces logout for compromised user

## Configuration

### Basic Configuration

```typescript
const authConfig = {
  jwt: {
    secret: process.env.JWT_SECRET,
    accessTokenExpiry: "1h",
    refreshTokenExpiry: "7d",
    issuer: "your-app",
    audience: "your-api",
  },
  session: {
    secret: process.env.SESSION_SECRET,
    maxAge: 86400000, // 24 hours
    secure: true,
    httpOnly: true,
  },
  passwordPolicy: {
    minLength: 8,
    requireUppercase: true,
    requireLowercase: true,
    requireNumbers: true,
    requireSpecialChars: true,
  },
};
```

### Zero Trust Configuration

```typescript
const authConfig = {
  // ... other config
  zeroTrust: {
    enabled: true,
    deviceTrust: true,
    continuousVerification: true,
    riskScoring: true,
  },
};
```

## OAuth/OIDC Integration

```typescript
const authConfig = {
  oauth: {
    providers: [
      {
        name: "google",
        clientId: process.env.GOOGLE_CLIENT_ID,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
        authorizationURL: "https://accounts.google.com/o/oauth2/v2/auth",
        tokenURL: "https://oauth2.googleapis.com/token",
        userInfoURL: "https://www.googleapis.com/oauth2/v2/userinfo",
        scope: ["openid", "email", "profile"],
      },
    ],
  },
};
```

## Multi-Factor Authentication

```typescript
// Enable MFA for user
await auth.enableMFA(user.id, "totp");

// Generate QR code for TOTP setup
const qrCode = await auth.generateMFAQRCode(user.id);

// Verify MFA token
const valid = await auth.verifyMFAToken(user.id, "123456");
```

## API Key Management

```typescript
// Create API key
const apiKey = await auth.createAPIKey(user.id, "Production API Key", [
  { resource: "documents", action: "read" },
  { resource: "documents", action: "write" },
]);

// Validate API key
const keyData = await auth.validateAPIKey(apiKey.key);
```

## Middleware Integration

```typescript
import express from "express";
import { authMiddleware } from "@iota-big3/sdk-auth/middleware";

const app = express();

// Protect all routes
app.use(authMiddleware(auth));

// Protect specific routes
app.get(
  "/api/protected",
  authMiddleware(auth, {
    permissions: ["documents:read"],
  }),
  (req, res) => {
    res.json({ user: req.user });
  }
);
```

## Security Best Practices

1. **Always use environment variables** for secrets
2. **Enable MFA** for privileged accounts
3. **Implement rate limiting** on authentication endpoints
4. **Use secure session configuration** in production
5. **Enable Zero Trust** features for sensitive applications
6. **Regularly rotate** JWT secrets and API keys
7. **Monitor authentication events** for anomalies

## Compliance

This package supports compliance with:

- **SOC 2** - Comprehensive audit logging
- **HIPAA** - Strong encryption and access controls
- **GDPR** - Data protection and privacy controls
- **FERPA** - Educational privacy requirements

## Performance

- JWT validation: <1ms
- Session lookup: <5ms (Redis-backed)
- Permission checks: <1ms (in-memory)
- Risk scoring: <10ms

## License

MIT

## Priority 2: Advanced Auth Features

### SAML 2.0 Support

The SDK now includes comprehensive SAML 2.0 support for enterprise SSO:

```typescript
import { SAMLProvider } from "@iota-big3/sdk-auth";

const samlProvider = new SAMLProvider({
  entryPoint: "https://idp.example.com/sso",
  issuer: "https://myapp.example.com",
  cert: "MIID...", // IdP certificate
  callbackUrl: "https://myapp.example.com/auth/saml/callback",
  identifierFormat: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
});

// Express routes
app.get("/auth/saml/login", samlProvider.middleware().login);
app.post("/auth/saml/callback", samlProvider.middleware().callback);
app.get("/auth/saml/metadata", samlProvider.middleware().metadata);
app.get("/auth/saml/logout", samlProvider.middleware().logout);
```

### Microsoft & Okta OAuth Providers

New OAuth providers for enterprise identity providers:

#### Microsoft (Azure AD)

```typescript
import { MicrosoftOAuthProvider } from "@iota-big3/sdk-auth";

const microsoftProvider = new MicrosoftOAuthProvider({
  clientId: process.env.AZURE_CLIENT_ID!,
  clientSecret: process.env.AZURE_CLIENT_SECRET!,
  redirectUri: "https://myapp.com/auth/microsoft/callback",
  tenant: "common", // or specific tenant ID
  scopes: ["openid", "profile", "email", "User.Read"],
});

// Get Microsoft Graph user profile
const user = await microsoftProvider.getUserProfile(accessToken);
```

#### Okta

```typescript
import { OktaOAuthProvider } from "@iota-big3/sdk-auth";

const oktaProvider = new OktaOAuthProvider({
  clientId: process.env.OKTA_CLIENT_ID!,
  clientSecret: process.env.OKTA_CLIENT_SECRET!,
  domain: "dev-123456.okta.com",
  redirectUri: "https://myapp.com/auth/okta/callback",
  authorizationServerId: "default",
});

// Okta-specific features
const logoutUrl = oktaProvider.getLogoutUrl(idToken, postLogoutRedirectUri);
```

### Comprehensive Audit Trail

Track all authentication events for security and compliance:

```typescript
const auth = new AuthManager({
  jwtSecret: "your-secret",
  auditTrailConfig: {
    enabled: true,
    retention: {
      days: 90,
      maxRecords: 1000000,
    },
    filters: {
      excludeActions: ["auth:token_refreshed"],
    },
    anonymize: {
      ipAddress: true,
      userAgent: false,
    },
  },
});

// Query audit logs
const auditTrail = auth.getAuditTrail();
const events = await auditTrail.query({
  userId: "user123",
  action: "auth:login",
  startDate: new Date("2023-01-01"),
  limit: 100,
});

// Get user activity summary
const summary = await auditTrail.getUserSummary(userId, 30);
console.log(`Failed logins: ${summary.failedLoginCount}`);

// Generate security report
const report = await auditTrail.getSecurityReport(7);
console.log(`Suspicious activities: ${report.suspiciousActivities}`);
```

#### Audit Events Tracked

- `auth:login` - Successful login
- `auth:logout` - User logout
- `auth:mfa_enabled` - MFA enabled
- `auth:mfa_verified` - MFA verification
- `auth:password_changed` - Password change
- `auth:account_locked` - Account locked
- `auth:role_assigned` - Role assignment
- `auth:api_key_created` - API key creation
- `auth:rate_limit_exceeded` - Rate limit hit
- `auth:suspicious_activity` - Security alerts

#### Custom Audit Storage

```typescript
class DatabaseAuditStorage implements AuditStorage {
  async store(event: AuditEvent): Promise<void> {
    await db.insert("audit_logs", event);
  }

  async query(options: AuditQueryOptions): Promise<AuditEvent[]> {
    return await db.select("audit_logs", options);
  }

  async cleanup(before: Date): Promise<number> {
    return await db.delete("audit_logs", { timestamp: { $lt: before } });
  }
}

const auth = new AuthManager({
  auditTrailConfig: {
    enabled: true,
    storage: new DatabaseAuditStorage(),
  },
});
```

## Phase 2g: Feature Flags & Enhanced Security

### Feature Flags System

The SDK includes a comprehensive feature flags system for safe rollout of new features:

```typescript
import { AuthManager, defaultAuthFeatureFlags } from "@iota-big3/sdk-auth";

const auth = new AuthManager({
  jwtSecret: "your-secret",
  featureFlags: defaultAuthFeatureFlags,
  featureFlagsStorage: "redis", // or 'memory', 'database'
});

// Check if feature is enabled
const featureFlags = auth.getFeatureFlags();
if (featureFlags.isEnabled("webauthn", { userId: user.id })) {
  // Use WebAuthn
}

// Gradual rollout
featureFlags.enable("zero-trust-scoring");
featureFlags.setRolloutPercentage("zero-trust-scoring", 25); // 25% of users

// Enable for specific users/roles
featureFlags.enableFor("delegation", ["user123", "role:admin"]);
```

### Available Feature Flags

- **webauthn** - WebAuthn/FIDO2 passwordless authentication
- **sms-mfa** - SMS-based multi-factor authentication
- **email-mfa** - Email-based multi-factor authentication
- **zero-trust-scoring** - Continuous verification with risk scoring
- **saml-signature-verification** - Full SAML signature verification
- **password-policy** - Configurable password requirements
- **account-recovery** - Self-service password reset
- **delegation** - User impersonation for admins
- **session-anomaly-detection** - Detect unusual session behavior
- **geo-location-access** - Location-based access control

### Enhanced SAML Signature Verification

SAML signature verification is now feature-flagged for safe rollout:

```typescript
// Enable SAML signature verification gradually
const featureFlags = auth.getFeatureFlags();

// Start with 10% of users
featureFlags.setRolloutPercentage("saml-signature-verification", 10);

// Monitor and increase
featureFlags.setRolloutPercentage("saml-signature-verification", 50);

// Full rollout when confident
featureFlags.setRolloutPercentage("saml-signature-verification", 100);
```

### Zero Trust Scoring

Implement continuous risk-based authentication:

```typescript
import { AuthManager } from "@iota-big3/sdk-auth";

const auth = new AuthManager({
  jwtSecret: "your-secret",
  zeroTrust: {
    lowRiskThreshold: 30,
    mediumRiskThreshold: 60,
    highRiskThreshold: 80,
    weights: {
      deviceTrust: 30,
      locationTrust: 25,
      behaviorTrust: 20,
      timeTrust: 15,
      networkTrust: 10,
    },
  },
});

// Calculate risk score during authentication
const riskFactors = {
  deviceId: request.deviceId,
  isKnownDevice: false,
  ipAddress: request.ip,
  country: geoIP.country,
  isVpn: detectVPN(request.ip),
  loginTime: new Date(),
  failedAttempts: 0,
  authMethod: "password",
};

const riskScore = await auth.calculateRiskScore(userId, riskFactors);

if (riskScore.level === "critical") {
  // Block access
  return res.status(403).json({
    error: "Access denied due to high risk",
    recommendations: riskScore.recommendations,
  });
}

if (riskScore.level === "high") {
  // Require step-up authentication
  return res.status(401).json({
    error: "Additional verification required",
    mfaRequired: true,
  });
}

// Make authentication decisions
const zeroTrust = auth.getZeroTrust();
const decision = zeroTrust.makeAuthDecision(riskScore);

if (!decision.allow) {
  return res.status(403).json({ error: decision.reason });
}

if (decision.requireMfa) {
  // Trigger MFA flow
}

// Apply restrictions if needed
req.restrictions = decision.restrictions; // e.g., ['read-only', 'no-admin']
```

#### Trusted Device Management

```typescript
// Add trusted device
await zeroTrust.addTrustedDevice(userId, {
  deviceId: "device-uuid",
  fingerprint: "browser-fingerprint",
  name: "John's MacBook",
  platform: "macOS",
  browser: "Chrome",
});

// Check if device is trusted
const isTrusted = await zeroTrust.isDeviceTrusted(
  userId,
  deviceId,
  fingerprint
);

// List user's trusted devices
const devices = await zeroTrust.getTrustedDevices(userId);

// Remove trusted device
await zeroTrust.removeTrustedDevice(userId, deviceId);
```

#### Location-Based Risk Assessment

```typescript
// Add trusted location
await zeroTrust.addTrustedLocation(userId, {
  name: "Home Office",
  latitude: 37.7749,
  longitude: -122.4194,
  radius: 5, // 5km radius
  country: "US",
  city: "San Francisco",
});

// Check if current location is trusted
const isLocationTrusted = await zeroTrust.isLocationTrusted(
  userId,
  currentLat,
  currentLon
);

// Detect impossible travel
const isPossible = zeroTrust.isPossibleTravel(
  { latitude: prevLat, longitude: prevLon, timestamp: prevTime },
  { latitude: currLat, longitude: currLon, timestamp: currTime },
  900 // Max 900 km/h (flight speed)
);
```

#### Behavioral Analysis

```typescript
// Update user baseline with login patterns
await zeroTrust.updateUserBaseline(userId, {
  loginTime: new Date(),
  country: "US",
  deviceId: "device-123",
  sessionDuration: 120, // minutes
});

// Check if login time is typical
const isTypicalTime = zeroTrust.isTypicalLoginTime(userId, new Date());

// Get user's behavioral baseline
const baseline = await zeroTrust.getUserBaseline(userId);
```

#### Session Risk Monitoring

```typescript
// Create risk-aware session
const session = await zeroTrust.createSession(userId, sessionId, {
  deviceId: deviceId,
  ipAddress: request.ip,
  authMethod: "mfa",
});

// Monitor session activities
await zeroTrust.recordSessionActivity(sessionId, {
  action: "data_export",
  resource: "/api/sensitive-data",
  result: "success",
});

// Get current session risk
const sessionRisk = await zeroTrust.getSessionRisk(sessionId);

if (sessionRisk.currentRiskScore.level === "high") {
  // Force re-authentication or terminate session
}
```

#### Risk Policies

Define custom risk policies:

```typescript
// Add policy for VPN users
await zeroTrust.addRiskPolicy({
  id: "vpn-policy",
  name: "VPN Access Policy",
  enabled: true,
  conditions: [{ factor: "isVpn", operator: "eq", value: true }],
  actions: [RecommendedAction.REQUIRE_MFA, RecommendedAction.LIMIT_ACCESS],
  priority: 1,
});

// Add policy for suspicious countries
await zeroTrust.addRiskPolicy({
  id: "country-block",
  name: "High-Risk Country Block",
  enabled: true,
  conditions: [
    { factor: "country", operator: "in", value: ["XX", "YY", "ZZ"] },
    { factor: "isKnownDevice", operator: "eq", value: false },
  ],
  actions: [RecommendedAction.BLOCK_ACCESS],
  priority: 0, // Highest priority
});
```

#### Risk Event Handling

```typescript
// Listen for risk events
zeroTrust.on("risk:threshold_exceeded", (event) => {
  console.log(`Risk threshold exceeded for user ${event.userId}`);
  console.log(`Score changed from ${event.previousScore} to ${event.newScore}`);

  // Send security alert
  sendSecurityAlert({
    userId: event.userId,
    riskLevel: event.newScore,
    recommendedActions: event.recommendedActions,
  });
});
```

#### Integration with Express Middleware

```typescript
const zeroTrustMiddleware = (requiredLevel: "low" | "medium" = "medium") => {
  return async (req, res, next) => {
    if (!req.user) return next();

    const factors = {
      deviceId: req.headers["x-device-id"],
      ipAddress: req.ip,
      userAgent: req.headers["user-agent"],
      // ... collect other factors
    };

    const riskScore = await auth.calculateRiskScore(req.user.id, factors);

    // Store risk score in request
    req.riskScore = riskScore;

    // Check if risk level is acceptable
    const levels = ["low", "medium", "high", "critical"];
    const requiredIndex = levels.indexOf(requiredLevel);
    const actualIndex = levels.indexOf(riskScore.level);

    if (actualIndex > requiredIndex) {
      return res.status(403).json({
        error: "Risk level too high",
        riskLevel: riskScore.level,
        recommendations: riskScore.recommendations,
      });
    }

    next();
  };
};

// Protect sensitive routes
app.get(
  "/api/admin/*",
  authenticate,
  zeroTrustMiddleware("low"),
  adminController
);
```

## Phase 2g: Next Generation Features

### WebAuthn/FIDO2 Support

Enable passwordless authentication with biometrics and security keys:

```typescript
import { AuthManager } from "@iota-big3/sdk-auth";

const auth = new AuthManager({
  jwtSecret: "your-secret",
  webauthn: {
    rpId: "example.com",
    rpName: "My App",
    origin: "https://example.com",
  },
});

// Check if WebAuthn is enabled
const webauthn = auth.getWebAuthn();
if (webauthn) {
  // Registration
  const regOptions = await webauthn.generateRegistrationOptions({
    userId: user.id,
    userName: user.email,
    userDisplayName: user.name,
    rpName: "My App",
    rpId: "example.com",
  });

  // Send options to client for WebAuthn ceremony
  // Client returns registration result

  const verification = await webauthn.verifyRegistration(
    regOptions.challenge,
    registrationResult,
    user.id
  );

  if (verification.verified) {
    // Credential registered successfully
  }

  // Authentication
  const authOptions = await webauthn.generateAuthenticationOptions({
    userId: user.id,
    rpId: "example.com",
  });

  // Client performs authentication ceremony

  const authVerification = await webauthn.verifyAuthentication(
    authOptions.challenge,
    authenticationResult
  );
}
```

#### Managing WebAuthn Credentials

```typescript
// List user credentials
const credentials = await webauthn.getUserCredentials(userId);

// Update credential name
await webauthn.updateCredentialMetadata(userId, credentialId, {
  name: "My YubiKey 5C",
});

// Delete credential
await webauthn.deleteCredential(userId, credentialId);
```

### Password Policy Engine

Enforce configurable password requirements:

```typescript
import { AuthManager, PASSWORD_POLICY_PRESETS } from "@iota-big3/sdk-auth";

const auth = new AuthManager({
  jwtSecret: "your-secret",
  passwordPolicy: PASSWORD_POLICY_PRESETS.enterprise,
  // or custom policy:
  // passwordPolicy: {
  //   minLength: 12,
  //   requireUppercase: true,
  //   requireLowercase: true,
  //   requireNumbers: true,
  //   requireSpecialChars: true,
  //   disallowCommonPasswords: true,
  //   disallowUserInfo: true
  // }
});

const policy = auth.getPasswordPolicy();
if (policy) {
  // Validate password
  const result = policy.validate(password, {
    user: {
      email: user.email,
      username: user.username,
      previousPasswords: user.passwordHistory,
    },
  });

  if (!result.isValid) {
    console.log("Password errors:", result.errors);
    console.log("Suggestions:", result.suggestions);
    console.log("Strength:", result.score);
  }

  // Generate compliant password
  const newPassword = policy.generatePassword({
    length: 16,
    memorable: true,
    words: 4,
    separator: "-",
  });
}
```

#### Policy Presets

- **minimal**: 8+ characters
- **standard**: 8+ chars, uppercase, lowercase, numbers
- **strong**: 12+ chars, all character types, no common passwords
- **enterprise**: 14+ chars, strict requirements, history check, expiry

#### Password Strength Analysis

```typescript
const result = policy.validate("MyP@ssw0rd123");
console.log(result.score);
// {
//   score: 85,
//   strength: 'strong',
//   entropy: 78.3,
//   crackTime: {
//     onlineThrottled: '3 years',
//     onlineUnthrottled: '11 days',
//     offlineSlow: '19 minutes',
//     offlineFast: 'instant'
//   }
// }
```

### Feature Flag Configuration

All Phase 2g features are protected by feature flags:

```typescript
const auth = new AuthManager({
  jwtSecret: "your-secret",
  featureFlags: [
    { name: "webauthn", enabled: true },
    { name: "password-policy", enabled: true },
    { name: "zero-trust-scoring", enabled: false },
    {
      name: "password-policy",
      enabled: true,
      rolloutPercentage: 50, // Gradual rollout
    },
  ],
});
```

### Express Integration Example

```typescript
import express from "express";

const app = express();

// WebAuthn registration endpoint
app.post("/auth/webauthn/register/begin", async (req, res) => {
  const webauthn = req.authManager.getWebAuthn();
  if (!webauthn) {
    return res.status(404).json({ error: "WebAuthn not enabled" });
  }

  const options = await webauthn.generateRegistrationOptions({
    userId: req.user.id,
    userName: req.user.email,
    userDisplayName: req.user.name,
    rpName: "My App",
    rpId: req.hostname,
  });

  req.session.challenge = options.challenge;
  res.json(options);
});

// Password validation middleware
const validatePassword = async (req, res, next) => {
  const policy = req.authManager.getPasswordPolicy();
  if (!policy) return next();

  const result = policy.validate(req.body.password, {
    user: {
      email: req.body.email,
      username: req.body.username,
    },
  });

  if (!result.isValid) {
    return res.status(400).json({
      error: "Password does not meet requirements",
      errors: result.errors,
      suggestions: result.suggestions,
      strength: result.score,
    });
  }

  next();
};

app.post("/auth/register", validatePassword, async (req, res) => {
  // Registration logic
});
```

### SMS/Email MFA

Multi-factor authentication via SMS and Email:

```typescript
import { AuthManager } from "@iota-big3/sdk-auth";

const auth = new AuthManager({
  jwtSecret: "your-secret",
  smsMFA: {
    provider: "twilio",
    twilioConfig: {
      accountSid: process.env.TWILIO_ACCOUNT_SID,
      authToken: process.env.TWILIO_AUTH_TOKEN,
      fromNumber: "+1234567890",
    },
    codeLength: 6,
    codeExpiry: 5, // minutes
    messageTemplate: "Your {appName} code: {code}",
  },
  emailMFA: {
    provider: "smtp",
    smtpConfig: {
      host: "smtp.example.com",
      port: 587,
      auth: { user: "user", pass: "pass" },
    },
    from: "noreply@example.com",
    codeExpiry: 10, // minutes
    htmlTemplate: "<h1>Your code: {code}</h1>",
  },
});

// Send SMS code
const smsResult = await auth.sendSMSCode(userId, "+1234567890");

// Send Email code
const emailResult = await auth.sendEmailCode(userId, "user@example.com");

// Verify code
const mfaManager = auth.getSMSEmailMFA();
const verifyResult = await mfaManager.verifyCode(smsResult.codeId, "123456");

if (verifyResult.verified) {
  // Continue with authentication
}
```

#### Custom Providers

```typescript
// Custom SMS Provider
const customSMSProvider: SMSProvider = {
  async sendSMS(to: string, message: string) {
    // Your SMS logic
    return { success: true, messageId: "xxx" };
  },

  validateNumber(phoneNumber: string) {
    return /^\+[1-9]\d{1,14}$/.test(phoneNumber);
  },
};

// Custom Email Provider
const customEmailProvider: EmailProvider = {
  async sendEmail(options: EmailOptions) {
    // Your email logic
    return { success: true, messageId: "yyy" };
  },

  validateAddress(email: string) {
    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
  },
};

// Use custom providers
const auth = new AuthManager({
  smsMFA: {
    provider: "custom",
    customProvider: customSMSProvider,
  },
  emailMFA: {
    provider: "custom",
    customProvider: customEmailProvider,
  },
});
```

#### Rate Limiting & Resend

```typescript
// Configure rate limits
const mfaConfig = {
  rateLimits: {
    maxCodesPerHour: 5,
    maxCodesPerDay: 20,
    maxVerificationAttemptsPerCode: 3,
  },
};

// Resend code (with delay enforcement)
const resendResult = await mfaManager.resendCode(codeId);

// Get MFA statistics
const stats = await mfaManager.getStatistics(userId, "day");
console.log(`SMS sent: ${stats.sms.sent}, verified: ${stats.sms.verified}`);
```

### Account Recovery

Self-service password reset with multiple verification methods:

```typescript
import { AccountRecoveryManager } from "@iota-big3/sdk-auth";

// Initialize recovery manager
const recoveryManager = new AccountRecoveryManager(
  {
    methods: ["email", "sms", "security_questions", "backup_codes"],
    tokenExpiry: 60, // minutes
    maxAttempts: 3,
    lockoutDuration: 60, // minutes
    recoveryUrl: "https://app.example.com/reset-password",
    emailTemplate: {
      subject: "Reset Your Password",
      htmlTemplate: '<a href="{link}">Reset Password</a>',
    },
  },
  userStore, // Your user database interface
  notificationService, // Email/SMS service
  featureFlags
);

// Initiate recovery via email
const result = await recoveryManager.initiateRecovery(
  "user@example.com",
  "email"
);

// Verify token from email link
const verifyResult = await recoveryManager.verifyToken(token);

if (verifyResult.success) {
  // Reset password
  const resetResult = await recoveryManager.resetPassword(
    verifyResult.sessionId,
    "NewSecurePassword123!"
  );
}
```

#### Security Questions

```typescript
// Set up security questions
const questions: SecurityQuestion[] = [
  {
    id: "q1",
    question: "What was your first pet's name?",
    category: "Personal",
  },
  { id: "q2", question: "In what city were you born?", category: "Personal" },
  {
    id: "q3",
    question: "What is your mother's maiden name?",
    category: "Personal",
  },
];

recoveryManager.setSecurityQuestions(questions);

// User sets their answers
await recoveryManager.setUserSecurityQuestions(userId, [
  { questionId: "q1", answer: "fluffy" },
  { questionId: "q2", answer: "new york" },
]);

// During recovery
const initResult = await recoveryManager.initiateRecovery(
  "user@example.com",
  "security_questions"
);

// Get questions
const challenges = await recoveryManager.getSecurityQuestions(
  initResult.requestId
);

// Verify answers
const verifyResult = await recoveryManager.verifySecurityAnswers(
  initResult.requestId,
  [
    { questionId: "q1", answer: "fluffy" },
    { questionId: "q2", answer: "new york" },
  ]
);
```

#### Backup Codes

```typescript
// Generate backup codes for user
const backupCodes = await recoveryManager.generateBackupCodes(userId);
// Returns: ['ABCD1234-5678', 'EFGH9012-3456', ...]

// During recovery
const initResult = await recoveryManager.initiateRecovery(
  "user@example.com",
  "backup_codes"
);

// Verify backup code
const verifyResult = await recoveryManager.verifyBackupCode(
  initResult.requestId,
  "ABCD1234-5678"
);
```

#### Multi-Method Recovery

```typescript
// Require both email and SMS verification
const recoveryManager = new AccountRecoveryManager({
  methods: ["email", "sms"],
  requireEmailVerification: true,
  requireSMSVerification: true,
});

// Start with email
const emailResult = await recoveryManager.initiateRecovery(
  "user@example.com",
  "email"
);

// Verify email token
const emailVerify = await recoveryManager.verifyToken(emailToken);

// Continue with SMS
const smsResult = await recoveryManager.continueRecovery(
  emailVerify.sessionId,
  "sms"
);

// Verify SMS and reset password
const smsVerify = await recoveryManager.verifyToken(smsToken);
await recoveryManager.resetPassword(smsVerify.sessionId, newPassword);
```

#### Recovery Events & Statistics

```typescript
// Listen for recovery events
recoveryManager.on("recovery:event", (event) => {
  if (event.type === "recovery_locked") {
    // Send security alert
    sendSecurityAlert({
      userId: event.userId,
      reason: "Account locked due to failed recovery attempts",
    });
  }
});

// Get recovery statistics
const stats = await recoveryManager.getStatistics("day");
console.log(`Recovery attempts: ${stats.initiated}`);
console.log(`Successful: ${stats.completed}`);
console.log(`Failed: ${stats.failed}`);
console.log(`Locked accounts: ${stats.locked}`);
```

### Session Anomaly Detection

Real-time behavioral analysis to detect suspicious session activities:

```typescript
import { AuthManager } from "@iota-big3/sdk-auth";

const auth = new AuthManager({
  jwtSecret: "your-secret",
  sessionAnomaly: {
    velocityThreshold: 100, // Actions per minute
    dataAccessThreshold: 1000, // MB per hour
    privilegedActionThreshold: 50, // Per hour
    enablePatternAnalysis: true,
    enableVelocityDetection: true,
    enableResourceAnalysis: true,
    autoBlockOnCritical: true,
  },
});

// Track session activities
auth.trackActivity({
  id: crypto.randomUUID(),
  sessionId: "session123",
  userId: "user123",
  timestamp: new Date(),
  action: "data_export",
  resource: "/api/sensitive-data",
  method: "GET",
  dataSize: 50 * 1024 * 1024, // 50MB
  ipAddress: "1.2.3.4",
});

// Check for anomalies
const anomalyDetector = auth.getSessionAnomaly();
const result = await anomalyDetector.checkForAnomalies("session123");

if (result.anomalyDetected) {
  console.log("Anomalies detected:", result.anomalies);
  console.log("Risk score:", result.overallRiskScore);
  console.log("Suggested actions:", result.suggestedActions);
}
```

#### Behavioral Profiles

```typescript
// Update user behavioral profile
await anomalyDetector.updateBehavioralProfile("user123", {
  userId: "user123",
  averageActionsPerMinute: 10,
  typicalActions: ["view_dashboard", "view_reports", "export_data"],
  typicalResources: ["/api/reports", "/api/dashboard"],
  typicalTimeRanges: [
    { dayOfWeek: 1, startHour: 9, endHour: 17, frequency: 90 },
  ],
  commonIpAddresses: ["192.168.1.100"],
  commonUserAgents: ["Chrome/120.0"],
  commonLocations: ["US"],
  averageDataAccess: 100, // MB/hour
  typicalResponseTimes: { "/api/data": 200 },
  commonActionSequences: [
    {
      actions: ["login", "view_dashboard", "view_reports"],
      frequency: 80,
      averageTimeBetween: 5000,
    },
  ],
  lastUpdated: new Date(),
  sampleSize: 1000,
});
```

#### Custom Anomaly Rules

```typescript
// Add custom detection rule
await anomalyDetector.addRule({
  id: "high-data-export",
  name: "Excessive Data Export",
  description: "Detect large data exports",
  enabled: true,
  priority: 1,
  conditions: [
    { metric: "dataAccess", operator: "gt", value: 500, timeWindow: 5 },
  ],
  actions: [AnomalyAction.ALERT, AnomalyAction.LIMIT_ACCESS],
  severity: "high",
  cooldown: 30, // minutes
});

// Monitor sessions in real-time
const monitor = anomalyDetector.startMonitoring("session123", "user123");
console.log("Current risk score:", monitor.currentRiskScore);
```

#### Anomaly Types Detected

- **Velocity Anomalies**: Excessive API calls or actions
- **Pattern Anomalies**: Unusual action sequences
- **Resource Anomalies**: Access to sensitive resources
- **Time Anomalies**: Activity outside normal hours
- **Privilege Escalation**: Rapid privileged actions
- **Data Exfiltration**: Large data transfers

### Geo-Location Access Control

IP-based restrictions and location-aware security:

```typescript
import { AuthManager } from "@iota-big3/sdk-auth";

const auth = new AuthManager({
  jwtSecret: "your-secret",
  geoLocation: {
    provider: "ipapi", // or 'maxmind', 'ipinfo', 'custom'
    apiKey: process.env.GEO_API_KEY,
    enableCache: true,
    cacheExpiry: 60, // minutes
    treatVPNAsHighRisk: true,
    autoBlockOnViolation: true,
  },
});

// Check IP access
const decision = await auth.checkIPAccess("1.2.3.4", {
  userId: "user123",
  resource: "/api/sensitive",
});

if (!decision.allowed) {
  console.log("Access denied:", decision.reason);

  if (decision.action === "challenge") {
    // Present challenges (MFA, CAPTCHA, etc.)
    console.log("Challenges required:", decision.challenges);
  }
}
```

#### Access Rules

```typescript
const geoManager = auth.getGeoLocation();

// Block specific countries
await geoManager.addRule({
  id: "block-countries",
  name: "Block High-Risk Countries",
  enabled: true,
  priority: 1,
  conditions: [{ field: "country", operator: "in", value: ["XX", "YY"] }],
  action: "block",
});

// Challenge VPN connections
await geoManager.addRule({
  id: "challenge-vpn",
  name: "Challenge VPN Users",
  enabled: true,
  priority: 2,
  conditions: [{ field: "isVPN", operator: "eq", value: true }],
  action: "challenge",
});

// Allow specific IP ranges
await geoManager.addRule({
  id: "office-ips",
  name: "Allow Office IPs",
  enabled: true,
  priority: 0, // Highest priority
  conditions: [{ field: "ip", operator: "in", value: ["10.0.0.0/8"] }],
  action: "allow",
});
```

#### Location Restrictions

```typescript
// User-specific whitelist
await geoManager.addLocationRestriction({
  id: "user-whitelist",
  type: "whitelist",
  scope: "user",
  scopeId: "user123",
  locations: [
    { type: "country", value: "US" },
    { type: "country", value: "CA" },
    { type: "city", value: "San Francisco" },
  ],
  enabled: true,
  createdAt: new Date(),
  updatedAt: new Date(),
});

// Global blacklist
await geoManager.addLocationRestriction({
  id: "global-blacklist",
  type: "blacklist",
  scope: "global",
  locations: [
    { type: "country", value: "Sanctioned Country" },
    {
      type: "ip_range",
      value: { start: "192.0.2.0", end: "192.0.2.255" },
    },
  ],
  enabled: true,
  createdAt: new Date(),
  updatedAt: new Date(),
});
```

#### Geo-Fencing

```typescript
// Create office geo-fence
await geoManager.addGeoFence({
  id: "hq-fence",
  name: "Headquarters",
  type: "circle",
  coordinates: {
    type: "circle",
    center: { latitude: 37.7749, longitude: -122.4194 },
    radiusKm: 5,
  },
  rules: [
    {
      action: "allow",
      userScope: "role",
      roles: ["employee", "admin"],
    },
  ],
  enabled: true,
  schedule: {
    timezone: "America/Los_Angeles",
    active: [
      {
        dayOfWeek: [1, 2, 3, 4, 5], // Mon-Fri
        startTime: "08:00",
        endTime: "18:00",
      },
    ],
  },
});
```

#### Travel Analysis

```typescript
// Analyze user travel patterns
const travelAnalysis = await geoManager.analyzeTravelPattern(
  "user123",
  "5.6.7.8", // Current IP
  new Date()
);

if (travelAnalysis.suspicious) {
  console.log("Suspicious travel detected:", travelAnalysis.patterns);

  // Check for impossible travel
  const impossibleTravel = travelAnalysis.patterns.find(
    (p) => p.type === "impossible_travel"
  );

  if (impossibleTravel) {
    // Require additional verification
    console.log("Impossible travel:", impossibleTravel.description);
  }
}

// Get user travel history
const travelPattern = await geoManager.getUserTravelPattern("user123");
console.log("Typical countries:", travelPattern.typicalCountries);
console.log("Suspicious patterns:", travelPattern.suspiciousPatterns);
```

#### IP Intelligence

```typescript
// Get IP reputation
const intelligence = await geoManager.getIPIntelligence("1.2.3.4");

console.log("IP Reputation:", intelligence.reputation); // good, neutral, suspicious, bad
console.log("Trust Score:", intelligence.score); // 0-100
console.log("Risk Factors:", intelligence.factors);

// Get geo-location statistics
const stats = await geoManager.getStatistics("day");
console.log("Blocked attempts:", stats.blockedAttempts);
console.log("Top blocked countries:", stats.topBlockedCountries);
console.log("VPN attempts:", stats.vpnAttempts);
```

#### Express Middleware Integration

```typescript
// Session anomaly middleware
app.use((req, res, next) => {
  if (req.session && req.user) {
    auth.trackActivity({
      id: crypto.randomUUID(),
      sessionId: req.session.id,
      userId: req.user.id,
      timestamp: new Date(),
      action: `${req.method} ${req.path}`,
      resource: req.path,
      method: req.method,
      ipAddress: req.ip,
      userAgent: req.get("user-agent"),
    });
  }
  next();
});

// Geo-location middleware
app.use(async (req, res, next) => {
  try {
    const decision = await auth.checkIPAccess(req.ip, {
      userId: req.user?.id,
      resource: req.path,
    });

    if (!decision.allowed) {
      if (decision.action === "block") {
        return res.status(403).json({
          error: "Access denied",
          reason: decision.reason,
        });
      }

      if (decision.action === "challenge") {
        req.geoChallenge = decision.challenges;
      }
    }

    req.geoLocation = decision.location;
    next();
  } catch (error) {
    next(error);
  }
});
```

## Phase 3 & 4: Enterprise Integration

### High Availability (Phase 3)

The SDK integrates with other IOTA Big3 SDKs for high availability features:

```typescript
import { createHAAuthManager } from "@iota-big3/sdk-auth";

const haAuth = createHAAuthManager(
  {
    secretKey: process.env.JWT_SECRET,
    accessTokenExpiry: 3600,
  },
  {
    enableReadReplicas: true, // Uses sdk-database
    enableDistributedCache: true, // Uses sdk-performance
    enableMultiRegion: true, // Uses sdk-cloud
    enableFailover: true, // Uses sdk-database
    sessionReplication: {
      strategy: "async",
      regions: ["us-east-1", "eu-west-1"],
    },
  }
);
```

### Compliance Integration (Phase 4)

Compliance is handled by `sdk-compliance`, not duplicated in auth:

```typescript
import { ComplianceIntegratedAuthManager } from "@iota-big3/sdk-auth";

const complianceAuth = new ComplianceIntegratedAuthManager(authConfig, {
  enableGDPR: true, // GDPR export/deletion via sdk-compliance
  enableSOC2: true, // SOC2 audit logging via sdk-compliance
  enablePCIDSS: true, // PCI compliance via sdk-compliance
  dataRetentionDays: 365,
  auditLogRetentionDays: 2555, // 7 years
});

// GDPR data export
const userData = await complianceAuth.exportUserData(userId);

// GDPR right to be forgotten
await complianceAuth.deleteUserData(userId, "user_request");

// Compliance status
const status = await complianceAuth.getComplianceStatus();
```

### Architecture Philosophy

This SDK follows the IOTA Big3 architecture principles:

❌ **NOT**: Implementing all features within sdk-auth
✅ **INSTEAD**: Delegating to specialized SDKs

| Feature         | Wrong Approach              | Right Approach        |
| --------------- | --------------------------- | --------------------- |
| Session Storage | Build Redis cluster in auth | Use `sdk-performance` |
| Read Replicas   | Add DB logic to auth        | Use `sdk-database`    |
| GDPR Export     | Create export in auth       | Use `sdk-compliance`  |
| Audit Logs      | Add audit tables            | Use `sdk-compliance`  |
| Multi-region    | Handle regions in auth      | Use `sdk-cloud`       |

This prevents duplication and ensures each SDK focuses on its specialty.