opc-agent 0.9.0 → 1.0.0

package/src/core/errors.ts

@@ -0,0 +1,148 @@
+/**
+ * OPC Agent Error Hierarchy - v1.0.0
+ * Custom error classes with user-friendly messages and recovery hints.
+ */
+
+export class OPCError extends Error {
+  public readonly code: string;
+  public readonly hint?: string;
+  public readonly context?: Record<string, unknown>;
+  public readonly timestamp = Date.now();
+
+  constructor(message: string, opts?: { code?: string; hint?: string; context?: Record<string, unknown>; cause?: Error }) {
+    super(message);
+    this.name = 'OPCError';
+    this.code = opts?.code ?? 'OPC_UNKNOWN';
+    this.hint = opts?.hint;
+    this.context = opts?.context;
+    if (opts?.cause) this.cause = opts.cause;
+  }
+
+  toJSON(): Record<string, unknown> {
+    return { name: this.name, code: this.code, message: this.message, hint: this.hint, context: this.context, timestamp: this.timestamp };
+  }
+
+  toUserMessage(): string {
+    return this.hint ? `${this.message}\n💡 ${this.hint}` : this.message;
+  }
+}
+
+export class ProviderError extends OPCError {
+  public readonly provider: string;
+  public readonly statusCode?: number;
+
+  constructor(provider: string, message: string, opts?: { statusCode?: number; hint?: string; cause?: Error }) {
+    super(message, {
+      code: 'OPC_PROVIDER_ERROR',
+      hint: opts?.hint ?? `Check your API key and network connection for ${provider}.`,
+      context: { provider, statusCode: opts?.statusCode },
+      cause: opts?.cause,
+    });
+    this.name = 'ProviderError';
+    this.provider = provider;
+    this.statusCode = opts?.statusCode;
+  }
+}
+
+export class ValidationError extends OPCError {
+  public readonly field?: string;
+  public readonly errors: string[];
+
+  constructor(message: string, errors: string[] = [], field?: string) {
+    super(message, {
+      code: 'OPC_VALIDATION_ERROR',
+      hint: 'Check your OAD configuration file for missing or invalid fields.',
+      context: { field, errors },
+    });
+    this.name = 'ValidationError';
+    this.field = field;
+    this.errors = errors;
+  }
+}
+
+export class ConfigError extends OPCError {
+  constructor(message: string, hint?: string) {
+    super(message, { code: 'OPC_CONFIG_ERROR', hint: hint ?? 'Check your oad.yaml and .env files.' });
+    this.name = 'ConfigError';
+  }
+}
+
+export class ChannelError extends OPCError {
+  public readonly channelType: string;
+
+  constructor(channelType: string, message: string, opts?: { hint?: string; cause?: Error }) {
+    super(message, {
+      code: 'OPC_CHANNEL_ERROR',
+      hint: opts?.hint ?? `Check configuration for the ${channelType} channel.`,
+      context: { channelType },
+      cause: opts?.cause,
+    });
+    this.name = 'ChannelError';
+    this.channelType = channelType;
+  }
+}
+
+export class PluginError extends OPCError {
+  public readonly pluginName: string;
+
+  constructor(pluginName: string, message: string, opts?: { hint?: string; cause?: Error }) {
+    super(message, {
+      code: 'OPC_PLUGIN_ERROR',
+      hint: opts?.hint ?? `Check plugin "${pluginName}" configuration.`,
+      context: { pluginName },
+      cause: opts?.cause,
+    });
+    this.name = 'PluginError';
+    this.pluginName = pluginName;
+  }
+}
+
+export class RateLimitError extends OPCError {
+  public readonly retryAfterMs?: number;
+
+  constructor(message?: string, retryAfterMs?: number) {
+    super(message ?? 'Rate limit exceeded. Please slow down.', {
+      code: 'OPC_RATE_LIMIT',
+      hint: retryAfterMs ? `Try again in ${Math.ceil(retryAfterMs / 1000)} seconds.` : 'Please wait before sending more messages.',
+      context: { retryAfterMs },
+    });
+    this.name = 'RateLimitError';
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+export class SecurityError extends OPCError {
+  constructor(message: string, hint?: string) {
+    super(message, { code: 'OPC_SECURITY_ERROR', hint: hint ?? 'This request was blocked for security reasons.' });
+    this.name = 'SecurityError';
+  }
+}
+
+export class TimeoutError extends OPCError {
+  constructor(operation: string, timeoutMs: number) {
+    super(`Operation "${operation}" timed out after ${timeoutMs}ms`, {
+      code: 'OPC_TIMEOUT',
+      hint: 'The operation took too long. Try again or increase the timeout.',
+      context: { operation, timeoutMs },
+    });
+    this.name = 'TimeoutError';
+  }
+}
+
+/**
+ * Wrap an unknown thrown value into an OPCError.
+ */
+export function wrapError(err: unknown, fallbackMessage = 'An unexpected error occurred'): OPCError {
+  if (err instanceof OPCError) return err;
+  if (err instanceof Error) return new OPCError(err.message, { cause: err });
+  return new OPCError(typeof err === 'string' ? err : fallbackMessage);
+}
+
+/**
+ * Format error for user display (no stack traces).
+ */
+export function formatErrorForUser(err: unknown): string {
+  if (err instanceof OPCError) return err.toUserMessage();
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/core/security.ts

@@ -0,0 +1,171 @@
+/**
+ * Security Hardening Module - v1.0.0
+ * Input sanitization, CORS, security headers, API key rotation.
+ */
+
+import type { Request, Response, NextFunction } from 'express';
+
+// ── Input Sanitization ──────────────────────────────────────
+
+const XSS_PATTERNS = [
+  /<script\b[^>]*>[\s\S]*?<\/script>/gi,
+  /javascript:/gi,
+  /on\w+\s*=/gi,
+  /<iframe\b/gi,
+  /<object\b/gi,
+  /<embed\b/gi,
+  /<form\b/gi,
+];
+
+const SQL_PATTERNS = [
+  /(\b(SELECT|INSERT|UPDATE|DELETE|DROP|UNION|ALTER|CREATE|EXEC)\b.*\b(FROM|INTO|TABLE|SET|WHERE|ALL)\b)/gi,
+  /(--|;)\s*(DROP|ALTER|DELETE)/gi,
+];
+
+export function sanitizeInput(input: string): string {
+  let clean = input;
+  for (const pattern of XSS_PATTERNS) {
+    clean = clean.replace(pattern, '');
+  }
+  // Encode dangerous HTML entities
+  clean = clean.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  return clean;
+}
+
+export function detectInjection(input: string): { safe: boolean; threats: string[] } {
+  const threats: string[] = [];
+  for (const pattern of XSS_PATTERNS) {
+    if (pattern.test(input)) threats.push('xss');
+    pattern.lastIndex = 0;
+  }
+  for (const pattern of SQL_PATTERNS) {
+    if (pattern.test(input)) threats.push('sql_injection');
+    pattern.lastIndex = 0;
+  }
+  return { safe: threats.length === 0, threats: [...new Set(threats)] };
+}
+
+// ── Security Headers (Helmet-style) ────────────────────────
+
+export interface SecurityHeadersConfig {
+  contentSecurityPolicy?: string;
+  enableHSTS?: boolean;
+  frameDeny?: boolean;
+  xssProtection?: boolean;
+  noSniff?: boolean;
+  referrerPolicy?: string;
+}
+
+export function securityHeaders(config?: SecurityHeadersConfig) {
+  const csp = config?.contentSecurityPolicy ?? "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'";
+  return (_req: Request, res: Response, next: NextFunction): void => {
+    res.setHeader('Content-Security-Policy', csp);
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', config?.frameDeny !== false ? 'DENY' : 'SAMEORIGIN');
+    res.setHeader('X-XSS-Protection', '1; mode=block');
+    res.setHeader('Referrer-Policy', config?.referrerPolicy ?? 'strict-origin-when-cross-origin');
+    if (config?.enableHSTS !== false) {
+      res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+    }
+    res.removeHeader('X-Powered-By');
+    next();
+  };
+}
+
+// ── CORS Configuration ──────────────────────────────────────
+
+export interface CORSConfig {
+  origins?: string[];
+  methods?: string[];
+  allowHeaders?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+}
+
+export function corsMiddleware(config?: CORSConfig) {
+  const origins = config?.origins ?? ['*'];
+  const methods = config?.methods ?? ['GET', 'POST', 'OPTIONS'];
+  const headers = config?.allowHeaders ?? ['Content-Type', 'Authorization'];
+
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const origin = req.headers.origin ?? '';
+    if (origins.includes('*') || origins.includes(origin)) {
+      res.setHeader('Access-Control-Allow-Origin', origins.includes('*') ? '*' : origin);
+    }
+    res.setHeader('Access-Control-Allow-Methods', methods.join(', '));
+    res.setHeader('Access-Control-Allow-Headers', headers.join(', '));
+    if (config?.credentials) res.setHeader('Access-Control-Allow-Credentials', 'true');
+    if (config?.maxAge) res.setHeader('Access-Control-Max-Age', String(config.maxAge));
+    if (req.method === 'OPTIONS') { res.status(204).end(); return; }
+    next();
+  };
+}
+
+// ── API Key Rotation ────────────────────────────────────────
+
+export interface APIKeyEntry {
+  key: string;
+  label?: string;
+  createdAt: number;
+  expiresAt?: number;
+  active: boolean;
+}
+
+export class APIKeyManager {
+  private keys: APIKeyEntry[] = [];
+
+  addKey(key: string, opts?: { label?: string; expiresAt?: number }): void {
+    this.keys.push({ key, label: opts?.label, createdAt: Date.now(), expiresAt: opts?.expiresAt, active: true });
+  }
+
+  revokeKey(key: string): boolean {
+    const entry = this.keys.find(k => k.key === key);
+    if (entry) { entry.active = false; return true; }
+    return false;
+  }
+
+  isValid(key: string): boolean {
+    const entry = this.keys.find(k => k.key === key);
+    if (!entry || !entry.active) return false;
+    if (entry.expiresAt && Date.now() > entry.expiresAt) { entry.active = false; return false; }
+    return true;
+  }
+
+  rotateKey(oldKey: string, newKey: string): boolean {
+    const entry = this.keys.find(k => k.key === oldKey && k.active);
+    if (!entry) return false;
+    entry.active = false;
+    this.addKey(newKey, { label: entry.label });
+    return true;
+  }
+
+  listActive(): APIKeyEntry[] {
+    return this.keys.filter(k => k.active && (!k.expiresAt || Date.now() <= k.expiresAt));
+  }
+
+  cleanup(): number {
+    const before = this.keys.length;
+    this.keys = this.keys.filter(k => k.active && (!k.expiresAt || Date.now() <= k.expiresAt));
+    return before - this.keys.length;
+  }
+}
+
+// ── Input Validation Middleware ──────────────────────────────
+
+export function inputValidation() {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    if (req.body?.message && typeof req.body.message === 'string') {
+      const check = detectInjection(req.body.message);
+      if (!check.safe) {
+        res.status(400).json({ error: 'Input contains potentially unsafe content', threats: check.threats });
+        return;
+      }
+      // Limit message size
+      if (req.body.message.length > 100_000) {
+        res.status(413).json({ error: 'Message too large (max 100KB)' });
+        return;
+      }
+    }
+    next();
+  };
+}

package/src/index.ts

@@ -93,3 +93,10 @@ export type { CacheConfig, CacheEntry } from './core/cache';
 export { getSupportedLocales } from './i18n';
 export { createDataAnalystConfig } from './templates/data-analyst';
 export { createTeacherConfig } from './templates/teacher';
+
+// v1.0.0 modules
+export { OPCError, ProviderError, ValidationError, ConfigError, ChannelError, PluginError, RateLimitError, SecurityError, TimeoutError, wrapError, formatErrorForUser } from './core/errors';
+export { sanitizeInput, detectInjection, securityHeaders, corsMiddleware, APIKeyManager, inputValidation } from './core/security';
+export type { SecurityHeadersConfig, CORSConfig, APIKeyEntry } from './core/security';
+export { createLoggingPlugin, createAnalyticsPlugin, createRateLimitPlugin } from './plugins';
+export type { PluginManifest } from './plugins';

package/src/plugins/index.ts

@@ -1,10 +1,17 @@
-import type { ISkill, IChannel } from '../core/types';
+import type { ISkill, IChannel, Message } from '../core/types';
 import type { MCPTool } from '../tools/mcp';
+import { Logger } from '../core/logger';
 
 /**
- * Plugin lifecycle hooks.
+ * Plugin lifecycle hooks - v1.0.0
  */
 export interface PluginHooks {
+  onInit?: () => Promise<void>;
+  onMessage?: (message: Message) => Promise<Message | void>;
+  onResponse?: (message: Message, response: Message) => Promise<Message | void>;
+  onError?: (error: Error, context?: Record<string, unknown>) => Promise<void>;
+  onShutdown?: () => Promise<void>;
+  // Legacy aliases
   beforeInit?: () => Promise<void>;
   afterInit?: () => Promise<void>;
   beforeMessage?: (message: { content: string }) => Promise<void>;
@@ -13,7 +20,15 @@ export interface PluginHooks {
 }
 
 /**
- * Plugin interface — extend agent with skills, tools, channels, and lifecycle hooks.
+ * Plugin manifest in OAD: plugins: [{ name, config }]
+ */
+export interface PluginManifest {
+  name: string;
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Plugin interface - extend agent with skills, tools, channels, and lifecycle hooks.
  */
 export interface IPlugin {
   name: string;
@@ -27,9 +42,14 @@ export interface IPlugin {
 
 export class PluginManager {
   private plugins: Map<string, IPlugin> = new Map();
+  private logger = new Logger('plugins');
 
   register(plugin: IPlugin): void {
+    if (this.plugins.has(plugin.name)) {
+      this.logger.warn(`Plugin "${plugin.name}" already registered, replacing`);
+    }
     this.plugins.set(plugin.name, plugin);
+    this.logger.info(`Plugin registered: ${plugin.name}@${plugin.version}`);
   }
 
   unregister(name: string): void {
@@ -42,9 +62,7 @@ export class PluginManager {
 
   list(): { name: string; version: string; description?: string }[] {
     return Array.from(this.plugins.values()).map(({ name, version, description }) => ({
-      name,
-      version,
-      description,
+      name, version, description,
     }));
   }
 
@@ -56,9 +74,59 @@ export class PluginManager {
     for (const plugin of this.plugins.values()) {
       const hook = plugin.hooks?.[hookName];
       if (hook) {
-        await (hook as (...a: unknown[]) => Promise<void>)(...args);
+        try {
+          await (hook as (...a: unknown[]) => Promise<void>)(...args);
+        } catch (err) {
+          this.logger.error(`Plugin "${plugin.name}" hook "${hookName}" failed`, {
+            error: err instanceof Error ? err.message : String(err),
+          });
+          // Don't let one plugin break others
+        }
+      }
+    }
+  }
+
+  async runOnInit(): Promise<void> {
+    await this.runHook('onInit');
+    await this.runHook('beforeInit');
+    await this.runHook('afterInit');
+  }
+
+  async runOnMessage(message: Message): Promise<Message> {
+    let msg = message;
+    for (const plugin of this.plugins.values()) {
+      if (plugin.hooks?.onMessage) {
+        const result = await plugin.hooks.onMessage(msg);
+        if (result) msg = result;
+      }
+      if (plugin.hooks?.beforeMessage) {
+        await plugin.hooks.beforeMessage({ content: msg.content });
       }
     }
+    return msg;
+  }
+
+  async runOnResponse(message: Message, response: Message): Promise<Message> {
+    let resp = response;
+    for (const plugin of this.plugins.values()) {
+      if (plugin.hooks?.onResponse) {
+        const result = await plugin.hooks.onResponse(message, resp);
+        if (result) resp = result;
+      }
+      if (plugin.hooks?.afterMessage) {
+        await plugin.hooks.afterMessage({ content: message.content }, { content: resp.content });
+      }
+    }
+    return resp;
+  }
+
+  async runOnError(error: Error, context?: Record<string, unknown>): Promise<void> {
+    await this.runHook('onError', error, context);
+  }
+
+  async runOnShutdown(): Promise<void> {
+    await this.runHook('onShutdown');
+    await this.runHook('beforeShutdown');
   }
 
   getAllSkills(): ISkill[] {
@@ -85,3 +153,56 @@ export class PluginManager {
     return channels;
   }
 }
+
+// ── Built-in Plugins ────────────────────────────────────────
+
+export function createLoggingPlugin(): IPlugin {
+  const logger = new Logger('agent:messages');
+  return {
+    name: 'logging',
+    version: '1.0.0',
+    description: 'Logs all messages and responses',
+    hooks: {
+      onInit: async () => { logger.info('Agent initialized'); },
+      onMessage: async (msg: Message) => { logger.info(`← ${msg.role}: ${msg.content.slice(0, 100)}`); return undefined as any; },
+      onResponse: async (_msg: Message, resp: Message) => { logger.info(`→ ${resp.role}: ${resp.content.slice(0, 100)}`); return undefined as any; },
+      onError: async (err: Error) => { logger.error(`Error: ${err.message}`); },
+      onShutdown: async () => { logger.info('Agent shutting down'); },
+    },
+  };
+}
+
+export function createAnalyticsPlugin(): IPlugin {
+  const stats = { messages: 0, errors: 0, startedAt: 0 };
+  return {
+    name: 'analytics',
+    version: '1.0.0',
+    description: 'Tracks message counts and error rates',
+    hooks: {
+      onInit: async () => { stats.startedAt = Date.now(); },
+      onMessage: async () => { stats.messages++; return undefined as any; },
+      onError: async () => { stats.errors++; },
+    },
+  };
+}
+
+export function createRateLimitPlugin(maxPerMinute = 60): IPlugin {
+  const timestamps: number[] = [];
+  return {
+    name: 'rate-limit',
+    version: '1.0.0',
+    description: `Rate limits to ${maxPerMinute} messages/minute`,
+    hooks: {
+      onMessage: async () => {
+        const now = Date.now();
+        const windowStart = now - 60_000;
+        while (timestamps.length > 0 && timestamps[0] < windowStart) timestamps.shift();
+        if (timestamps.length >= maxPerMinute) {
+          throw new Error('Rate limit exceeded. Please slow down.');
+        }
+        timestamps.push(now);
+        return undefined as any;
+      },
+    },
+  };
+}

package/src/schema/oad.ts

@@ -48,6 +48,11 @@ export const HITLSchema = z.object({
   defaultAction: z.enum(['approve', 'deny']).default('deny'),
 });
 
+export const PluginRefSchema = z.object({
+  name: z.string(),
+  config: z.record(z.unknown()).optional(),
+});
+
 export const AuthSchema = z.object({
   enabled: z.boolean().default(false),
   apiKeys: z.array(z.string()).default([]),
@@ -131,6 +136,7 @@ export const SpecSchema = z.object({
   webhook: WebhookSchema.optional(),
   hitl: HITLSchema.optional(),
   auth: AuthSchema.optional(),
+  plugins: z.array(PluginRefSchema).optional(),
 });
 
 export const OADSchema = z.object({

package/tests/errors.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest';
+import { OPCError, ProviderError, ValidationError, ConfigError, ChannelError, PluginError, RateLimitError, SecurityError, TimeoutError, wrapError, formatErrorForUser } from '../src/core/errors';
+
+describe('Error Hierarchy', () => {
+  it('OPCError has code, hint, timestamp', () => {
+    const err = new OPCError('boom', { code: 'TEST', hint: 'try again' });
+    expect(err.message).toBe('boom');
+    expect(err.code).toBe('TEST');
+    expect(err.hint).toBe('try again');
+    expect(err.timestamp).toBeGreaterThan(0);
+    expect(err.toUserMessage()).toContain('try again');
+  });
+
+  it('toJSON serializes correctly', () => {
+    const err = new OPCError('test', { code: 'T1' });
+    const json = err.toJSON();
+    expect(json.name).toBe('OPCError');
+    expect(json.code).toBe('T1');
+  });
+
+  it('ProviderError includes provider', () => {
+    const err = new ProviderError('openai', 'API key invalid', { statusCode: 401 });
+    expect(err.provider).toBe('openai');
+    expect(err.statusCode).toBe(401);
+    expect(err.code).toBe('OPC_PROVIDER_ERROR');
+    expect(err instanceof OPCError).toBe(true);
+  });
+
+  it('ValidationError includes errors array', () => {
+    const err = new ValidationError('Invalid config', ['missing name', 'bad version'], 'metadata');
+    expect(err.errors).toEqual(['missing name', 'bad version']);
+    expect(err.field).toBe('metadata');
+  });
+
+  it('ConfigError', () => {
+    const err = new ConfigError('Missing oad.yaml');
+    expect(err.code).toBe('OPC_CONFIG_ERROR');
+  });
+
+  it('ChannelError', () => {
+    const err = new ChannelError('web', 'Port in use');
+    expect(err.channelType).toBe('web');
+  });
+
+  it('PluginError', () => {
+    const err = new PluginError('my-plugin', 'Init failed');
+    expect(err.pluginName).toBe('my-plugin');
+  });
+
+  it('RateLimitError', () => {
+    const err = new RateLimitError(undefined, 5000);
+    expect(err.retryAfterMs).toBe(5000);
+    expect(err.toUserMessage()).toContain('5 seconds');
+  });
+
+  it('SecurityError', () => {
+    const err = new SecurityError('Blocked');
+    expect(err.code).toBe('OPC_SECURITY_ERROR');
+  });
+
+  it('TimeoutError', () => {
+    const err = new TimeoutError('llm-call', 30000);
+    expect(err.message).toContain('30000ms');
+  });
+
+  it('wrapError wraps unknown errors', () => {
+    const wrapped = wrapError('string error');
+    expect(wrapped instanceof OPCError).toBe(true);
+    expect(wrapped.message).toBe('string error');
+
+    const native = wrapError(new Error('native'));
+    expect(native.message).toBe('native');
+
+    const existing = new ProviderError('x', 'y');
+    expect(wrapError(existing)).toBe(existing);
+  });
+
+  it('formatErrorForUser returns clean message', () => {
+    expect(formatErrorForUser(new RateLimitError())).toContain('Rate limit');
+    expect(formatErrorForUser(new Error('raw'))).toBe('raw');
+    expect(formatErrorForUser('string')).toBe('string');
+  });
+});

package/tests/security.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { sanitizeInput, detectInjection, APIKeyManager } from '../src/core/security';
+
+describe('Security', () => {
+  describe('sanitizeInput', () => {
+    it('strips script tags', () => {
+      expect(sanitizeInput('<script>alert(1)</script>hello')).not.toContain('<script');
+    });
+    it('encodes HTML entities', () => {
+      const result = sanitizeInput('a < b & c > d');
+      expect(result).toContain('&lt;');
+      expect(result).toContain('&amp;');
+      expect(result).toContain('&gt;');
+    });
+  });
+
+  describe('detectInjection', () => {
+    it('detects XSS', () => {
+      const r = detectInjection('<script>alert(1)</script>');
+      expect(r.safe).toBe(false);
+      expect(r.threats).toContain('xss');
+    });
+    it('passes clean input', () => {
+      expect(detectInjection('Hello world')).toEqual({ safe: true, threats: [] });
+    });
+  });
+
+  describe('APIKeyManager', () => {
+    it('add, validate, revoke', () => {
+      const mgr = new APIKeyManager();
+      mgr.addKey('key1', { label: 'test' });
+      expect(mgr.isValid('key1')).toBe(true);
+      expect(mgr.isValid('key2')).toBe(false);
+      mgr.revokeKey('key1');
+      expect(mgr.isValid('key1')).toBe(false);
+    });
+
+    it('rotate key', () => {
+      const mgr = new APIKeyManager();
+      mgr.addKey('old');
+      expect(mgr.rotateKey('old', 'new')).toBe(true);
+      expect(mgr.isValid('old')).toBe(false);
+      expect(mgr.isValid('new')).toBe(true);
+    });
+
+    it('expires keys', () => {
+      const mgr = new APIKeyManager();
+      mgr.addKey('expired', { expiresAt: Date.now() - 1000 });
+      expect(mgr.isValid('expired')).toBe(false);
+    });
+
+    it('listActive filters', () => {
+      const mgr = new APIKeyManager();
+      mgr.addKey('a');
+      mgr.addKey('b');
+      mgr.revokeKey('b');
+      expect(mgr.listActive().length).toBe(1);
+    });
+  });
+});