@enderworld/onlyapi 1.5.1

package/src/core/ports/index.ts

@@ -0,0 +1,62 @@
+export type {
+  UserRepository,
+  CreateUserData,
+  UpdateUserData,
+  UserListOptions,
+} from "./user.repository.js";
+export type { PasswordHasher } from "./password-hasher.js";
+export type { TokenService, TokenPayload, TokenPair } from "./token-service.js";
+export type { Logger, LogLevel, LogEntry } from "./logger.js";
+export type { TokenBlacklist } from "./token-blacklist.js";
+export type { AccountLockout } from "./account-lockout.js";
+export type { AuditLog, AuditEntry, AuditQueryOptions } from "./audit-log.js";
+export { AuditAction } from "./audit-log.js";
+export type {
+  MetricsCollector,
+  Counter,
+  Histogram,
+  Gauge,
+  HistogramSnapshot,
+} from "./metrics.js";
+export type {
+  CircuitBreaker,
+  CircuitBreakerOptions,
+} from "./circuit-breaker.js";
+export { CircuitState } from "./circuit-breaker.js";
+export type { RetryPolicy, RetryOptions } from "./retry.js";
+export type { AlertSink, AlertPayload } from "./alert-sink.js";
+export { AlertLevel } from "./alert-sink.js";
+export type {
+  VerificationToken,
+  VerificationTokenRepository,
+} from "./verification-token.js";
+export { VerificationTokenType } from "./verification-token.js";
+export type {
+  RefreshTokenFamily,
+  RefreshTokenStore,
+} from "./refresh-token-store.js";
+export type { ApiKey, ApiKeyRepository } from "./api-key.js";
+export type { PasswordHistory, PasswordHistoryEntry } from "./password-history.js";
+export type { TotpService } from "./totp-service.js";
+export type {
+  OAuthProvider,
+  OAuthUserInfo,
+  OAuthAccount,
+  OAuthAccountRepository,
+} from "./oauth.js";
+export type {
+  PasswordPolicy,
+  PasswordPolicyConfig,
+  PasswordPolicyResult,
+} from "./password-policy.js";
+export type { DomainEvent, DomainEventType, EventBus, EventHandler } from "./event-bus.js";
+export { DomainEventType as DomainEventTypes } from "./event-bus.js";
+export type {
+  WebhookSubscription,
+  CreateWebhookData,
+  WebhookDelivery,
+  WebhookRegistry,
+} from "./webhook.js";
+export type { Job, JobHandler, SubmitJobOptions, JobQueue, JobQueueStats } from "./job-queue.js";
+export { JobStatus } from "./job-queue.js";
+export type { Cache } from "./cache.js";

package/src/core/ports/job-queue.ts

@@ -0,0 +1,73 @@
+/**
+ * Background job queue port — async task processing with retry.
+ *
+ * Jobs are submitted and executed asynchronously. Failed jobs are retried
+ * with exponential backoff up to maxRetries.
+ */
+
+import type { AppError } from "../errors/app-error.js";
+import type { Result } from "../types/result.js";
+
+export const JobStatus = {
+  PENDING: "pending",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  DEAD: "dead",
+} as const;
+
+export type JobStatus = (typeof JobStatus)[keyof typeof JobStatus];
+
+export interface Job {
+  readonly id: string;
+  readonly type: string;
+  readonly payload: Readonly<Record<string, unknown>>;
+  readonly status: JobStatus;
+  readonly attempts: number;
+  readonly maxRetries: number;
+  /** ISO 8601 — when the job should next be attempted */
+  readonly runAt: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  /** Last error message (if failed) */
+  readonly lastError?: string | undefined;
+}
+
+export type JobHandler = (payload: Readonly<Record<string, unknown>>) => Promise<void>;
+
+export interface SubmitJobOptions {
+  readonly type: string;
+  readonly payload: Readonly<Record<string, unknown>>;
+  /** Max retry attempts (default: 3) */
+  readonly maxRetries?: number | undefined;
+  /** Delay before first run in ms (default: 0 = immediate) */
+  readonly delayMs?: number | undefined;
+}
+
+export interface JobQueue {
+  /** Submit a job for async processing */
+  submit(options: SubmitJobOptions): Result<Job, AppError>;
+
+  /** Register a handler for a job type */
+  registerHandler(type: string, handler: JobHandler): void;
+
+  /** Start processing jobs (called once at boot) */
+  start(): void;
+
+  /** Stop processing (graceful shutdown) */
+  stop(): void;
+
+  /** Get job by ID */
+  getJob(id: string): Result<Job | null, AppError>;
+
+  /** Get queue statistics */
+  stats(): Result<JobQueueStats, AppError>;
+}
+
+export interface JobQueueStats {
+  readonly pending: number;
+  readonly running: number;
+  readonly completed: number;
+  readonly failed: number;
+  readonly dead: number;
+}

package/src/core/ports/logger.ts

@@ -0,0 +1,21 @@
+/**
+ * Port: Logger — structured, level-based logging contract.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+
+export interface LogEntry {
+  readonly level: LogLevel;
+  readonly message: string;
+  readonly timestamp: string;
+  readonly requestId?: string | undefined;
+  readonly [key: string]: unknown;
+}
+
+export interface Logger {
+  debug(msg: string, meta?: Record<string, unknown>): void;
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+  fatal(msg: string, meta?: Record<string, unknown>): void;
+  child(bindings: Record<string, unknown>): Logger;
+}

package/src/core/ports/metrics.ts

@@ -0,0 +1,49 @@
+/**
+ * Metrics collector port — Prometheus-compatible metrics interface.
+ * The core defines WHAT metrics we track; infrastructure decides HOW.
+ */
+
+export interface Counter {
+  inc(labels?: Record<string, string>, value?: number): void;
+  get(labels?: Record<string, string>): number;
+}
+
+export interface Histogram {
+  observe(value: number, labels?: Record<string, string>): void;
+  /** Returns { count, sum, buckets: Map<number, number> } per label set */
+  get(labels?: Record<string, string>): HistogramSnapshot | undefined;
+}
+
+export interface Gauge {
+  set(value: number, labels?: Record<string, string>): void;
+  inc(labels?: Record<string, string>, value?: number): void;
+  dec(labels?: Record<string, string>, value?: number): void;
+  get(labels?: Record<string, string>): number;
+}
+
+export interface HistogramSnapshot {
+  readonly count: number;
+  readonly sum: number;
+  readonly buckets: ReadonlyMap<number, number>;
+}
+
+export interface MetricsCollector {
+  /** Total HTTP requests */
+  readonly httpRequestsTotal: Counter;
+  /** HTTP request duration in milliseconds */
+  readonly httpRequestDurationMs: Histogram;
+  /** Currently active connections */
+  readonly httpActiveConnections: Gauge;
+  /** Total HTTP errors (4xx + 5xx) */
+  readonly httpErrorsTotal: Counter;
+  /** Circuit breaker state changes */
+  readonly circuitBreakerState: Gauge;
+  /** Alert notifications sent */
+  readonly alertsSentTotal: Counter;
+
+  /** Serialize all metrics to Prometheus text exposition format */
+  serialize(): string;
+
+  /** Reset all metrics (useful for testing) */
+  reset(): void;
+}

package/src/core/ports/oauth.ts

@@ -0,0 +1,55 @@
+import type { AppError } from "../errors/app-error.js";
+import type { UserId } from "../types/brand.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Port: OAuth Provider
+ * Adapters for external OAuth2 providers (Google, GitHub, etc.)
+ */
+
+export interface OAuthUserInfo {
+  readonly providerId: string;
+  readonly email: string;
+  readonly name?: string;
+}
+
+export interface OAuthProvider {
+  /** Provider name (e.g., "google", "github") */
+  readonly name: string;
+  /** Build the authorization URL for the user to visit */
+  getAuthorizationUrl(state: string, redirectUri: string): string;
+  /** Exchange an authorization code for user info */
+  exchangeCode(code: string, redirectUri: string): Promise<Result<OAuthUserInfo, AppError>>;
+}
+
+/**
+ * Port: OAuth Account Repository
+ * Links external OAuth identities to internal user accounts.
+ */
+export interface OAuthAccount {
+  readonly id: string;
+  readonly userId: UserId;
+  readonly provider: string;
+  readonly providerUserId: string;
+  readonly email: string | null;
+  readonly createdAt: number;
+}
+
+export interface OAuthAccountRepository {
+  /** Link an OAuth identity to a user */
+  link(
+    userId: UserId,
+    provider: string,
+    providerUserId: string,
+    email: string | null,
+  ): Promise<Result<OAuthAccount, AppError>>;
+  /** Find a user by their OAuth identity */
+  findByProvider(
+    provider: string,
+    providerUserId: string,
+  ): Promise<Result<OAuthAccount | null, AppError>>;
+  /** List all OAuth accounts for a user */
+  listByUser(userId: UserId): Promise<Result<readonly OAuthAccount[], AppError>>;
+  /** Unlink an OAuth identity from a user */
+  unlink(id: string, userId: UserId): Promise<Result<void, AppError>>;
+}

package/src/core/ports/password-hasher.ts

@@ -0,0 +1,10 @@
+import type { AppError } from "../errors/app-error.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Port: Password Hasher
+ */
+export interface PasswordHasher {
+  hash(plain: string): Promise<Result<string, AppError>>;
+  verify(plain: string, hash: string): Promise<Result<boolean, AppError>>;
+}

package/src/core/ports/password-history.ts

@@ -0,0 +1,23 @@
+import type { AppError } from "../errors/app-error.js";
+import type { UserId } from "../types/brand.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Port: Password History
+ * Stores past password hashes to prevent reuse.
+ */
+export interface PasswordHistoryEntry {
+  readonly id: string;
+  readonly userId: UserId;
+  readonly passwordHash: string;
+  readonly createdAt: number;
+}
+
+export interface PasswordHistory {
+  /** Add a password hash to the user's history */
+  add(userId: UserId, passwordHash: string): Promise<Result<void, AppError>>;
+  /** Get the last N password hashes for a user */
+  getRecent(userId: UserId, count: number): Promise<Result<readonly string[], AppError>>;
+  /** Prune old history beyond the configured retention limit */
+  prune(userId: UserId, keepCount: number): Promise<Result<void, AppError>>;
+}

package/src/core/ports/password-policy.ts

@@ -0,0 +1,43 @@
+import type { AppError } from "../errors/app-error.js";
+import type { UserId } from "../types/brand.js";
+import type { Result } from "../types/result.js";
+import type { PasswordHasher } from "./password-hasher.js";
+import type { PasswordHistory } from "./password-history.js";
+
+/**
+ * Port: Password Policy
+ * Validates passwords against configured rules:
+ * - Minimum length, uppercase, lowercase, digit, special char
+ * - History check (no reuse of last N passwords)
+ * - Expiry detection
+ */
+export interface PasswordPolicyConfig {
+  readonly minLength: number;
+  readonly requireUppercase: boolean;
+  readonly requireLowercase: boolean;
+  readonly requireDigit: boolean;
+  readonly requireSpecial: boolean;
+  readonly historyCount: number;
+  readonly maxAgeDays: number; // 0 = no expiry
+}
+
+export interface PasswordPolicyResult {
+  readonly valid: boolean;
+  readonly violations: readonly string[];
+}
+
+export interface PasswordPolicy {
+  /** Validate a password against the policy rules (no history check) */
+  validate(password: string): PasswordPolicyResult;
+  /** Check if the password was recently used (requires DB lookup) */
+  checkHistory(
+    userId: UserId,
+    password: string,
+    passwordHasher: PasswordHasher,
+    history: PasswordHistory,
+  ): Promise<Result<boolean, AppError>>;
+  /** Check if the user's password has expired */
+  isExpired(passwordChangedAt: number | null): boolean;
+  /** Get the current policy config */
+  readonly config: PasswordPolicyConfig;
+}

package/src/core/ports/refresh-token-store.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: Refresh Token Family
+ * Tracks refresh token families for rotation with reuse detection.
+ * Each family represents a single login session.
+ */
+
+export interface RefreshTokenFamily {
+  readonly id: string;
+  readonly userId: UserId;
+  readonly currentTokenHash: string;
+  readonly revoked: boolean;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+}
+
+export interface RefreshTokenStore {
+  /** Create a new token family for a login session */
+  createFamily(userId: UserId, tokenHash: string): Promise<Result<string, AppError>>;
+  /** Rotate: set a new current token hash, return old hash for comparison */
+  rotate(
+    familyId: string,
+    oldTokenHash: string,
+    newTokenHash: string,
+  ): Promise<Result<void, AppError>>;
+  /** Find family by current token hash */
+  findByTokenHash(tokenHash: string): Promise<Result<RefreshTokenFamily | null, AppError>>;
+  /** Revoke an entire family (reuse detection) */
+  revokeFamily(familyId: string): Promise<Result<void, AppError>>;
+  /** Revoke all families for a user (logout-all) */
+  revokeAllForUser(userId: UserId): Promise<Result<void, AppError>>;
+  /** Prune expired/old families */
+  prune(maxAgeMs: number): Promise<Result<number, AppError>>;
+}

package/src/core/ports/retry.ts

@@ -0,0 +1,23 @@
+/**
+ * Retry policy port — configurable retry with backoff for transient failures.
+ */
+
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default: 3) */
+  readonly maxRetries: number;
+  /** Base delay in ms for exponential backoff (default: 100) */
+  readonly baseDelayMs: number;
+  /** Maximum delay cap in ms (default: 5000) */
+  readonly maxDelayMs: number;
+  /** Jitter factor 0–1 (default: 0.2) */
+  readonly jitter: number;
+  /** Predicate: should this error be retried? (default: all errors) */
+  readonly retryable?: (error: unknown) => boolean;
+  /** Called on each retry attempt */
+  readonly onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
+}
+
+export interface RetryPolicy {
+  /** Execute a function with retry logic */
+  execute<T>(fn: () => Promise<T>): Promise<T>;
+}

package/src/core/ports/token-blacklist.ts

@@ -0,0 +1,16 @@
+import type { AppError } from "../errors/app-error.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Port: Token Blacklist
+ * Allows checking if a token has been revoked (e.g. on logout).
+ * Infrastructure can implement this with in-memory Set, SQLite, or Redis.
+ */
+export interface TokenBlacklist {
+  /** Add a token to the blacklist. expiresAt is epoch ms when the token naturally expires. */
+  add(tokenHash: string, expiresAt: number): Promise<Result<void, AppError>>;
+  /** Check whether a token hash is blacklisted */
+  isBlacklisted(tokenHash: string): Promise<Result<boolean, AppError>>;
+  /** Prune expired entries (housekeeping) */
+  prune(): Promise<Result<number, AppError>>;
+}

package/src/core/ports/token-service.ts

@@ -0,0 +1,23 @@
+import type { UserRole } from "../entities/user.entity.js";
+import type { AppError } from "../errors/app-error.js";
+import type { UserId } from "../types/brand.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Port: Token Service (JWT or similar)
+ */
+export interface TokenPayload {
+  readonly sub: UserId;
+  readonly role: UserRole;
+}
+
+export interface TokenPair {
+  readonly accessToken: string;
+  readonly refreshToken: string;
+}
+
+export interface TokenService {
+  sign(payload: TokenPayload): Promise<Result<TokenPair, AppError>>;
+  verify(token: string): Promise<Result<TokenPayload, AppError>>;
+  refresh(refreshToken: string): Promise<Result<TokenPair, AppError>>;
+}

package/src/core/ports/totp-service.ts

@@ -0,0 +1,16 @@
+import type { AppError } from "../errors/app-error.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Port: TOTP Service
+ * Time-based One-Time Password (RFC 6238) for MFA/2FA.
+ * Compatible with Google Authenticator, Authy, etc.
+ */
+export interface TotpService {
+  /** Generate a random TOTP secret (base32-encoded) */
+  generateSecret(): string;
+  /** Generate an otpauth:// URI for QR code display */
+  generateUri(secret: string, email: string, issuer: string): string;
+  /** Verify a TOTP code against a secret. Allows ±1 window for clock drift. */
+  verify(secret: string, code: string): Result<boolean, AppError>;
+}

package/src/core/ports/user.repository.ts

@@ -0,0 +1,40 @@
+import type { User, UserRole } from "../entities/user.entity.js";
+import type { AppError } from "../errors/app-error.js";
+import type { UserId } from "../types/brand.js";
+import type { CursorParams, PaginatedResult } from "../types/pagination.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Port: User Repository
+ * Defines the contract the domain expects — infrastructure implements.
+ */
+export interface UserRepository {
+  findById(id: UserId): Promise<Result<User, AppError>>;
+  findByEmail(email: string): Promise<Result<User, AppError>>;
+  create(data: CreateUserData): Promise<Result<User, AppError>>;
+  update(id: UserId, data: UpdateUserData): Promise<Result<User, AppError>>;
+  delete(id: UserId): Promise<Result<void, AppError>>;
+  list(options: UserListOptions): Promise<Result<PaginatedResult<User>, AppError>>;
+  count(): Promise<Result<number, AppError>>;
+}
+
+export interface CreateUserData {
+  readonly email: string;
+  readonly passwordHash: string;
+  readonly role: UserRole;
+}
+
+export interface UpdateUserData {
+  readonly email?: string | undefined;
+  readonly passwordHash?: string | undefined;
+  readonly role?: UserRole | undefined;
+  readonly emailVerified?: boolean | undefined;
+  readonly mfaEnabled?: boolean | undefined;
+  readonly mfaSecret?: string | null | undefined;
+  readonly passwordChangedAt?: number | undefined;
+}
+
+export interface UserListOptions extends CursorParams {
+  readonly search?: string | undefined;
+  readonly role?: UserRole | undefined;
+}

package/src/core/ports/verification-token.ts

@@ -0,0 +1,41 @@
+import type { AppError } from "../errors/app-error.js";
+import type { UserId } from "../types/brand.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Port: Verification Token Repository
+ * Handles time-limited tokens for email verification and password reset.
+ */
+
+export const VerificationTokenType = {
+  EMAIL_VERIFICATION: "email_verification",
+  PASSWORD_RESET: "password_reset",
+} as const;
+
+export type VerificationTokenType =
+  (typeof VerificationTokenType)[keyof typeof VerificationTokenType];
+
+export interface VerificationToken {
+  readonly id: string;
+  readonly userId: UserId;
+  readonly type: VerificationTokenType;
+  readonly tokenHash: string;
+  readonly expiresAt: number;
+  readonly usedAt: number | null;
+  readonly createdAt: number;
+}
+
+export interface VerificationTokenRepository {
+  /** Create a new verification token. Returns the raw (unhashed) token. */
+  create(
+    userId: UserId,
+    type: VerificationTokenType,
+    ttlMs: number,
+  ): Promise<Result<string, AppError>>;
+  /** Verify and consume a token. Marks it as used. Returns the userId. */
+  verify(rawToken: string, type: VerificationTokenType): Promise<Result<UserId, AppError>>;
+  /** Invalidate all tokens for a user of a given type */
+  invalidateAll(userId: UserId, type: VerificationTokenType): Promise<Result<void, AppError>>;
+  /** Prune expired tokens */
+  prune(): Promise<Result<number, AppError>>;
+}

package/src/core/ports/webhook.ts

@@ -0,0 +1,58 @@
+/**
+ * Webhook registry port — manages outbound HTTP webhook subscriptions
+ * that fire on domain events.
+ */
+
+import type { AppError } from "../errors/app-error.js";
+import type { Result } from "../types/result.js";
+import type { DomainEventType } from "./event-bus.js";
+
+export interface WebhookSubscription {
+  readonly id: string;
+  readonly url: string;
+  /** Event types this webhook listens for. Empty = all events. */
+  readonly events: ReadonlyArray<DomainEventType>;
+  /** Shared secret for HMAC-SHA256 signature verification */
+  readonly secret: string;
+  /** Whether this subscription is active */
+  readonly active: boolean;
+  /** ISO 8601 creation timestamp */
+  readonly createdAt: string;
+}
+
+export interface CreateWebhookData {
+  readonly url: string;
+  readonly events: ReadonlyArray<DomainEventType>;
+  readonly secret: string;
+}
+
+export interface WebhookDelivery {
+  readonly id: string;
+  readonly webhookId: string;
+  readonly eventId: string;
+  readonly url: string;
+  readonly status: number;
+  readonly success: boolean;
+  readonly attemptNumber: number;
+  readonly deliveredAt: string;
+}
+
+export interface WebhookRegistry {
+  /** Create a new webhook subscription */
+  create(data: CreateWebhookData): Result<WebhookSubscription, AppError>;
+
+  /** List all active webhook subscriptions */
+  list(): Result<ReadonlyArray<WebhookSubscription>, AppError>;
+
+  /** Find subscriptions matching a specific event type */
+  findByEvent(eventType: DomainEventType): Result<ReadonlyArray<WebhookSubscription>, AppError>;
+
+  /** Remove a webhook subscription by ID */
+  remove(id: string): Result<void, AppError>;
+
+  /** Toggle a webhook subscription on/off */
+  setActive(id: string, active: boolean): Result<void, AppError>;
+
+  /** Record a delivery attempt */
+  recordDelivery(delivery: WebhookDelivery): Result<void, AppError>;
+}

package/src/core/types/brand.ts

@@ -0,0 +1,19 @@
+/**
+ * Branded / Opaque type utility.
+ * Prevents accidental interchange of structurally identical primitives.
+ *
+ * @example
+ * type UserId = Brand<string, "UserId">;
+ * const id: UserId = "abc" as UserId;
+ */
+declare const __brand: unique symbol;
+
+export type Brand<T, B extends string> = T & { readonly [__brand]: B };
+
+/** Common branded identifiers */
+export type UserId = Brand<string, "UserId">;
+export type RequestId = Brand<string, "RequestId">;
+export type Timestamp = Brand<number, "Timestamp">;
+
+/** Helper to create branded values (runtime no-op, compile-time safety) */
+export const brand = <T, B extends string>(value: T): Brand<T, B> => value as Brand<T, B>;

package/src/core/types/index.ts

@@ -0,0 +1,19 @@
+export { type Brand, type UserId, type RequestId, type Timestamp, brand } from "./brand.js";
+export {
+  type Result,
+  type Ok,
+  type Err,
+  ok,
+  err,
+  map,
+  flatMap,
+  unwrapOr,
+  tryCatch,
+  tryCatchAsync,
+} from "./result.js";
+export {
+  type CursorParams,
+  type PaginatedResult,
+  encodeCursor,
+  decodeCursor,
+} from "./pagination.js";

package/src/core/types/pagination.ts

@@ -0,0 +1,28 @@
+/**
+ * Cursor-based pagination types.
+ * Cursor is an opaque base64-encoded string containing the sort key.
+ */
+
+export interface CursorParams {
+  readonly cursor?: string | undefined;
+  readonly limit: number;
+}
+
+export interface PaginatedResult<T> {
+  readonly items: readonly T[];
+  readonly nextCursor: string | null;
+  readonly hasMore: boolean;
+  readonly total?: number | undefined;
+}
+
+/** Encode a cursor value (ISO timestamp or ID) to a URL-safe opaque string */
+export const encodeCursor = (value: string): string => btoa(value);
+
+/** Decode an opaque cursor back to the original value */
+export const decodeCursor = (cursor: string): string | null => {
+  try {
+    return atob(cursor);
+  } catch {
+    return null;
+  }
+};