@build-astron-co/nimbus 0.2.0

package/src/utils/rate-limiter.ts

@@ -0,0 +1,121 @@
+import { logger } from './logger';
+
+interface RateLimiterOptions {
+  requestsPerMinute: number;
+  burstSize?: number;
+}
+
+interface ClientBucket {
+  tokens: number;
+  lastRefill: number;
+}
+
+export class SimpleRateLimiter {
+  private requestsPerMinute: number;
+  private burstSize: number;
+  private buckets: Map<string, ClientBucket>;
+  private cleanupInterval: ReturnType<typeof setInterval> | null;
+
+  constructor(options: RateLimiterOptions) {
+    this.requestsPerMinute = options.requestsPerMinute;
+    this.burstSize = options.burstSize || options.requestsPerMinute;
+    this.buckets = new Map();
+
+    this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+    if (
+      this.cleanupInterval &&
+      typeof this.cleanupInterval === 'object' &&
+      'unref' in this.cleanupInterval
+    ) {
+      (this.cleanupInterval as any).unref();
+    }
+  }
+
+  tryAcquire(clientId: string = 'default'): boolean {
+    const now = Date.now();
+    let bucket = this.buckets.get(clientId);
+
+    if (!bucket) {
+      bucket = { tokens: this.burstSize, lastRefill: now };
+      this.buckets.set(clientId, bucket);
+    }
+
+    const elapsed = now - bucket.lastRefill;
+    const refill = (elapsed / 60_000) * this.requestsPerMinute;
+    bucket.tokens = Math.min(this.burstSize, bucket.tokens + refill);
+    bucket.lastRefill = now;
+
+    if (bucket.tokens >= 1) {
+      bucket.tokens -= 1;
+      return true;
+    }
+
+    return false;
+  }
+
+  getRemainingRequests(clientId: string = 'default'): number {
+    const bucket = this.buckets.get(clientId);
+    if (!bucket) {
+      return this.burstSize;
+    }
+
+    const elapsed = Date.now() - bucket.lastRefill;
+    const refill = (elapsed / 60_000) * this.requestsPerMinute;
+    return Math.min(this.burstSize, Math.floor(bucket.tokens + refill));
+  }
+
+  private cleanup(): void {
+    const cutoff = Date.now() - 120_000;
+    for (const [clientId, bucket] of this.buckets) {
+      if (bucket.lastRefill < cutoff) {
+        this.buckets.delete(clientId);
+      }
+    }
+  }
+
+  destroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+}
+
+function getClientIp(req: Request): string {
+  const forwarded = req.headers.get('x-forwarded-for');
+  if (forwarded) {
+    return forwarded.split(',')[0].trim();
+  }
+
+  const realIp = req.headers.get('x-real-ip');
+  if (realIp) {
+    return realIp;
+  }
+
+  return 'unknown';
+}
+
+export function rateLimitMiddleware(limiter: SimpleRateLimiter): (req: Request) => Response | null {
+  return (req: Request): Response | null => {
+    const url = new URL(req.url);
+
+    if (url.pathname === '/health') {
+      return null;
+    }
+
+    const clientIp = getClientIp(req);
+    if (!limiter.tryAcquire(clientIp)) {
+      logger.warn(`Rate limited client ${clientIp} on ${url.pathname}`);
+      const retryAfter = Math.ceil(60 / limiter.getRemainingRequests(clientIp) || 60);
+      return new Response(JSON.stringify({ success: false, error: 'Too Many Requests' }), {
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'Retry-After': String(retryAfter),
+        },
+      });
+    }
+
+    return null;
+  };
+}

package/src/utils/service-auth.ts

@@ -0,0 +1,49 @@
+import { logger } from './logger';
+
+const SERVICE_TOKEN_HEADER = 'x-internal-service-token';
+
+export function validateServiceToken(req: Request): boolean {
+  const expectedToken = process.env.INTERNAL_SERVICE_TOKEN;
+  if (!expectedToken) {
+    return true;
+  }
+
+  const providedToken = req.headers.get(SERVICE_TOKEN_HEADER);
+  return providedToken === expectedToken;
+}
+
+export function serviceAuthMiddleware(req: Request): Response | null {
+  const expectedToken = process.env.INTERNAL_SERVICE_TOKEN;
+  if (!expectedToken) {
+    return null;
+  }
+
+  const url = new URL(req.url);
+  const path = url.pathname;
+
+  if (path === '/health' || path.startsWith('/swagger') || path === '/api/openapi.json') {
+    return null;
+  }
+
+  if (!path.startsWith('/api/')) {
+    return null;
+  }
+
+  if (!validateServiceToken(req)) {
+    logger.warn(`Unauthorized service request to ${path}`);
+    return Response.json(
+      { success: false, error: 'Unauthorized: invalid or missing service token' },
+      { status: 401 }
+    );
+  }
+
+  return null;
+}
+
+export function getServiceAuthHeaders(): Record<string, string> {
+  const token = process.env.INTERNAL_SERVICE_TOKEN;
+  if (!token) {
+    return {};
+  }
+  return { [SERVICE_TOKEN_HEADER]: token };
+}

package/src/utils/validation.ts

@@ -0,0 +1,53 @@
+import { ValidationError } from './errors';
+
+export function validateRequired(value: unknown, fieldName: string, service: string): void {
+  if (value === undefined || value === null || value === '') {
+    throw new ValidationError(`Field '${fieldName}' is required`, service, { field: fieldName });
+  }
+}
+
+export function validateString(value: unknown, fieldName: string, service: string): string {
+  if (typeof value !== 'string') {
+    throw new ValidationError(`Field '${fieldName}' must be a string`, service, {
+      field: fieldName,
+      received: typeof value,
+    });
+  }
+  return value;
+}
+
+export function validateNumber(value: unknown, fieldName: string, service: string): number {
+  if (typeof value !== 'number' || isNaN(value)) {
+    throw new ValidationError(`Field '${fieldName}' must be a number`, service, {
+      field: fieldName,
+      received: typeof value,
+    });
+  }
+  return value;
+}
+
+export function validateBoolean(value: unknown, fieldName: string, service: string): boolean {
+  if (typeof value !== 'boolean') {
+    throw new ValidationError(`Field '${fieldName}' must be a boolean`, service, {
+      field: fieldName,
+      received: typeof value,
+    });
+  }
+  return value;
+}
+
+export function validateEnum<T extends string>(
+  value: unknown,
+  fieldName: string,
+  allowedValues: T[],
+  service: string
+): T {
+  if (typeof value !== 'string' || !allowedValues.includes(value as T)) {
+    throw new ValidationError(
+      `Field '${fieldName}' must be one of: ${allowedValues.join(', ')}`,
+      service,
+      { field: fieldName, received: value, allowed: allowedValues }
+    );
+  }
+  return value as T;
+}

package/src/version.ts

@@ -0,0 +1,4 @@
+export const VERSION = '0.2.0';
+
+const _RAW_BUILD_DATE = '__BUILD_DATE__';
+export const BUILD_DATE = _RAW_BUILD_DATE.startsWith('__') ? 'dev' : _RAW_BUILD_DATE;

package/src/watcher/index.ts

@@ -0,0 +1,163 @@
+/**
+ * Filesystem Watcher
+ *
+ * Watches the project directory for file changes and emits events
+ * that the agent loop can respond to (e.g., re-reading modified files).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { EventEmitter } from 'node:events';
+
+export interface FileChangeEvent {
+  type: 'change' | 'rename';
+  path: string;
+  timestamp: number;
+}
+
+export class FileWatcher extends EventEmitter {
+  private watcher: fs.FSWatcher | null = null;
+  private changes: FileChangeEvent[] = [];
+  private readonly maxChanges = 100;
+  private readonly ignorePatterns = [
+    'node_modules',
+    '.git',
+    'dist',
+    'coverage',
+    '.nimbus',
+    '__pycache__',
+    '.terraform',
+  ];
+
+  constructor(private readonly rootDir: string) {
+    super();
+  }
+
+  /**
+   * Start watching the project directory.
+   */
+  start(): void {
+    if (this.watcher) {
+      return;
+    }
+
+    try {
+      this.watcher = fs.watch(this.rootDir, { recursive: true }, (eventType, filename) => {
+        if (!filename) {
+          return;
+        }
+
+        // Skip ignored paths
+        const parts = filename.split(path.sep);
+        if (parts.some(p => this.ignorePatterns.includes(p))) {
+          return;
+        }
+
+        // Skip hidden files
+        if (parts.some(p => p.startsWith('.') && p !== '.env')) {
+          return;
+        }
+
+        const event: FileChangeEvent = {
+          type: eventType as 'change' | 'rename',
+          path: path.join(this.rootDir, filename),
+          timestamp: Date.now(),
+        };
+
+        this.changes.push(event);
+        if (this.changes.length > this.maxChanges) {
+          this.changes.shift();
+        }
+
+        this.emit('change', event);
+      });
+
+      // recursive:true is only supported on macOS and Windows.
+      // On Linux, fs.watch silently ignores the flag and only watches the root dir.
+      if (process.platform === 'linux') {
+        // Watch key subdirectories individually as a workaround
+        const subdirs = ['src', 'lib', 'app', 'packages', 'services', 'test', 'tests', 'scripts'];
+        for (const sub of subdirs) {
+          const subPath = path.join(this.rootDir, sub);
+          try {
+            if (fs.existsSync(subPath) && fs.statSync(subPath).isDirectory()) {
+              fs.watch(subPath, { recursive: false }, (eventType, filename) => {
+                if (!filename) {
+                  return;
+                }
+                const fullPath = path.join(subPath, filename);
+                const relParts = path.relative(this.rootDir, fullPath).split(path.sep);
+                if (relParts.some(p => this.ignorePatterns.includes(p))) {
+                  return;
+                }
+                if (relParts.some(p => p.startsWith('.') && p !== '.env')) {
+                  return;
+                }
+                const event: FileChangeEvent = {
+                  type: eventType as 'change' | 'rename',
+                  path: fullPath,
+                  timestamp: Date.now(),
+                };
+                this.changes.push(event);
+                if (this.changes.length > this.maxChanges) {
+                  this.changes.shift();
+                }
+                this.emit('change', event);
+              });
+            }
+          } catch {
+            /* non-critical */
+          }
+        }
+      }
+    } catch {
+      // Watching is non-critical -- some systems don't support recursive watch
+    }
+  }
+
+  /**
+   * Stop watching.
+   */
+  stop(): void {
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+  }
+
+  /**
+   * Get recent changes since a timestamp.
+   */
+  getChangesSince(timestamp: number): FileChangeEvent[] {
+    return this.changes.filter(c => c.timestamp > timestamp);
+  }
+
+  /**
+   * Get a summary of recent changes for the agent context.
+   */
+  getSummary(since?: number): string {
+    const relevant = since ? this.getChangesSince(since) : this.changes;
+    if (relevant.length === 0) {
+      return '';
+    }
+
+    const uniquePaths = [...new Set(relevant.map(c => c.path))];
+    const lines = uniquePaths.slice(-20).map(p => {
+      const rel = path.relative(this.rootDir, p);
+      return `  - ${rel}`;
+    });
+
+    return `Files changed externally:\n${lines.join('\n')}`;
+  }
+
+  /**
+   * Clear the change history.
+   */
+  clearChanges(): void {
+    this.changes = [];
+  }
+
+  get isWatching(): boolean {
+    return this.watcher !== null;
+  }
+}