@enderworld/onlyapi 1.5.1

package/src/main.ts

@@ -0,0 +1,479 @@
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import sql from "mssql";
+import { createAdminService } from "./application/services/admin.service.js";
+import { createApiKeyService } from "./application/services/api-key.service.js";
+import { createAuthService } from "./application/services/auth.service.js";
+import { createHealthService } from "./application/services/health.service.js";
+import { createUserService } from "./application/services/user.service.js";
+import { AlertLevel } from "./core/ports/alert-sink.js";
+import type { Cache } from "./core/ports/cache.js";
+import { CircuitState } from "./core/ports/circuit-breaker.js";
+import type { OAuthProvider } from "./core/ports/oauth.js";
+import { createNoopAlertSink, createWebhookAlertSink } from "./infrastructure/alerting/webhook.js";
+import { createInMemoryCache } from "./infrastructure/cache/in-memory-cache.js";
+import { createRedisCache } from "./infrastructure/cache/redis-cache.js";
+import { loadConfig } from "./infrastructure/config/config.js";
+import { migrateUp } from "./infrastructure/database/migrations/runner.js";
+import {
+  createMssqlAccountLockout,
+  createMssqlApiKeyRepository,
+  createMssqlAuditLog,
+  createMssqlOAuthAccountRepo,
+  createMssqlPasswordHistory,
+  createMssqlRefreshTokenStore,
+  createMssqlTokenBlacklist,
+  createMssqlUserRepository,
+  createMssqlVerificationTokenRepo,
+  mssqlMigrateUp,
+} from "./infrastructure/database/mssql/index.js";
+import {
+  createPgAccountLockout,
+  createPgApiKeyRepository,
+  createPgAuditLog,
+  createPgOAuthAccountRepo,
+  createPgPasswordHistory,
+  createPgRefreshTokenStore,
+  createPgTokenBlacklist,
+  createPgUserRepository,
+  createPgVerificationTokenRepo,
+  pgMigrateUp,
+} from "./infrastructure/database/postgres/index.js";
+import { createSqliteAccountLockout } from "./infrastructure/database/sqlite-account-lockout.js";
+import { createSqliteApiKeyRepository } from "./infrastructure/database/sqlite-api-keys.js";
+import { createSqliteAuditLog } from "./infrastructure/database/sqlite-audit-log.js";
+import { createSqliteOAuthAccountRepo } from "./infrastructure/database/sqlite-oauth-accounts.js";
+import { createSqlitePasswordHistory } from "./infrastructure/database/sqlite-password-history.js";
+import { createSqliteRefreshTokenStore } from "./infrastructure/database/sqlite-refresh-token-store.js";
+import { createSqliteTokenBlacklist } from "./infrastructure/database/sqlite-token-blacklist.js";
+import { createSqliteUserRepository } from "./infrastructure/database/sqlite-user.repository.js";
+import { createSqliteVerificationTokenRepo } from "./infrastructure/database/sqlite-verification-tokens.js";
+import { createEventBus } from "./infrastructure/events/event-bus.js";
+import { createDomainEventFactory } from "./infrastructure/events/event-factory.js";
+import { createInMemoryWebhookRegistry } from "./infrastructure/events/in-memory-webhook-registry.js";
+import { createWebhookDispatcher } from "./infrastructure/events/webhook-dispatcher.js";
+import { createInMemoryJobQueue } from "./infrastructure/jobs/job-queue.js";
+import { createLogger } from "./infrastructure/logging/logger.js";
+import { createMetricsCollector } from "./infrastructure/metrics/prometheus.js";
+import { createGitHubOAuthProvider } from "./infrastructure/oauth/github.js";
+import { createGoogleOAuthProvider } from "./infrastructure/oauth/google.js";
+import { createCircuitBreaker } from "./infrastructure/resilience/circuit-breaker.js";
+import { createPasswordHasher } from "./infrastructure/security/password-hasher.js";
+import { createPasswordPolicy } from "./infrastructure/security/password-policy.js";
+import { createTokenService } from "./infrastructure/security/token-service.js";
+import { createTotpService } from "./infrastructure/security/totp-service.js";
+import { createWebSocketManager } from "./presentation/handlers/websocket.handler.js";
+import { createRouter } from "./presentation/routes/router.js";
+import { createServer } from "./presentation/server.js";
+import { printShutdown, printStartupBanner } from "./shared/cli.js";
+import { Container, Tokens } from "./shared/container.js";
+
+/**
+ * Bootstrap — compose the entire dependency graph, then start the server.
+ * Single entry point, fail-fast on misconfiguration.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: bootstrap wires all drivers/services — inherently branchy
+const bootstrap = async () => {
+  const bootStart = performance.now();
+
+  // 1. Config (validated, fails fast)
+  const config = loadConfig();
+
+  // 2. Infrastructure
+  const logger = createLogger(config.log.level, {}, config.log.format);
+  const passwordHasher = createPasswordHasher();
+  const tokenService = createTokenService(config.jwt);
+
+  // 3. Database — driver-based adapter selection
+  let db: Database | undefined;
+  // biome-ignore lint/suspicious/noExplicitAny: Bun.sql tagged template type
+  let pgSql: any | undefined;
+  let mssqlPool: sql.ConnectionPool | undefined;
+  let userRepo: ReturnType<typeof createSqliteUserRepository>;
+  let tokenBlacklist: ReturnType<typeof createSqliteTokenBlacklist>;
+  let accountLockout: ReturnType<typeof createSqliteAccountLockout>;
+  let auditLog: ReturnType<typeof createSqliteAuditLog>;
+  let verificationTokens: ReturnType<typeof createSqliteVerificationTokenRepo>;
+  let refreshTokenStore: ReturnType<typeof createSqliteRefreshTokenStore>;
+  let apiKeyRepo: ReturnType<typeof createSqliteApiKeyRepository>;
+  let passwordHistory: ReturnType<typeof createSqlitePasswordHistory>;
+  let oauthAccounts: ReturnType<typeof createSqliteOAuthAccountRepo>;
+
+  if (config.database.driver === "postgres") {
+    // Postgres via Bun.sql (zero-dep, native driver)
+    const dbUrl = config.database.url;
+    if (!dbUrl) {
+      logger.fatal("DATABASE_URL is required when DATABASE_DRIVER=postgres");
+      process.exit(1);
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: Bun.sql dynamic URL config
+    pgSql = new (Bun as any).SQL({ url: dbUrl });
+    logger.info("Postgres database connecting", { url: dbUrl.replace(/:[^:@]+@/, ":***@") });
+
+    await pgMigrateUp(pgSql, logger);
+
+    userRepo = createPgUserRepository(pgSql);
+    tokenBlacklist = createPgTokenBlacklist(pgSql);
+    accountLockout = createPgAccountLockout(pgSql, {
+      maxAttempts: config.lockout.maxAttempts,
+      lockoutDurationMs: config.lockout.durationMs,
+    });
+    auditLog = createPgAuditLog(pgSql);
+    verificationTokens = createPgVerificationTokenRepo(pgSql);
+    refreshTokenStore = createPgRefreshTokenStore(pgSql);
+    apiKeyRepo = createPgApiKeyRepository(pgSql);
+    passwordHistory = createPgPasswordHistory(pgSql);
+    oauthAccounts = createPgOAuthAccountRepo(pgSql);
+    logger.info("Postgres adapters initialized");
+  } else if (config.database.driver === "mssql") {
+    // SQL Server via mssql npm package (tedious TDS protocol)
+    const dbUrl = config.database.url;
+    if (!dbUrl) {
+      logger.fatal("DATABASE_URL is required when DATABASE_DRIVER=mssql");
+      process.exit(1);
+    }
+    mssqlPool = await sql.connect(dbUrl);
+    logger.info("SQL Server database connected", {
+      url: dbUrl.replace(/:[^:@]+@/, ":***@"),
+    });
+
+    await mssqlMigrateUp(mssqlPool, logger);
+
+    userRepo = createMssqlUserRepository(mssqlPool);
+    tokenBlacklist = createMssqlTokenBlacklist(mssqlPool);
+    accountLockout = createMssqlAccountLockout(mssqlPool, {
+      maxAttempts: config.lockout.maxAttempts,
+      lockoutDurationMs: config.lockout.durationMs,
+    });
+    auditLog = createMssqlAuditLog(mssqlPool);
+    verificationTokens = createMssqlVerificationTokenRepo(mssqlPool);
+    refreshTokenStore = createMssqlRefreshTokenStore(mssqlPool);
+    apiKeyRepo = createMssqlApiKeyRepository(mssqlPool);
+    passwordHistory = createMssqlPasswordHistory(mssqlPool);
+    oauthAccounts = createMssqlOAuthAccountRepo(mssqlPool);
+    logger.info("SQL Server adapters initialized");
+  } else {
+    // SQLite (default — zero deps, bun:sqlite built-in)
+    const dbPath = config.database.path;
+    const dbDir = dirname(dbPath);
+    if (!existsSync(dbDir)) {
+      mkdirSync(dbDir, { recursive: true });
+    }
+    db = new Database(dbPath, { create: true });
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA synchronous = NORMAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    logger.info("SQLite database opened", { path: dbPath });
+
+    await migrateUp(db, logger);
+
+    userRepo = createSqliteUserRepository(db);
+    tokenBlacklist = createSqliteTokenBlacklist(db);
+    accountLockout = createSqliteAccountLockout(db, {
+      maxAttempts: config.lockout.maxAttempts,
+      lockoutDurationMs: config.lockout.durationMs,
+    });
+    auditLog = createSqliteAuditLog(db);
+    verificationTokens = createSqliteVerificationTokenRepo(db);
+    refreshTokenStore = createSqliteRefreshTokenStore(db);
+    apiKeyRepo = createSqliteApiKeyRepository(db);
+    passwordHistory = createSqlitePasswordHistory(db);
+    oauthAccounts = createSqliteOAuthAccountRepo(db);
+  }
+
+  // 4. Cache — driver-based adapter selection
+  let cache: Cache;
+
+  if (config.redis.enabled) {
+    cache = await createRedisCache({
+      config: {
+        host: config.redis.host,
+        port: config.redis.port,
+        password: config.redis.password,
+        db: config.redis.db,
+      },
+      logger: logger.child({ service: "redis" }),
+    });
+    logger.info("Redis cache connected", { host: config.redis.host, port: config.redis.port });
+  } else {
+    cache = createInMemoryCache();
+    logger.info("In-memory cache initialized");
+  }
+
+  // 5. Security services
+  const totpService = createTotpService();
+  const passwordPolicy = createPasswordPolicy(config.passwordPolicy);
+
+  // 5a. OAuth providers (only registered when configured)
+  const oauthProviders = new Map<string, OAuthProvider>();
+  if (config.oauth.googleClientId && config.oauth.googleClientSecret) {
+    oauthProviders.set(
+      "google",
+      createGoogleOAuthProvider({
+        clientId: config.oauth.googleClientId,
+        clientSecret: config.oauth.googleClientSecret,
+      }),
+    );
+    logger.info("OAuth provider registered: google");
+  }
+  if (config.oauth.githubClientId && config.oauth.githubClientSecret) {
+    oauthProviders.set(
+      "github",
+      createGitHubOAuthProvider({
+        clientId: config.oauth.githubClientId,
+        clientSecret: config.oauth.githubClientSecret,
+      }),
+    );
+    logger.info("OAuth provider registered: github");
+  }
+
+  // 5b. Event system, webhooks, job queue
+  const eventBus = createEventBus({ logger: logger.child({ service: "event-bus" }) });
+  const eventFactory = createDomainEventFactory();
+  const webhookRegistry = createInMemoryWebhookRegistry();
+  const webhookDispatcher = createWebhookDispatcher({
+    registry: webhookRegistry,
+    logger: logger.child({ service: "webhook" }),
+  });
+  const jobQueue = createInMemoryJobQueue({
+    logger: logger.child({ service: "job-queue" }),
+  });
+
+  // Wire webhook dispatcher as a wildcard event subscriber
+  eventBus.subscribeAll((event) => webhookDispatcher.dispatch(event));
+
+  // 6. Register in DI container
+  Container.register(Tokens.Logger, logger);
+  Container.register(Tokens.Config, config);
+  Container.register(Tokens.Database, db);
+  Container.register(Tokens.PasswordHasher, passwordHasher);
+  Container.register(Tokens.TokenService, tokenService);
+  Container.register(Tokens.TokenBlacklist, tokenBlacklist);
+  Container.register(Tokens.AccountLockout, accountLockout);
+  Container.register(Tokens.UserRepository, userRepo);
+  Container.register(Tokens.AuditLog, auditLog);
+  Container.register(Tokens.VerificationTokenRepository, verificationTokens);
+  Container.register(Tokens.RefreshTokenStore, refreshTokenStore);
+  Container.register(Tokens.ApiKeyRepository, apiKeyRepo);
+  Container.register(Tokens.PasswordHistory, passwordHistory);
+  Container.register(Tokens.PasswordPolicy, passwordPolicy);
+  Container.register(Tokens.TotpService, totpService);
+  Container.register(Tokens.OAuthProviders, oauthProviders);
+  Container.register(Tokens.OAuthAccountRepository, oauthAccounts);
+
+  // 6b. Cache
+  Container.register(Tokens.Cache, cache);
+
+  // 6c. Event, webhook, and job queue registrations
+  Container.register(Tokens.EventBus, eventBus);
+  Container.register(Tokens.EventFactory, eventFactory);
+  Container.register(Tokens.WebhookRegistry, webhookRegistry);
+  Container.register(Tokens.WebhookDispatcher, webhookDispatcher);
+  Container.register(Tokens.JobQueue, jobQueue);
+
+  // 6d. Observability — metrics collector
+  const metricsCollector = createMetricsCollector();
+  Container.register(Tokens.MetricsCollector, metricsCollector);
+
+  // 6e. Alerting — webhook alert sink (or noop if no URL configured)
+  const alertSink = config.alerting.webhookUrl
+    ? createWebhookAlertSink({
+        url: config.alerting.webhookUrl,
+        timeoutMs: config.alerting.timeoutMs,
+        logger: logger.child({ service: "alerting" }),
+      })
+    : createNoopAlertSink();
+  Container.register(Tokens.AlertSink, alertSink);
+
+  // 6f. Resilience — circuit breaker for database operations
+  const dbCircuitBreaker = createCircuitBreaker({
+    name: "database",
+    failureThreshold: config.circuitBreaker.failureThreshold,
+    resetTimeoutMs: config.circuitBreaker.resetTimeoutMs,
+    halfOpenSuccessThreshold: config.circuitBreaker.halfOpenSuccessThreshold,
+    onStateChange: (cbName, from, to) => {
+      logger.warn("Circuit breaker state changed", {
+        circuitBreaker: cbName,
+        from,
+        to,
+      });
+
+      // Update metrics gauge: 0=closed, 1=half_open, 2=open
+      const stateValue = to === CircuitState.CLOSED ? 0 : to === CircuitState.HALF_OPEN ? 1 : 2;
+      metricsCollector.circuitBreakerState.set(stateValue, { name: cbName });
+
+      // Fire alerting hooks on state changes
+      if (to === CircuitState.OPEN) {
+        alertSink.send({
+          level: AlertLevel.CRITICAL,
+          title: `Circuit breaker OPEN: ${cbName}`,
+          message: `Circuit breaker "${cbName}" has opened after reaching failure threshold. Requests will be short-circuited.`,
+          timestamp: new Date().toISOString(),
+          source: "onlyApi",
+          metadata: { circuitBreaker: cbName, from, to },
+        });
+        metricsCollector.alertsSentTotal.inc({ level: "critical" });
+      } else if (to === CircuitState.CLOSED && from === CircuitState.HALF_OPEN) {
+        alertSink.send({
+          level: AlertLevel.RESOLVED,
+          title: `Circuit breaker CLOSED: ${cbName}`,
+          message: `Circuit breaker "${cbName}" has recovered and returned to normal operation.`,
+          timestamp: new Date().toISOString(),
+          source: "onlyApi",
+          metadata: { circuitBreaker: cbName, from, to },
+        });
+        metricsCollector.alertsSentTotal.inc({ level: "resolved" });
+      }
+    },
+  });
+
+  // 7. Application services
+  const authService = createAuthService({
+    userRepo,
+    passwordHasher,
+    tokenService,
+    tokenBlacklist,
+    accountLockout,
+    verificationTokens,
+    refreshTokenStore,
+    passwordHistory,
+    passwordPolicy,
+    totpService,
+    oauthProviders,
+    oauthAccounts,
+    logger: logger.child({ service: "auth" }),
+  });
+
+  const userService = createUserService({
+    userRepo,
+    passwordHasher,
+    logger: logger.child({ service: "user" }),
+  });
+
+  const healthService = createHealthService({
+    logger: logger.child({ service: "health" }),
+    version: "2.0.0",
+    circuitBreakers: [dbCircuitBreaker],
+  });
+
+  const adminService = createAdminService({
+    userRepo,
+    auditLog,
+    logger: logger.child({ service: "admin" }),
+  });
+
+  const apiKeyService = createApiKeyService({
+    apiKeyRepo,
+    logger: logger.child({ service: "api-key" }),
+  });
+
+  Container.register(Tokens.AuthService, authService);
+  Container.register(Tokens.UserService, userService);
+  Container.register(Tokens.HealthService, healthService);
+  Container.register(Tokens.AdminService, adminService);
+  Container.register(Tokens.ApiKeyService, apiKeyService);
+
+  // 8. Presentation
+  const router = createRouter({
+    authService,
+    userService,
+    healthService,
+    adminService,
+    apiKeyService,
+    tokenService,
+    metricsCollector,
+    oauthProviders,
+    eventBus,
+    webhookRegistry,
+    logger,
+  });
+
+  // 8b. WebSocket manager
+  const wsManager = createWebSocketManager({
+    tokenService,
+    eventBus,
+    logger: logger.child({ service: "websocket" }),
+  });
+  Container.register(Tokens.WebSocketManager, wsManager);
+
+  // Wire WebSocket manager as event subscriber (broadcast to WS clients)
+  eventBus.subscribeAll((event) => wsManager.broadcast(event));
+
+  const srv = createServer({ config, logger, router, metrics: metricsCollector, wsManager });
+
+  // 9. Start
+  const instance = srv.start();
+  jobQueue.start();
+
+  // 10. Print startup banner
+  const isCluster = Bun.env["WORKER_ID"] !== undefined;
+  if (!isCluster) {
+    printStartupBanner({
+      config,
+      bootTimeMs: performance.now() - bootStart,
+    });
+  }
+
+  // 11. Periodic token pruning (every 10 minutes)
+  const pruneInterval = setInterval(
+    async () => {
+      const blacklistResult = await tokenBlacklist.prune();
+      if (blacklistResult.ok && blacklistResult.value > 0) {
+        logger.debug("Pruned expired blacklisted tokens", { count: blacklistResult.value });
+      }
+
+      const verifyResult = await verificationTokens.prune();
+      if (verifyResult.ok && verifyResult.value > 0) {
+        logger.debug("Pruned expired verification tokens", { count: verifyResult.value });
+      }
+
+      const refreshResult = await refreshTokenStore.prune(30 * 24 * 60 * 60 * 1000);
+      if (refreshResult.ok && refreshResult.value > 0) {
+        logger.debug("Pruned revoked refresh token families", { count: refreshResult.value });
+      }
+    },
+    10 * 60 * 1000,
+  );
+
+  // 12. Graceful shutdown
+  const shutdown = (signal: string) => {
+    clearInterval(pruneInterval);
+    jobQueue.stop();
+    srv.flush(); // flush buffered access logs before exit
+    if (db) db.close(); // close SQLite connection
+    if (mssqlPool) mssqlPool.close(); // close SQL Server connection pool
+    cache.close(); // close cache (no-op for in-memory, QUIT for Redis)
+    printShutdown(signal);
+    instance.stop();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+  // 13. Unhandled rejection safety net
+  process.on("unhandledRejection", (reason) => {
+    logger.fatal("Unhandled promise rejection", {
+      error: reason instanceof Error ? reason.message : String(reason),
+      stack: reason instanceof Error ? reason.stack : undefined,
+    });
+
+    // Fire alert on fatal errors
+    alertSink.send({
+      level: AlertLevel.CRITICAL,
+      title: "Unhandled promise rejection",
+      message: reason instanceof Error ? reason.message : String(reason),
+      timestamp: new Date().toISOString(),
+      source: "onlyApi",
+      metadata: {
+        stack: reason instanceof Error ? reason.stack : undefined,
+      },
+    });
+    metricsCollector.alertsSentTotal.inc({ level: "critical" });
+  });
+
+  return instance;
+};
+
+bootstrap();

package/src/presentation/context.ts

@@ -0,0 +1,26 @@
+import type { Logger } from "../core/ports/logger.js";
+import type { TokenPayload } from "../core/ports/token-service.js";
+import type { RequestId } from "../core/types/brand.js";
+import type { TraceContext } from "../infrastructure/tracing/trace-context.js";
+import type { I18nContext } from "./i18n/index.js";
+
+/**
+ * Typed request context threaded through the middleware pipeline.
+ * Immutable — each middleware returns a new context with added fields.
+ */
+export interface RequestContext {
+  readonly requestId: RequestId;
+  readonly startTime: number;
+  readonly ip: string;
+  readonly method: string;
+  readonly path: string;
+  readonly auth?: TokenPayload | undefined;
+  /** W3C Trace Context — traceId + spanId for distributed tracing */
+  readonly trace: TraceContext;
+  /** Request-scoped logger with requestId pre-bound */
+  readonly logger: Logger;
+  /** API version resolved from URL path or Accept-Version header */
+  readonly apiVersion: "v1" | "v2";
+  /** i18n context with locale-bound translation function */
+  readonly i18n: I18nContext;
+}

package/src/presentation/handlers/admin.handler.ts

@@ -0,0 +1,114 @@
+import { banUserDto, changeRoleDto, listUsersDto } from "../../application/dtos/admin.dto.js";
+import type { AdminService } from "../../application/services/admin.service.js";
+import { UserRole } from "../../core/entities/user.entity.js";
+import type { Logger } from "../../core/ports/logger.js";
+import type { TokenService } from "../../core/ports/token-service.js";
+import type { UserId } from "../../core/types/brand.js";
+import type { RequestContext } from "../context.js";
+import { authenticate, authorise } from "../middleware/auth.js";
+import { validateBody } from "../middleware/validate.js";
+import { errorResponse, jsonResponse, noContentResponse } from "./response.js";
+
+/**
+ * Extract query parameters from a URL string without allocating a URL object.
+ */
+const extractQuery = (url: string): URLSearchParams => {
+  const qIdx = url.indexOf("?");
+  return new URLSearchParams(qIdx === -1 ? "" : url.substring(qIdx + 1));
+};
+
+export const adminHandlers = (
+  adminService: AdminService,
+  tokenService: TokenService,
+  logger: Logger,
+) => {
+  /** Shared admin auth check — requires ADMIN role */
+  const requireAdmin = async (req: Request, _ctx: RequestContext) => {
+    const authResult = await authenticate(req, tokenService);
+    if (!authResult.ok) return authResult;
+    return authorise(authResult.value, [UserRole.ADMIN]);
+  };
+
+  return {
+    listUsers: async (req: Request, ctx: RequestContext): Promise<Response> => {
+      const auth = await requireAdmin(req, ctx);
+      if (!auth.ok) {
+        logger.warn("Admin auth failed on listUsers", { requestId: ctx.requestId });
+        return errorResponse(auth.error, ctx.requestId);
+      }
+
+      const query = extractQuery(req.url);
+      const parsed = validateBody(listUsersDto, {
+        cursor: query.get("cursor") ?? undefined,
+        limit: query.get("limit") ?? "20",
+        search: query.get("search") ?? undefined,
+        role: query.get("role") ?? undefined,
+      });
+      if (!parsed.ok) return errorResponse(parsed.error, ctx.requestId);
+
+      const dto = { ...parsed.value, limit: parsed.value.limit ?? 20 };
+      const result = await adminService.listUsers(dto);
+      if (!result.ok) return errorResponse(result.error, ctx.requestId);
+
+      return jsonResponse(result.value);
+    },
+
+    getUser: async (req: Request, ctx: RequestContext, userId: string): Promise<Response> => {
+      const auth = await requireAdmin(req, ctx);
+      if (!auth.ok) return errorResponse(auth.error, ctx.requestId);
+
+      const result = await adminService.getUser(userId as UserId);
+      if (!result.ok) return errorResponse(result.error, ctx.requestId);
+
+      return jsonResponse(result.value);
+    },
+
+    changeRole: async (req: Request, ctx: RequestContext, userId: string): Promise<Response> => {
+      const auth = await requireAdmin(req, ctx);
+      if (!auth.ok) return errorResponse(auth.error, ctx.requestId);
+
+      const body = await req.json().catch(() => null);
+      const validated = validateBody(changeRoleDto, body);
+      if (!validated.ok) return errorResponse(validated.error, ctx.requestId);
+
+      const result = await adminService.changeRole(
+        userId as UserId,
+        validated.value,
+        auth.value.sub,
+        ctx.ip,
+      );
+      if (!result.ok) return errorResponse(result.error, ctx.requestId);
+
+      return jsonResponse(result.value);
+    },
+
+    banUser: async (req: Request, ctx: RequestContext, userId: string): Promise<Response> => {
+      const auth = await requireAdmin(req, ctx);
+      if (!auth.ok) return errorResponse(auth.error, ctx.requestId);
+
+      const body = await req.json().catch(() => null);
+      const validated = validateBody(banUserDto, body);
+      if (!validated.ok) return errorResponse(validated.error, ctx.requestId);
+
+      const result = await adminService.banUser(
+        userId as UserId,
+        validated.value,
+        auth.value.sub,
+        ctx.ip,
+      );
+      if (!result.ok) return errorResponse(result.error, ctx.requestId);
+
+      return noContentResponse();
+    },
+
+    unbanUser: async (req: Request, ctx: RequestContext, userId: string): Promise<Response> => {
+      const auth = await requireAdmin(req, ctx);
+      if (!auth.ok) return errorResponse(auth.error, ctx.requestId);
+
+      const result = await adminService.unbanUser(userId as UserId, auth.value.sub, ctx.ip);
+      if (!result.ok) return errorResponse(result.error, ctx.requestId);
+
+      return noContentResponse();
+    },
+  };
+};

package/src/presentation/handlers/api-key.handler.ts

@@ -0,0 +1,68 @@
+import { createApiKeyDto } from "../../application/dtos/auth.dto.js";
+import type { ApiKeyService } from "../../application/services/api-key.service.js";
+import type { Logger } from "../../core/ports/logger.js";
+import type { TokenService } from "../../core/ports/token-service.js";
+import type { RequestContext } from "../context.js";
+import { authenticate } from "../middleware/auth.js";
+import { validateBody } from "../middleware/validate.js";
+import { createdResponse, errorResponse, jsonResponse, noContentResponse } from "./response.js";
+
+export const apiKeyHandlers = (
+  apiKeyService: ApiKeyService,
+  tokenService: TokenService,
+  logger: Logger,
+) => ({
+  create: async (req: Request, ctx: RequestContext): Promise<Response> => {
+    const authResult = await authenticate(req, tokenService);
+    if (!authResult.ok) return errorResponse(authResult.error, ctx.requestId);
+
+    const body = await req.json().catch(() => null);
+    const validated = validateBody(createApiKeyDto, body);
+    if (!validated.ok) return errorResponse(validated.error, ctx.requestId);
+
+    const result = await apiKeyService.create(
+      authResult.value.sub,
+      validated.value.name,
+      validated.value.scopes ?? [],
+      validated.value.expiresInDays,
+    );
+    if (!result.ok) return errorResponse(result.error, ctx.requestId);
+
+    logger.info("API key created", {
+      requestId: ctx.requestId,
+      userId: authResult.value.sub,
+      keyId: result.value.key.id,
+    });
+
+    return createdResponse({
+      key: result.value.key,
+      rawKey: result.value.rawKey,
+    });
+  },
+
+  list: async (req: Request, ctx: RequestContext): Promise<Response> => {
+    const authResult = await authenticate(req, tokenService);
+    if (!authResult.ok) return errorResponse(authResult.error, ctx.requestId);
+
+    const result = await apiKeyService.list(authResult.value.sub);
+    if (!result.ok) return errorResponse(result.error, ctx.requestId);
+
+    return jsonResponse({ keys: result.value });
+  },
+
+  revoke: async (req: Request, ctx: RequestContext, keyId: string): Promise<Response> => {
+    const authResult = await authenticate(req, tokenService);
+    if (!authResult.ok) return errorResponse(authResult.error, ctx.requestId);
+
+    const result = await apiKeyService.revoke(keyId, authResult.value.sub);
+    if (!result.ok) return errorResponse(result.error, ctx.requestId);
+
+    logger.info("API key revoked", {
+      requestId: ctx.requestId,
+      userId: authResult.value.sub,
+      keyId,
+    });
+
+    return noContentResponse();
+  },
+});