@enderworld/onlyapi 1.5.1

package/src/cli/ui.ts

@@ -0,0 +1,189 @@
+/**
+ * CLI UI utilities — zero-dependency ANSI colors, spinner, and prompts.
+ * Follows the same style as the server startup banner.
+ */
+
+// ── ANSI escape sequences ──────────────────────────────────────────────
+
+const esc = (code: string) => `\x1b[${code}m`;
+const reset = esc("0");
+
+export const bold = (s: string) => `${esc("1")}${s}${reset}`;
+export const dim = (s: string) => `${esc("2")}${s}${reset}`;
+
+export const cyan = (s: string) => `${esc("36")}${s}${reset}`;
+export const green = (s: string) => `${esc("32")}${s}${reset}`;
+export const yellow = (s: string) => `${esc("33")}${s}${reset}`;
+export const magenta = (s: string) => `${esc("35")}${s}${reset}`;
+export const blue = (s: string) => `${esc("34")}${s}${reset}`;
+export const red = (s: string) => `${esc("31")}${s}${reset}`;
+export const gray = (s: string) => `${esc("90")}${s}${reset}`;
+export const white = (s: string) => `${esc("97")}${s}${reset}`;
+
+export const bgCyan = (s: string) => `${esc("46")}${esc("30")} ${s} ${reset}`;
+export const bgGreen = (s: string) => `${esc("42")}${esc("30")} ${s} ${reset}`;
+export const bgYellow = (s: string) => `${esc("43")}${esc("30")} ${s} ${reset}`;
+export const bgMagenta = (s: string) => `${esc("45")}${esc("97")} ${s} ${reset}`;
+export const bgRed = (s: string) => `${esc("41")}${esc("97")} ${s} ${reset}`;
+
+// ── Icons ───────────────────────────────────────────────────────────────
+
+export const icons = {
+  success: green("✔"),
+  error: red("✗"),
+  warning: yellow("⚠"),
+  info: cyan("ℹ"),
+  arrow: cyan("→"),
+  chevron: cyan("›"),
+  sparkle: magenta("✦"),
+  bolt: yellow("⚡"),
+  folder: blue("📁"),
+  file: gray("📄"),
+  gear: gray("⚙"),
+  rocket: magenta("🚀"),
+  package: cyan("📦"),
+} as const;
+
+// ── Logo ────────────────────────────────────────────────────────────────
+
+export const logo = (version: string): string => {
+  const lines = [
+    `${bold(cyan("  ┌─────────────────────────────────────────┐"))}`,
+    `${bold(cyan("  │"))}                                           ${bold(cyan("│"))}`,
+    `${bold(cyan("  │"))}   ${bold(white("⚡ onlyApi CLI"))}  ${dim(gray(`v${version}`))}                  ${bold(cyan("│"))}`,
+    `${bold(cyan("  │"))}   ${dim(gray("Zero-dep enterprise REST API on Bun"))}    ${bold(cyan("│"))}`,
+    `${bold(cyan("  │"))}                                           ${bold(cyan("│"))}`,
+    `${bold(cyan("  └─────────────────────────────────────────┘"))}`,
+  ];
+  return lines.join("\n");
+};
+
+// ── Output helpers ──────────────────────────────────────────────────────
+
+export const log = (msg: string) => process.stdout.write(`${msg}\n`);
+export const blank = () => process.stdout.write("\n");
+export const error = (msg: string) => process.stderr.write(`  ${icons.error} ${red(msg)}\n`);
+export const warn = (msg: string) => process.stdout.write(`  ${icons.warning} ${yellow(msg)}\n`);
+export const info = (msg: string) => process.stdout.write(`  ${icons.info} ${msg}\n`);
+export const success = (msg: string) => process.stdout.write(`  ${icons.success} ${green(msg)}\n`);
+export const step = (msg: string) => process.stdout.write(`  ${icons.chevron} ${msg}\n`);
+
+// ── Spinner ─────────────────────────────────────────────────────────────
+
+const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+
+export interface Spinner {
+  start: () => void;
+  stop: (finalMsg?: string) => void;
+  update: (msg: string) => void;
+}
+
+export const createSpinner = (message: string): Spinner => {
+  let frame = 0;
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let currentMsg = message;
+
+  const clear = () => {
+    process.stdout.write("\r\x1b[K");
+  };
+
+  return {
+    start() {
+      timer = setInterval(() => {
+        clear();
+        const icon = spinnerFrames[frame % spinnerFrames.length] ?? "⠋";
+        process.stdout.write(`  ${cyan(icon)} ${currentMsg}`);
+        frame++;
+      }, 80);
+    },
+    update(msg: string) {
+      currentMsg = msg;
+    },
+    stop(finalMsg?: string) {
+      if (timer) clearInterval(timer);
+      clear();
+      if (finalMsg) {
+        process.stdout.write(`  ${icons.success} ${green(finalMsg)}\n`);
+      }
+    },
+  };
+};
+
+// ── Prompt (simple stdin reader) ────────────────────────────────────────
+
+export const prompt = async (question: string, defaultValue?: string): Promise<string> => {
+  const suffix = defaultValue ? ` ${dim(`(${defaultValue})`)}` : "";
+  process.stdout.write(`  ${icons.chevron} ${question}${suffix}: `);
+
+  const reader = Bun.stdin.stream().getReader();
+  const { value } = await reader.read();
+  reader.releaseLock();
+
+  const input = value ? new TextDecoder().decode(value).trim() : "";
+  return input || defaultValue || "";
+};
+
+export const confirm = async (question: string, defaultYes = true): Promise<boolean> => {
+  const hint = defaultYes ? `${bold("Y")}/n` : `y/${bold("N")}`;
+  process.stdout.write(`  ${icons.chevron} ${question} ${dim(`[${hint}]`)}: `);
+
+  const reader = Bun.stdin.stream().getReader();
+  const { value } = await reader.read();
+  reader.releaseLock();
+
+  const input = value ? new TextDecoder().decode(value).trim().toLowerCase() : "";
+  if (input === "") return defaultYes;
+  return input === "y" || input === "yes";
+};
+
+// ── Table helper ────────────────────────────────────────────────────────
+
+export const printKeyValue = (pairs: readonly [string, string][]): void => {
+  const maxKey = Math.max(...pairs.map(([k]) => k.length));
+  for (const [key, value] of pairs) {
+    log(`  ${gray("│")} ${dim(key.padEnd(maxKey))}  ${white(value)}`);
+  }
+};
+
+// ── Section header ──────────────────────────────────────────────────────
+
+export const section = (title: string): void => {
+  blank();
+  log(`  ${bold(white(title))}`);
+  log(`  ${gray("─".repeat(50))}`);
+};
+
+// ── Box ─────────────────────────────────────────────────────────────────
+
+export const box = (lines: string[]): void => {
+  const maxLen = Math.max(...lines.map((l) => stripAnsi(l).length));
+  const border = gray("─".repeat(maxLen + 4));
+
+  log(`  ┌${border}┐`);
+  for (const line of lines) {
+    const padding = " ".repeat(maxLen - stripAnsi(line).length);
+    log(`  │  ${line}${padding}  │`);
+  }
+  log(`  └${border}┘`);
+};
+
+// ── Strip ANSI codes for length calculation ─────────────────────────────
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: intentional ANSI escape stripping
+const stripAnsi = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, "");
+
+// ── Duration formatter ─────────────────────────────────────────────────
+
+export const formatDuration = (ms: number): string => {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1000)}s`;
+};
+
+// ── Random string generator ────────────────────────────────────────────
+
+export const randomSecret = (length = 64): string => {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  const bytes = crypto.getRandomValues(new Uint8Array(length));
+  return Array.from(bytes, (b) => chars[b % chars.length]).join("");
+};

package/src/cluster.ts

@@ -0,0 +1,62 @@
+import { cpus } from "node:os";
+import { printClusterBanner, printShutdown } from "./shared/cli.js";
+
+/**
+ * Clustered entry point — spawns one worker per CPU core.
+ *
+ * Usage:  NODE_ENV=production bun src/cluster.ts
+ *
+ * Each worker runs its own Bun.serve() with reusePort: true,
+ * allowing the kernel to load-balance across all cores via SO_REUSEPORT.
+ * This is how you scale to millions of req/s on multi-core servers.
+ */
+
+const cpuCount = cpus().length;
+const numWorkers = Number(Bun.env["WORKERS"] ?? cpuCount);
+
+printClusterBanner(numWorkers, cpuCount);
+
+const workers: Array<ReturnType<typeof Bun.spawn>> = [];
+
+for (let i = 0; i < numWorkers; i++) {
+  const worker = Bun.spawn(["bun", "src/main.ts"], {
+    env: {
+      ...process.env,
+      WORKER_ID: String(i),
+    },
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  workers.push(worker);
+}
+
+// Forward SIGINT/SIGTERM to all workers for graceful shutdown
+const shutdown = (signal: string) => {
+  printShutdown(signal);
+  for (const w of workers) {
+    w.kill();
+  }
+  process.exit(0);
+};
+
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+// Monitor worker health
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
+const yellow = (s: string) => `\x1b[33m${s}\x1b[0m`;
+const green = (s: string) => `\x1b[32m${s}\x1b[0m`;
+const white = (s: string) => `\x1b[97m${s}\x1b[0m`;
+const bold = (s: string) => `\x1b[1m${s}\x1b[0m`;
+
+for (const [i, worker] of workers.entries()) {
+  // Log when worker becomes ready
+  process.stdout.write(`  ${green("✓")} ${dim("Worker")} ${bold(white(`#${i}`))} ${dim("ready")} ${dim(`(PID ${worker.pid})`)}
+`);
+
+  worker.exited.then((code) => {
+    const icon = code === 0 ? green("●") : yellow("●");
+    process.stdout.write(`  ${icon} ${dim("Worker")} ${bold(white(`#${i}`))} ${dim("exited")} ${dim(`(code ${code})`)}
+`);
+  });
+}

package/src/core/entities/index.ts

@@ -0,0 +1 @@
+export { type User, type UserRole, UserRole as UserRoles } from "./user.entity.js";

package/src/core/entities/user.entity.ts

@@ -0,0 +1,24 @@
+import type { Timestamp, UserId } from "../types/index.js";
+
+/**
+ * User entity — pure data, no behaviour, no framework deps.
+ */
+export interface User {
+  readonly id: UserId;
+  readonly email: string;
+  readonly passwordHash: string;
+  readonly role: UserRole;
+  readonly emailVerified: boolean;
+  readonly mfaEnabled: boolean;
+  readonly mfaSecret: string | null;
+  readonly passwordChangedAt: Timestamp | null;
+  readonly createdAt: Timestamp;
+  readonly updatedAt: Timestamp;
+}
+
+export const UserRole = {
+  ADMIN: "admin",
+  USER: "user",
+} as const;
+
+export type UserRole = (typeof UserRole)[keyof typeof UserRole];

package/src/core/errors/app-error.ts

@@ -0,0 +1,81 @@
+/**
+ * Canonical application error — every failure in the system is expressed
+ * as an AppError so HTTP, logging, and metrics layers have a single shape.
+ */
+
+export const ErrorCode = {
+  // Client errors
+  BAD_REQUEST: "BAD_REQUEST",
+  UNAUTHORIZED: "UNAUTHORIZED",
+  FORBIDDEN: "FORBIDDEN",
+  NOT_FOUND: "NOT_FOUND",
+  CONFLICT: "CONFLICT",
+  RATE_LIMITED: "RATE_LIMITED",
+  VALIDATION: "VALIDATION",
+  // Server errors
+  INTERNAL: "INTERNAL",
+  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+  TIMEOUT: "TIMEOUT",
+} as const;
+
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+export interface AppError {
+  readonly code: ErrorCode;
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+  readonly cause?: unknown;
+}
+
+const STATUS_MAP: Record<ErrorCode, number> = {
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  RATE_LIMITED: 429,
+  VALIDATION: 422,
+  INTERNAL: 500,
+  SERVICE_UNAVAILABLE: 503,
+  TIMEOUT: 504,
+};
+
+export const httpStatus = (code: ErrorCode): number => STATUS_MAP[code];
+
+/** Factory helpers */
+export const appError = (
+  code: ErrorCode,
+  message: string,
+  details?: Record<string, unknown>,
+  cause?: unknown,
+): AppError => {
+  const error: AppError = { code, message };
+  if (details !== undefined) {
+    return { ...error, details, cause };
+  }
+  if (cause !== undefined) {
+    return { ...error, cause };
+  }
+  return error;
+};
+
+export const badRequest = (msg: string, details?: Record<string, unknown>): AppError =>
+  appError(ErrorCode.BAD_REQUEST, msg, details);
+
+export const unauthorized = (msg = "Unauthorized"): AppError =>
+  appError(ErrorCode.UNAUTHORIZED, msg);
+
+export const forbidden = (msg = "Forbidden"): AppError => appError(ErrorCode.FORBIDDEN, msg);
+
+export const notFound = (resource: string): AppError =>
+  appError(ErrorCode.NOT_FOUND, `${resource} not found`);
+
+export const conflict = (msg: string): AppError => appError(ErrorCode.CONFLICT, msg);
+
+export const rateLimited = (): AppError => appError(ErrorCode.RATE_LIMITED, "Too many requests");
+
+export const validation = (details: Record<string, unknown>): AppError =>
+  appError(ErrorCode.VALIDATION, "Validation failed", details);
+
+export const internal = (msg = "Internal server error", cause?: unknown): AppError =>
+  appError(ErrorCode.INTERNAL, msg, undefined, cause);

package/src/core/errors/index.ts

@@ -0,0 +1,15 @@
+export {
+  type AppError,
+  type ErrorCode,
+  ErrorCode as ErrorCodes,
+  httpStatus,
+  appError,
+  badRequest,
+  unauthorized,
+  forbidden,
+  notFound,
+  conflict,
+  rateLimited,
+  validation,
+  internal,
+} from "./app-error.js";

package/src/core/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Core barrel — the innermost ring. Zero external dependencies.
+ */
+export * from "./types/index.js";
+export * from "./errors/index.js";
+export * from "./entities/index.js";
+export * from "./ports/index.js";

package/src/core/ports/account-lockout.ts

@@ -0,0 +1,15 @@
+import type { AppError } from "../errors/app-error.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Port: Account Lockout
+ * Tracks failed login attempts and determines if an account is locked.
+ */
+export interface AccountLockout {
+  /** Record a failed login attempt. Returns whether the account is now locked. */
+  recordFailedAttempt(email: string): Promise<Result<boolean, AppError>>;
+  /** Reset failed attempts on successful login */
+  resetAttempts(email: string): Promise<Result<void, AppError>>;
+  /** Check if account is currently locked. Returns lock expiry time or null. */
+  isLocked(email: string): Promise<Result<number | null, AppError>>;
+}

package/src/core/ports/alert-sink.ts

@@ -0,0 +1,27 @@
+/**
+ * Alert sink port — webhook/notification interface for critical events.
+ */
+
+export const AlertLevel = {
+  WARNING: "warning",
+  CRITICAL: "critical",
+  RESOLVED: "resolved",
+} as const;
+
+export type AlertLevel = (typeof AlertLevel)[keyof typeof AlertLevel];
+
+export interface AlertPayload {
+  readonly level: AlertLevel;
+  readonly title: string;
+  readonly message: string;
+  readonly timestamp: string;
+  readonly source: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface AlertSink {
+  /** Send an alert notification */
+  send(payload: AlertPayload): Promise<void>;
+  /** Check if the alert sink is configured and available */
+  readonly enabled: boolean;
+}

package/src/core/ports/api-key.ts

@@ -0,0 +1,37 @@
+import type { AppError } from "../errors/app-error.js";
+import type { UserId } from "../types/brand.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Port: API Key Repository
+ * Manages hashed API keys for service-to-service authentication.
+ */
+
+export interface ApiKey {
+  readonly id: string;
+  readonly userId: UserId;
+  readonly name: string;
+  readonly keyPrefix: string;
+  readonly scopes: readonly string[];
+  readonly expiresAt: number | null;
+  readonly lastUsedAt: number | null;
+  readonly createdAt: number;
+}
+
+export interface ApiKeyRepository {
+  /** Create a new API key. Returns the full key (shown once). */
+  create(
+    userId: UserId,
+    name: string,
+    scopes: readonly string[],
+    expiresAt?: number,
+  ): Promise<Result<{ key: ApiKey; rawKey: string }, AppError>>;
+  /** Verify a raw API key. Returns the key metadata if valid. */
+  verify(rawKey: string): Promise<Result<ApiKey, AppError>>;
+  /** List all API keys for a user (key hashes are never returned) */
+  listByUser(userId: UserId): Promise<Result<readonly ApiKey[], AppError>>;
+  /** Revoke (delete) an API key */
+  revoke(id: string, userId: UserId): Promise<Result<void, AppError>>;
+  /** Update last used timestamp */
+  touch(id: string): Promise<Result<void, AppError>>;
+}

package/src/core/ports/audit-log.ts

@@ -0,0 +1,46 @@
+import type { AppError } from "../errors/app-error.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Port: Audit Log — append-only ledger of significant system events.
+ * Records who did what, when, and from which IP address.
+ */
+
+export interface AuditEntry {
+  readonly id: string;
+  readonly userId: string | null;
+  readonly action: AuditAction;
+  readonly resource: string;
+  readonly resourceId: string | null;
+  readonly detail: string | null;
+  readonly ip: string;
+  readonly timestamp: number;
+}
+
+export const AuditAction = {
+  USER_REGISTERED: "USER_REGISTERED",
+  USER_LOGGED_IN: "USER_LOGGED_IN",
+  USER_LOGGED_OUT: "USER_LOGGED_OUT",
+  USER_LOGIN_FAILED: "USER_LOGIN_FAILED",
+  USER_UPDATED: "USER_UPDATED",
+  USER_DELETED: "USER_DELETED",
+  USER_BANNED: "USER_BANNED",
+  USER_UNBANNED: "USER_UNBANNED",
+  USER_ROLE_CHANGED: "USER_ROLE_CHANGED",
+  TOKEN_REFRESHED: "TOKEN_REFRESHED",
+  ACCOUNT_LOCKED: "ACCOUNT_LOCKED",
+} as const;
+
+export type AuditAction = (typeof AuditAction)[keyof typeof AuditAction];
+
+export interface AuditLog {
+  append(entry: Omit<AuditEntry, "id" | "timestamp">): Promise<Result<void, AppError>>;
+  query(options: AuditQueryOptions): Promise<Result<readonly AuditEntry[], AppError>>;
+}
+
+export interface AuditQueryOptions {
+  readonly userId?: string | undefined;
+  readonly action?: AuditAction | undefined;
+  readonly limit?: number | undefined;
+  readonly since?: number | undefined;
+}

package/src/core/ports/cache.ts

@@ -0,0 +1,24 @@
+/**
+ * Port: Cache — generic key-value cache abstraction.
+ * Implementations: in-memory (Map), Redis.
+ */
+
+import type { AppError } from "../errors/app-error.js";
+import type { Result } from "../types/result.js";
+
+export interface Cache {
+  /** Get a value by key. Returns null if not found or expired. */
+  get<T = unknown>(key: string): Promise<Result<T | null, AppError>>;
+  /** Set a value with optional TTL in milliseconds. */
+  set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<Result<void, AppError>>;
+  /** Delete a key. Returns true if it existed. */
+  del(key: string): Promise<Result<boolean, AppError>>;
+  /** Check if a key exists. */
+  has(key: string): Promise<Result<boolean, AppError>>;
+  /** Increment a numeric value by delta (default 1). Creates with value=delta if key absent. */
+  incr(key: string, delta?: number): Promise<Result<number, AppError>>;
+  /** Delete all keys matching a glob pattern (e.g. "rate:*"). */
+  delPattern(pattern: string): Promise<Result<number, AppError>>;
+  /** Close the connection / release resources. */
+  close(): Promise<void>;
+}

package/src/core/ports/circuit-breaker.ts

@@ -0,0 +1,42 @@
+/**
+ * Circuit breaker port — resilience pattern for external service calls.
+ *
+ * States:
+ *   CLOSED   → normal operation; failures counted
+ *   OPEN     → requests short-circuited; waiting for reset timeout
+ *   HALF_OPEN → limited probes allowed to test recovery
+ */
+
+export const CircuitState = {
+  CLOSED: "CLOSED",
+  OPEN: "OPEN",
+  HALF_OPEN: "HALF_OPEN",
+} as const;
+
+export type CircuitState = (typeof CircuitState)[keyof typeof CircuitState];
+
+export interface CircuitBreakerOptions {
+  /** Name for identification and metrics */
+  readonly name: string;
+  /** Number of failures before opening (default: 5) */
+  readonly failureThreshold: number;
+  /** Time in ms before OPEN → HALF_OPEN (default: 30_000) */
+  readonly resetTimeoutMs: number;
+  /** Number of successful probes in HALF_OPEN before closing (default: 2) */
+  readonly halfOpenSuccessThreshold: number;
+  /** Called on state change */
+  readonly onStateChange?: (name: string, from: CircuitState, to: CircuitState) => void;
+}
+
+export interface CircuitBreaker {
+  /** Execute a function through the circuit breaker */
+  execute<T>(fn: () => Promise<T>): Promise<T>;
+  /** Get current state */
+  readonly state: CircuitState;
+  /** Get name */
+  readonly name: string;
+  /** Get failure count in current window */
+  readonly failureCount: number;
+  /** Reset to CLOSED state */
+  reset(): void;
+}

package/src/core/ports/event-bus.ts

@@ -0,0 +1,78 @@
+/**
+ * Domain event system — typed events emitted by application services
+ * and consumed by subscribers (webhooks, SSE, WebSocket, audit log, etc.).
+ *
+ * Zero-dependency, strongly typed, Result-based.
+ */
+
+import type { UserId } from "../types/brand.js";
+
+// ─── Domain Event Types ───
+
+export const DomainEventType = {
+  USER_REGISTERED: "user.registered",
+  USER_DELETED: "user.deleted",
+  USER_UPDATED: "user.updated",
+  LOGIN_SUCCESS: "login.success",
+  LOGIN_FAILED: "login.failed",
+  LOGOUT: "logout",
+  PASSWORD_CHANGED: "password.changed",
+  PASSWORD_RESET: "password.reset",
+  EMAIL_VERIFIED: "email.verified",
+  MFA_ENABLED: "mfa.enabled",
+  MFA_DISABLED: "mfa.disabled",
+  API_KEY_CREATED: "api_key.created",
+  API_KEY_REVOKED: "api_key.revoked",
+  ACCOUNT_LOCKED: "account.locked",
+  ACCOUNT_UNLOCKED: "account.unlocked",
+} as const;
+
+export type DomainEventType = (typeof DomainEventType)[keyof typeof DomainEventType];
+
+// ─── Domain Event ───
+
+export interface DomainEvent<T extends DomainEventType = DomainEventType> {
+  /** Unique event ID */
+  readonly id: string;
+  /** Event type discriminator */
+  readonly type: T;
+  /** ISO 8601 timestamp */
+  readonly timestamp: string;
+  /** User who triggered the event (if applicable) */
+  readonly userId?: UserId | undefined;
+  /** Event-specific payload */
+  readonly payload: Readonly<Record<string, unknown>>;
+  /** Source IP address */
+  readonly ip?: string | undefined;
+}
+
+// ─── Event Handler ───
+
+export type EventHandler = (event: DomainEvent) => void | Promise<void>;
+
+// ─── Event Bus Port ───
+
+export interface EventBus {
+  /**
+   * Publish a domain event to all subscribers.
+   * Fire-and-forget semantics — errors in handlers are logged, not propagated.
+   */
+  publish(event: DomainEvent): void;
+
+  /**
+   * Subscribe to a specific event type.
+   * Returns an unsubscribe function.
+   */
+  subscribe(type: DomainEventType, handler: EventHandler): () => void;
+
+  /**
+   * Subscribe to ALL event types (wildcard).
+   * Returns an unsubscribe function.
+   */
+  subscribeAll(handler: EventHandler): () => void;
+
+  /**
+   * Number of registered handlers (for diagnostics).
+   */
+  readonly handlerCount: number;
+}