@strav/kernel 0.1.0

package/src/core/application.ts

@@ -0,0 +1,241 @@
+import Container from './container.ts'
+import type ServiceProvider from './service_provider.ts'
+import Emitter from '../events/emitter.ts'
+
+const SHUTDOWN_TIMEOUT = 30_000
+
+/**
+ * Application container with service-provider lifecycle management.
+ *
+ * Extends {@link Container} so all existing DI methods (`singleton`, `resolve`,
+ * `register`, `make`, `has`) continue to work unchanged. Adds provider
+ * orchestration: topological dependency sort, ordered boot, and reverse-order
+ * graceful shutdown on SIGINT / SIGTERM.
+ *
+ * @example
+ * import { app } from '@stravigor/kernel/core'
+ * import { ConfigProvider, DatabaseProvider, AuthProvider } from '@stravigor/kernel/providers'
+ *
+ * app
+ *   .useProviders([
+ *     new ConfigProvider(),
+ *     new DatabaseProvider(),
+ *     new AuthProvider({ resolver: (id) => User.find(id) })
+ *   ])
+ *   .onBooted(async () => {
+ *     console.log('Application is ready!')
+ *   })
+ *
+ * await app.start()
+ */
+export default class Application extends Container {
+  private _providers: ServiceProvider[] = []
+  private _bootedProviders: ServiceProvider[] = []
+  private _booted = false
+  private _shuttingDown = false
+  private _signalHandlers: (() => void)[] = []
+
+  /** Add a service provider. Must be called before {@link start}. */
+  use(provider: ServiceProvider): this {
+    if (this._booted) {
+      throw new Error(`Cannot add provider "${provider.name}" after the application has started.`)
+    }
+    this._providers.push(provider)
+    return this
+  }
+
+  /** Add multiple service providers at once. Must be called before {@link start}. */
+  useProviders(providers: ServiceProvider[]): this {
+    if (this._booted) {
+      throw new Error('Cannot add providers after the application has started.')
+    }
+    this._providers.push(...providers)
+    return this
+  }
+
+  /** Register a callback to run after the application has booted. */
+  onBooted(callback: () => void | Promise<void>): this {
+    Emitter.once('app:booted', callback)
+    return this
+  }
+
+  /**
+   * Boot the application.
+   *
+   * 1. Emit `app:starting`
+   * 2. Topologically sort providers by their declared dependencies
+   * 3. Call `register()` on every provider (synchronous, binds factories)
+   * 4. Call `boot()` on every provider in dependency order (async init)
+   * 5. Install SIGINT / SIGTERM handlers for graceful shutdown
+   * 6. Emit `app:booted`
+   */
+  async start(): Promise<void> {
+    if (this._booted) return
+
+    await Emitter.emit('app:starting')
+
+    // Sort providers so dependencies are booted first
+    const sorted = this.topologicalSort(this._providers)
+
+    // Phase 1: register all (synchronous)
+    for (const provider of sorted) {
+      provider.register(this)
+    }
+
+    // Phase 2: boot in order (async)
+    for (const provider of sorted) {
+      try {
+        await provider.boot(this)
+        this._bootedProviders.push(provider)
+      } catch (error) {
+        // Rollback: shutdown already-booted providers in reverse
+        await this.shutdownProviders()
+        throw error
+      }
+    }
+
+    this._booted = true
+    this.installSignalHandlers()
+
+    await Emitter.emit('app:booted')
+  }
+
+  /**
+   * Gracefully shut down the application.
+   *
+   * Calls `shutdown()` on every booted provider in reverse boot order,
+   * then exits the process. A 30-second timeout forces exit if providers
+   * don't finish in time.
+   */
+  async shutdown(): Promise<void> {
+    if (this._shuttingDown) return
+    this._shuttingDown = true
+
+    await Emitter.emit('app:shutdown')
+
+    const timer = setTimeout(() => {
+      console.error('Shutdown timed out, forcing exit.')
+      process.exit(1)
+    }, SHUTDOWN_TIMEOUT)
+
+    try {
+      await this.shutdownProviders()
+    } finally {
+      clearTimeout(timer)
+      this.removeSignalHandlers()
+      this._booted = false
+      this._shuttingDown = false
+    }
+
+    await Emitter.emit('app:terminated')
+  }
+
+  /** Whether the application has finished booting. */
+  get isBooted(): boolean {
+    return this._booted
+  }
+
+  /** Whether the application is currently shutting down. */
+  get isShuttingDown(): boolean {
+    return this._shuttingDown
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  /** Shutdown booted providers in reverse order. */
+  private async shutdownProviders(): Promise<void> {
+    const reversed = [...this._bootedProviders].reverse()
+    for (const provider of reversed) {
+      try {
+        await provider.shutdown(this)
+      } catch (error) {
+        console.error(`Error shutting down provider "${provider.name}":`, error)
+      }
+    }
+    this._bootedProviders = []
+  }
+
+  /** Install SIGINT/SIGTERM handlers for graceful shutdown. */
+  private installSignalHandlers(): void {
+    const handler = () => {
+      this.shutdown().then(() => process.exit(0))
+    }
+    this._signalHandlers.push(handler)
+    process.on('SIGINT', handler)
+    process.on('SIGTERM', handler)
+  }
+
+  /** Remove signal handlers. */
+  private removeSignalHandlers(): void {
+    for (const handler of this._signalHandlers) {
+      process.off('SIGINT', handler)
+      process.off('SIGTERM', handler)
+    }
+    this._signalHandlers = []
+  }
+
+  /**
+   * Topologically sort providers using Kahn's algorithm.
+   *
+   * Throws if a provider declares a dependency on an unknown provider name,
+   * or if a circular dependency is detected.
+   */
+  private topologicalSort(providers: ServiceProvider[]): ServiceProvider[] {
+    const byName = new Map<string, ServiceProvider>()
+    for (const p of providers) {
+      if (byName.has(p.name)) {
+        throw new Error(`Duplicate provider name: "${p.name}"`)
+      }
+      byName.set(p.name, p)
+    }
+
+    // Build adjacency list and in-degree map
+    const inDegree = new Map<string, number>()
+    const dependents = new Map<string, string[]>() // dep → providers that depend on it
+
+    for (const p of providers) {
+      inDegree.set(p.name, 0)
+      dependents.set(p.name, [])
+    }
+
+    for (const p of providers) {
+      for (const dep of p.dependencies) {
+        if (!byName.has(dep)) {
+          throw new Error(`Provider "${p.name}" depends on "${dep}", which is not registered.`)
+        }
+        inDegree.set(p.name, (inDegree.get(p.name) ?? 0) + 1)
+        dependents.get(dep)!.push(p.name)
+      }
+    }
+
+    // Kahn's algorithm
+    const queue: string[] = []
+    for (const [name, degree] of inDegree) {
+      if (degree === 0) queue.push(name)
+    }
+
+    const sorted: ServiceProvider[] = []
+    while (queue.length > 0) {
+      const name = queue.shift()!
+      sorted.push(byName.get(name)!)
+
+      for (const dependent of dependents.get(name)!) {
+        const newDegree = inDegree.get(dependent)! - 1
+        inDegree.set(dependent, newDegree)
+        if (newDegree === 0) queue.push(dependent)
+      }
+    }
+
+    if (sorted.length !== providers.length) {
+      const remaining = providers.filter(p => !sorted.includes(p)).map(p => p.name)
+      throw new Error(`Circular dependency detected among providers: ${remaining.join(', ')}`)
+    }
+
+    return sorted
+  }
+}
+
+/** Global application container singleton. */
+export const app = new Application()

package/src/core/container.ts

@@ -0,0 +1,113 @@
+import 'reflect-metadata'
+import { INJECTABLE } from './inject.ts'
+
+/** Constructor type for injectable classes. */
+type Constructor<T = any> = new (...args: any[]) => T
+
+/** A factory function that receives the container and returns a service instance. */
+type Factory<T = any> = (container: Container) => T
+
+/**
+ * A lightweight dependency injection container.
+ *
+ * Services are registered as factory functions or `@inject`-decorated classes
+ * and resolved by string name or class constructor.
+ *
+ * @example
+ * const app = new Container()
+ *   .singleton(Database)
+ *   .singleton(UserService)              // @inject decorated
+ *   .singleton('logger', () => new Logger())
+ *
+ * const svc = app.resolve(UserService)   // Database auto-injected
+ */
+export default class Container {
+  private factories = new Map<any, { factory: Factory; singleton: boolean }>()
+  private instances = new Map<any, any>()
+
+  /** Create a factory from a class constructor, resolving `design:paramtypes` metadata. */
+  private classToFactory<T>(Cls: Constructor<T>): Factory<T> {
+    const paramTypes: Constructor[] = Reflect.getMetadata('design:paramtypes', Cls) ?? []
+    return (c: Container) => new Cls(...paramTypes.map(dep => c.resolve(dep)))
+  }
+
+  /** Wrap an `@inject`-decorated class in a factory, or return a plain factory as-is. */
+  private toFactory<T>(factoryOrClass: Factory<T> | Constructor<T>): Factory<T> {
+    if (INJECTABLE in factoryOrClass) {
+      return this.classToFactory(factoryOrClass as Constructor<T>)
+    }
+    return factoryOrClass as Factory<T>
+  }
+
+  /** Register an `@inject` class that creates a new instance on every {@link resolve} call. */
+  register<T>(ctor: Constructor<T>): this
+  /** Register a factory under a class constructor key. Creates a new instance on every {@link resolve} call. */
+  register<T>(ctor: Constructor<T>, factory: Factory<T>): this
+  /** Register a factory or `@inject` class under a string name. Creates a new instance on every {@link resolve} call. */
+  register<T>(name: string, factory: Factory<T> | Constructor<T>): this
+  register<T>(nameOrCtor: string | Constructor<T>, factory?: Factory<T> | Constructor<T>): this {
+    if (typeof nameOrCtor === 'function') {
+      const resolved = factory ? this.toFactory(factory) : this.classToFactory(nameOrCtor)
+      this.factories.set(nameOrCtor, { factory: resolved, singleton: false })
+    } else {
+      this.factories.set(nameOrCtor, { factory: this.toFactory(factory!), singleton: false })
+    }
+    return this
+  }
+
+  /** Register an `@inject` class as a singleton by its constructor. */
+  singleton<T>(ctor: Constructor<T>): this
+  /** Register a factory under a class constructor key (resolved by constructor). */
+  singleton<T>(ctor: Constructor<T>, factory: Factory<T>): this
+  /** Register a factory or `@inject` class as a singleton under a string name. */
+  singleton<T>(name: string, factory: Factory<T> | Constructor<T>): this
+  singleton<T>(nameOrCtor: string | Constructor<T>, factory?: Factory<T> | Constructor<T>): this {
+    if (typeof nameOrCtor === 'function') {
+      const resolved = factory ? this.toFactory(factory) : this.classToFactory(nameOrCtor)
+      this.factories.set(nameOrCtor, { factory: resolved, singleton: true })
+    } else {
+      this.factories.set(nameOrCtor, { factory: this.toFactory(factory!), singleton: true })
+    }
+    return this
+  }
+
+  /** Resolve a service by its class constructor. */
+  resolve<T>(ctor: Constructor<T>): T
+  /** Resolve a service by its string name. */
+  resolve<T>(name: string): T
+  resolve<T>(key: string | Constructor<T>): T {
+    const entry = this.factories.get(key)
+    if (!entry) {
+      const label = typeof key === 'string' ? `"${key}"` : key.name
+      throw new Error(`Service ${label} is not registered`)
+    }
+
+    if (entry.singleton) {
+      if (!this.instances.has(key)) {
+        this.instances.set(key, entry.factory(this))
+      }
+      return this.instances.get(key)
+    }
+
+    return entry.factory(this)
+  }
+
+  /** Check whether a service has been registered under the given name or constructor. */
+  has(key: string | Constructor): boolean {
+    return this.factories.has(key)
+  }
+
+  /**
+   * Instantiate a class with automatic dependency injection.
+   *
+   * Unlike {@link resolve}, this does not require prior registration.
+   * Constructor dependencies are resolved recursively: registered services
+   * are pulled from the container, unregistered `@inject` classes are
+   * instantiated via `make()` as well.
+   */
+  make<T>(ctor: Constructor<T>): T {
+    const paramTypes: Constructor[] = Reflect.getMetadata('design:paramtypes', ctor) ?? []
+    const deps = paramTypes.map(dep => (this.has(dep) ? this.resolve(dep) : this.make(dep)))
+    return new ctor(...deps)
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export { default as Application, app } from './application.ts'
+export { default as Container } from './container.ts'
+export { default as ServiceProvider } from './service_provider.ts'
+export { inject, INJECTABLE } from './inject.ts'

package/src/core/inject.ts

@@ -0,0 +1,39 @@
+import 'reflect-metadata'
+
+/** Symbol used to mark a class as injectable. */
+export const INJECTABLE = Symbol('inject:injectable')
+
+/**
+ * Class decorator that marks a class as injectable.
+ *
+ * With `emitDecoratorMetadata` enabled, TypeScript automatically emits
+ * constructor parameter type metadata (`design:paramtypes`). The container
+ * reads this metadata to auto-resolve dependencies by class reference.
+ *
+ * Works as both `@inject` and `@inject()`.
+ *
+ * @example
+ * @inject
+ * class UserService {
+ *   constructor(protected db: Database, protected logger: Logger) {}
+ * }
+ *
+ * container.singleton(Database)
+ * container.singleton(Logger)
+ * container.singleton(UserService)
+ * container.resolve(UserService) // db and logger auto-injected by type
+ */
+export function inject<T extends Function>(target: T): void
+export function inject(): <T extends Function>(target: T) => void
+export function inject(target?: any) {
+  const mark = (cls: any) => {
+    Object.defineProperty(cls, INJECTABLE, { value: true, enumerable: false })
+  }
+  if (typeof target === 'function') {
+    mark(target)
+    return
+  }
+  return (cls: any) => {
+    mark(cls)
+  }
+}

package/src/core/service_provider.ts

@@ -0,0 +1,44 @@
+import type Application from './application.ts'
+
+/**
+ * Base class for service providers.
+ *
+ * A service provider encapsulates the full lifecycle of a framework service:
+ * registration (binding into the container), booting (async initialization),
+ * and shutdown (cleanup). The {@link Application} orchestrates providers
+ * in dependency order via topological sort.
+ *
+ * @example
+ * class AuthProvider extends ServiceProvider {
+ *   readonly name = 'auth'
+ *   readonly dependencies = ['database']
+ *
+ *   register(app: Application): void {
+ *     app.singleton(Auth)
+ *   }
+ *
+ *   async boot(app: Application): Promise<void> {
+ *     app.resolve(Auth)
+ *     Auth.useResolver((id) => User.find(id))
+ *     await Auth.ensureTables()
+ *   }
+ *
+ *   async shutdown(app: Application): Promise<void> {}
+ * }
+ */
+export default abstract class ServiceProvider {
+  /** Unique name used for dependency resolution between providers. */
+  abstract readonly name: string
+
+  /** Names of other providers that must be registered and booted first. */
+  readonly dependencies: string[] = []
+
+  /** Bind services into the container. Synchronous. Called before boot(). */
+  register(app: Application): void {}
+
+  /** Initialize services after ALL providers are registered. Can be async. */
+  boot(app: Application): void | Promise<void> {}
+
+  /** Clean up resources during shutdown. Called in reverse boot order. */
+  shutdown(app: Application): void | Promise<void> {}
+}

package/src/encryption/encryption_manager.ts

@@ -0,0 +1,215 @@
+import {
+  hkdfSync,
+  createCipheriv,
+  createDecipheriv,
+  createHmac,
+  timingSafeEqual,
+} from 'node:crypto'
+import { inject } from '../core/inject.ts'
+import Configuration from '../config/configuration.ts'
+import type { EncryptionConfig } from './types.ts'
+import { ConfigurationError, EncryptionError } from '../exceptions/errors.ts'
+
+const IV_LENGTH = 12
+const TAG_LENGTH = 16
+const KEY_LENGTH = 32
+const ALGORITHM = 'aes-256-gcm'
+const HKDF_SALT = 'strav-encryption-salt'
+
+function deriveKey(raw: string, info: string): Buffer {
+  return Buffer.from(hkdfSync('sha256', raw, HKDF_SALT, info, KEY_LENGTH))
+}
+
+function encryptWithKey(plaintext: string, key: Buffer): string {
+  const iv = Buffer.from(crypto.getRandomValues(new Uint8Array(IV_LENGTH)))
+  const cipher = createCipheriv(ALGORITHM, key, iv)
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+  // iv (12) + ciphertext (variable) + tag (16)
+  const payload = Buffer.concat([iv, encrypted, tag])
+  return payload.toString('base64url')
+}
+
+function decryptWithKey(payload: string, key: Buffer): string {
+  const buf = Buffer.from(payload, 'base64url')
+  if (buf.length < IV_LENGTH + TAG_LENGTH) {
+    throw new EncryptionError('Invalid encrypted payload: too short.')
+  }
+  const iv = buf.subarray(0, IV_LENGTH)
+  const tag = buf.subarray(buf.length - TAG_LENGTH)
+  const ciphertext = buf.subarray(IV_LENGTH, buf.length - TAG_LENGTH)
+  const decipher = createDecipheriv(ALGORITHM, key, iv)
+  decipher.setAuthTag(tag)
+  return decipher.update(ciphertext) + decipher.final('utf8')
+}
+
+/**
+ * Central encryption configuration hub.
+ *
+ * Resolved once via the DI container — reads the encryption config
+ * and derives cryptographic keys from the application key.
+ *
+ * @example
+ * app.singleton(EncryptionManager)
+ * app.resolve(EncryptionManager)
+ *
+ * // Swap keys at runtime (e.g., for testing)
+ * EncryptionManager.useKey('test-key-here')
+ */
+@inject
+export default class EncryptionManager {
+  private static _config: EncryptionConfig
+  private static _encryptionKey: Buffer
+  private static _hmacKey: Buffer
+  private static _previousEncryptionKeys: Buffer[]
+  private static _previousHmacKeys: Buffer[]
+
+  constructor(config: Configuration) {
+    EncryptionManager._config = {
+      key: '',
+      previousKeys: [],
+      ...(config.get('encryption', {}) as object),
+    }
+
+    const raw = EncryptionManager._config.key
+    if (!raw) {
+      throw new ConfigurationError(
+        'Encryption key is not set. Set APP_KEY in your .env file or configure encryption.key.'
+      )
+    }
+
+    EncryptionManager._encryptionKey = deriveKey(raw, 'aes-256-gcm')
+    EncryptionManager._hmacKey = deriveKey(raw, 'hmac-sha256')
+
+    EncryptionManager._previousEncryptionKeys = EncryptionManager._config.previousKeys.map(k =>
+      deriveKey(k, 'aes-256-gcm')
+    )
+    EncryptionManager._previousHmacKeys = EncryptionManager._config.previousKeys.map(k =>
+      deriveKey(k, 'hmac-sha256')
+    )
+  }
+
+  static get config(): EncryptionConfig {
+    return EncryptionManager._config
+  }
+
+  /** Swap the application key at runtime (e.g., for testing). */
+  static useKey(key: string): void {
+    EncryptionManager._encryptionKey = deriveKey(key, 'aes-256-gcm')
+    EncryptionManager._hmacKey = deriveKey(key, 'hmac-sha256')
+  }
+
+  // ---------------------------------------------------------------------------
+  // Symmetric Encryption (AES-256-GCM)
+  // ---------------------------------------------------------------------------
+
+  /** Encrypt a plaintext string. Returns a base64url-encoded payload. */
+  static encrypt(plaintext: string): string {
+    return encryptWithKey(plaintext, EncryptionManager._encryptionKey)
+  }
+
+  /**
+   * Decrypt a payload. Tries the current key first, then previous keys for rotation.
+   * Throws if none of the keys can decrypt the payload.
+   */
+  static decrypt(payload: string): string {
+    try {
+      return decryptWithKey(payload, EncryptionManager._encryptionKey)
+    } catch {
+      // Try previous keys for rotation
+      for (const key of EncryptionManager._previousEncryptionKeys) {
+        try {
+          return decryptWithKey(payload, key)
+        } catch {
+          continue
+        }
+      }
+      throw new EncryptionError('Decryption failed: invalid payload or key.')
+    }
+  }
+
+  /** Encrypt and JSON-serialize an object. */
+  static seal(data: unknown): string {
+    return EncryptionManager.encrypt(JSON.stringify(data))
+  }
+
+  /** Decrypt and JSON-deserialize an object. */
+  static unseal<T = unknown>(payload: string): T {
+    return JSON.parse(EncryptionManager.decrypt(payload)) as T
+  }
+
+  // ---------------------------------------------------------------------------
+  // HMAC Signing
+  // ---------------------------------------------------------------------------
+
+  /** Create an HMAC-SHA256 signature. Returns a hex string. */
+  static sign(data: string): string {
+    return createHmac('sha256', EncryptionManager._hmacKey).update(data).digest('hex')
+  }
+
+  /**
+   * Verify an HMAC-SHA256 signature using timing-safe comparison.
+   * Tries the current key first, then previous keys for rotation.
+   */
+  static verifySignature(data: string, signature: string): boolean {
+    const expected = Buffer.from(EncryptionManager.sign(data), 'hex')
+    const actual = Buffer.from(signature, 'hex')
+    if (expected.length !== actual.length) {
+      // Try previous keys
+      for (const key of EncryptionManager._previousHmacKeys) {
+        const prev = Buffer.from(createHmac('sha256', key).update(data).digest('hex'), 'hex')
+        if (prev.length === actual.length && timingSafeEqual(prev, actual)) return true
+      }
+      return false
+    }
+    if (timingSafeEqual(expected, actual)) return true
+    // Try previous keys
+    for (const key of EncryptionManager._previousHmacKeys) {
+      const prev = Buffer.from(createHmac('sha256', key).update(data).digest('hex'), 'hex')
+      if (prev.length === actual.length && timingSafeEqual(prev, actual)) return true
+    }
+    return false
+  }
+
+  // ---------------------------------------------------------------------------
+  // Password Hashing (Bun.password — argon2id)
+  // ---------------------------------------------------------------------------
+
+  /** Hash a password using argon2id. Returns an encoded hash string. */
+  static hash(password: string): Promise<string> {
+    return Bun.password.hash(password, 'argon2id')
+  }
+
+  /** Verify a password against a hash. Works with argon2id and bcrypt hashes. */
+  static verify(password: string, hash: string): Promise<boolean> {
+    return Bun.password.verify(password, hash)
+  }
+
+  // ---------------------------------------------------------------------------
+  // One-way Hashing
+  // ---------------------------------------------------------------------------
+
+  /** SHA-256 hash. Returns a hex string. */
+  static sha256(data: string): string {
+    return new Bun.CryptoHasher('sha256').update(data).digest('hex')
+  }
+
+  /** SHA-512 hash. Returns a hex string. */
+  static sha512(data: string): string {
+    return new Bun.CryptoHasher('sha512').update(data).digest('hex')
+  }
+
+  // ---------------------------------------------------------------------------
+  // Random Generation
+  // ---------------------------------------------------------------------------
+
+  /** Generate a random hex string (2 hex chars per byte). */
+  static random(bytes: number = 32): string {
+    return Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString('hex')
+  }
+
+  /** Generate raw random bytes. */
+  static randomBytes(bytes: number = 32): Uint8Array {
+    return crypto.getRandomValues(new Uint8Array(bytes))
+  }
+}