@kelpie/server 0.5.1 → 0.6.0

package/src/index.ts

@@ -7,6 +7,21 @@ export type { WebBundleOptions } from './webBundle.ts'
 export { ConfigurationError, loadConfig } from './lib/config.ts'
 export type { Environment, KelpieConfig, LogLevel, RuntimeMode } from './lib/config.ts'
 
+export { fromEnv, isFromEnvMarker, resolveMarker, resolveMarkers } from './lib/fromEnv.ts'
+export type { ConfigValue, FromEnvMarker, FromEnvProblem, ResolveResult } from './lib/fromEnv.ts'
+
+export { defineKelpieConfig, resolveKelpieConfig } from './lib/kelpieConfigFile.ts'
+export type {
+  EmailInput,
+  KelpieConfigInput,
+  RateLimitBudgetInput,
+  RateLimitInput,
+  SecretEncryptionInput,
+} from './lib/kelpieConfigFile.ts'
+
+export { appUrlConfigSchema } from './lib/appUrl.ts'
+export type { AppUrlConfig } from './lib/appUrl.ts'
+
 export { resolveClientIpFrom } from './lib/clientIp.ts'
 
 export { ModuleConfigFileError, readModuleConfigFile } from './lib/moduleConfig.ts'
@@ -23,9 +38,12 @@ export type { Database, DatabaseConnection, DatabaseProbe } from './lib/database
 
 export * as schema from './schema/index.ts'
 
-export { createEmailSender, createLogEmailSender, emailConfigSchema } from './lib/email.ts'
+export { createLogEmailSender, emailConfigSchema } from './lib/email.ts'
 export type { EmailConfig, EmailMessage, EmailSender } from './lib/email.ts'
 
+export { SMTP_EMAIL_PROVIDER, createSmtpEmailModule, createSmtpEmailSender } from './modules/smtp-email/index.ts'
+export type { SmtpEmailConfig, SmtpEmailModuleOptions, SmtpTransport } from './modules/smtp-email/index.ts'
+
 export { MINIMUM_PASSWORD_LENGTH, hashPassword, isPasswordStrongEnough, verifyPassword } from './lib/passwords.ts'
 export { generateToken, hashToken, tokenHashesMatch } from './lib/tokens.ts'
 
@@ -49,8 +67,13 @@ export type { ErrorBody, ErrorCode, ErrorDetail, ErrorStatus, ValidationIssue }
 export { createIdFactory, idPrefixes } from './lib/ids.ts'
 export type { IdFactory, ObjectKind } from './lib/ids.ts'
 
-export { createLogger } from './lib/logger.ts'
-export type { LogFields, Logger, LogSink } from './lib/logger.ts'
+export {
+  createCaptureTransport,
+  createLogger,
+  createStdoutTransport,
+  createTransportForDestination,
+} from './lib/logger.ts'
+export type { CreateLoggerOptions, LogFields, Logger, LoggingDestination } from './lib/logger.ts'
 
 export type {
   KelpieModule,
@@ -76,21 +99,33 @@ export type {
 
 export { SEATS_LIMIT } from './modules/workspace/capabilities.ts'
 
-export { DOMAIN_EVENT_NAMES, RECORD_OBJECT_TYPES, createEventBus } from './runtime/events.ts'
+export {
+  RECORD_OBJECT_TYPES,
+  checkEventCycle,
+  createEventBus,
+  currentEventChain,
+} from './runtime/events.ts'
 export type {
-  DomainEventName,
-  DomainEvents,
+  AnyEventHandler,
+  CycleGuardOutcome,
   EventBus,
+  EventBusOptions,
+  EventCatalog,
+  EventChainEntry,
   EventHandler,
+  EventName,
+  KelpieEventMap,
   RecordObjectType,
-  StagedObjectType,
+  SubscribeOptions,
 } from './runtime/events.ts'
+export type { ModuleEventCatalog } from './runtime/module.ts'
 
 export { createTransactionScope } from './runtime/transaction.ts'
 export type {
   BufferedEvents,
   Transaction,
   TransactionContext,
+  TransactionOptions,
   TransactionScope,
   TransactionScopeDependencies,
 } from './runtime/transaction.ts'
@@ -100,8 +135,8 @@ export type { MigrationPlanStep } from './runtime/migrate.ts'
 
 export { coreMigrationsDirectory, coreModules } from './modules/core.ts'
 
-export { resealStoredSecrets } from './modules/reseal.ts'
-export type { ResealColumnOutcome, ResealOutcome } from './modules/reseal.ts'
+export { resealStoredSecrets, runReseal } from './modules/reseal.ts'
+export type { ResealColumnOutcome, ResealOutcome, ResealPass, RunResealOptions } from './modules/reseal.ts'
 
 export { KEY_KINDS, kindOfSecret, mintKey, parseKeyKind, readBearerToken } from './modules/api-keys/keys.ts'
 export type { KeyKind, MintedKey } from './modules/api-keys/keys.ts'

package/src/lib/actor.ts

@@ -1,4 +1,4 @@
-import type { MemberRole } from '@kelpie/schemas'
+import type { EventActor, MemberRole } from '@kelpie/schemas'
 
 import { AppError } from './errors.ts'
 
@@ -97,3 +97,17 @@ export function actorUserId(actor: Actor): string | null {
 export function actorMemberId(actor: Actor): string | null {
   return actor.memberId
 }
+
+/**
+ * Maps the request actor to the actor stamped on domain events.
+ *
+ * A signed-in user becomes `user`. A workspace key (no user behind it) becomes
+ * `system`, because the event was caused by the workspace itself rather than
+ * any one person.
+ */
+export function toEventActor(actor: Actor): EventActor {
+  if (actor.userId !== null) {
+    return { kind: 'user', id: actor.userId }
+  }
+  return { kind: 'system' }
+}

package/src/lib/config.ts

@@ -3,8 +3,14 @@ import { z } from 'zod'
 import { emailConfigSchema } from './email.ts'
 import type { EmailConfig } from './email.ts'
 import { describeValidationIssue } from './errors.ts'
+// `EmailConfig` is `{ EMAIL_PROVIDER, EMAIL_FROM }`. `EMAIL_PROVIDER` names one
+// of the registered senders; `'log'` is always available, other names come
+// from provider modules. Provider-specific config (SMTP settings, an API key)
+// belongs to the module that reads it through `context.config(...)`.
+import type { LoggingDestination } from './logger.ts'
 import { rateLimitConfigFrom, rateLimitConfigSchema } from './rateLimit.ts'
 import type { RateLimitConfig } from './rateLimit.ts'
+import type { SecretEncryptionConfig } from './secrets.ts'
 
 /**
  * The single place the service reads environment variables. Every other module
@@ -18,12 +24,29 @@ export type RuntimeMode = 'development' | 'test' | 'production'
 
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
 
+/**
+ * Everything the logger needs to boot: the minimum severity to emit, and the
+ * ordered list of destinations each line is written to. Stdout is one such
+ * destination; adding a file or a hosted collector means adding an entry to
+ * `destinations` and extending `LoggingDestination` in `lib/logger.ts`.
+ */
+export interface LoggingConfig {
+  readonly level: LogLevel
+  readonly destinations: readonly LoggingDestination[]
+}
+
 export interface KelpieConfig {
   readonly runtimeMode: RuntimeMode
   readonly port: number
   readonly databaseUrl: string
-  readonly logLevel: LogLevel
-  /** Transactional mail only. Roadmap decision 4: configured, never hardcoded. */
+  readonly logging: LoggingConfig
+  /**
+   * The provider name the module runtime looks up in its registry, and the
+   * from address every outgoing message uses. See `lib/email.ts` for the
+   * shape and rules; `'log'` is always available, `'smtp'` is registered by
+   * the built-in `smtp-email` core module, and other names come from
+   * third-party provider modules.
+   */
   readonly email: EmailConfig
   /**
    * Path to the deploy-time module override file (`lib/moduleConfig.ts`).
@@ -44,6 +67,28 @@ export interface KelpieConfig {
    * client IP is read from `X-Forwarded-For` (`lib/clientIp.ts`).
    */
   readonly trustedProxyHopCount: number
+  /**
+   * What modules see through `context.config(schema)`. `resolveKelpieConfig`
+   * produces this by merging any `env` section in `kelpie.config.ts` over
+   * `process.env`, so a key in the config file wins for that key and unset
+   * keys pass through. `loadConfig` sets it to the environment it was given,
+   * so an old caller keeps the same behaviour.
+   */
+  readonly env: Environment
+  /**
+   * The deployment's base URL, source of every emailed link. Optional so an
+   * older assembly that omits it from `kelpie.config.ts` still boots: modules
+   * that need it fall back to `context.config(appUrlConfigSchema)` when unset.
+   * A new assembly declares it as a first-class field.
+   */
+  readonly appBaseUrl: string | undefined
+  /**
+   * The key(s) that seal stored secrets. Optional for the same reason
+   * `appBaseUrl` is: modules that need it fall back to
+   * `context.config(secretEncryptionConfigSchema)`. The base assembly declares
+   * it, so both webhooks and agent-tasks receive it through `services`.
+   */
+  readonly secretEncryption: SecretEncryptionConfig | undefined
 }
 
 /** Thrown at boot when the environment cannot produce a valid configuration. */
@@ -82,10 +127,8 @@ const environmentSchema = z.object({
 /**
  * Parses an environment into a validated config.
  *
- * `emailConfigSchema` is a discriminated union, so it is parsed separately
- * from the rest: a union has no flat `.shape` to spread into `environmentSchema`,
- * only its own `EMAIL_PROVIDER`-keyed branches. Problems from both parses are
- * combined into one error, preserving the "every missing variable at once" rule.
+ * The email variables are parsed separately so a caller sees every missing
+ * variable at once, rather than one at a time.
  *
  * @param environment Raw variables, normally `process.env`.
  * @throws ConfigurationError listing every invalid or missing variable.
@@ -107,11 +150,17 @@ export function loadConfig(environment: Environment): KelpieConfig {
     runtimeMode: environmentResult.data.NODE_ENV,
     port: environmentResult.data.PORT,
     databaseUrl: environmentResult.data.DATABASE_URL,
-    logLevel: environmentResult.data.LOG_LEVEL,
+    logging: {
+      level: environmentResult.data.LOG_LEVEL,
+      destinations: [{ kind: 'stdout' }],
+    },
     email: emailResult.data,
     moduleConfigPath: environmentResult.data.KELPIE_MODULE_CONFIG_PATH,
     webBundleDirectory: environmentResult.data.WEB_BUNDLE_DIR,
     rateLimit: rateLimitConfigFrom(environmentResult.data),
     trustedProxyHopCount: environmentResult.data.TRUSTED_PROXY_HOP_COUNT,
+    env: environment,
+    appBaseUrl: undefined,
+    secretEncryption: undefined,
   }
 }

package/src/lib/email.ts

@@ -1,7 +1,5 @@
-import nodemailer from 'nodemailer'
 import { z } from 'zod'
 
-import { describeThrown } from './errors.ts'
 import type { Logger } from './logger.ts'
 
 /**
@@ -9,15 +7,15 @@ import type { Logger } from './logger.ts'
  * and account-change notifications, nothing else. Kelpie never sends outreach
  * email.
  *
- * Roadmap decision 4: the provider is configured, never hardcoded. Core ships
- * the port and two providers, `log` and `smtp`. Both need no vendor account a
- * deployment doesn't already have, which is what keeps them in core rather than
- * a module, per `modules.md`'s split test. A provider that does need one
- * (Resend, Postmark, Mailtrap, SendGrid) is a commercial integration under that
- * same test and belongs in a module: it supplies its own `EmailSender` from its
- * own config, and an assembly's entry point wires it into `services.email` in
- * place of `createEmailSender`, the same way `kelpie-cloud/src/server.ts` wires
- * this one today.
+ * The assembly names one named provider in `kelpie.config.ts`'s
+ * `email.provider`. The module runtime resolves the name against a registry
+ * every module can contribute to via `context.provideEmailSender(name, sender)`.
+ * `'log'` is a built-in name the runtime always registers, so a bare install
+ * has something to point at. `'smtp'` is registered by the built-in
+ * `smtp-email` core module. Other names come from third-party provider modules
+ * (Resend, Postmark, SES) that follow the same registry pattern. Transport is
+ * arbitrary: the module builds one behind the `EmailSender` interface and
+ * hands it to core, which knows only how to `send`.
  */
 
 export interface EmailMessage {
@@ -30,40 +28,29 @@ export interface EmailSender {
   send(message: EmailMessage): Promise<void>
 }
 
-const logEmailConfigSchema = z.object({
-  EMAIL_PROVIDER: z.literal('log'),
+export const emailConfigSchema = z.object({
+  /**
+   * The named provider `registerModules` resolves against its registry. `'log'`
+   * is a built-in, always present. Any other name needs a module that
+   * registered it via `context.provideEmailSender(name, sender)`. Free-string
+   * so a self-hoster can add a module core has never heard of.
+   */
+  EMAIL_PROVIDER: z.string().min(1),
   EMAIL_FROM: z.string().min(1),
 })
 
-const smtpEmailConfigSchema = z.object({
-  EMAIL_PROVIDER: z.literal('smtp'),
-  EMAIL_FROM: z.string().min(1),
-  SMTP_HOST: z.string().min(1),
-  SMTP_PORT: z.coerce.number().int().positive().max(65535),
-  SMTP_SECURE: z.enum(['true', 'false']).transform((value) => value === 'true'),
-  SMTP_USER: z.string().min(1),
-  SMTP_PASSWORD: z.string().min(1),
-})
-
-export const emailConfigSchema = z.discriminatedUnion('EMAIL_PROVIDER', [
-  logEmailConfigSchema,
-  smtpEmailConfigSchema,
-])
-
 export type EmailConfig = z.infer<typeof emailConfigSchema>
-export type SmtpEmailConfig = z.infer<typeof smtpEmailConfigSchema>
 
 /**
- * Writes the message to the log instead of sending it. For self-hosted
- * development, where the reset link in the log is exactly what you want.
- *
- * This is a deliberate choice, not a fallback: `EMAIL_PROVIDER` has no default,
- * so nobody reaches this provider without naming it.
+ * Writes the message to the log instead of sending it. The registry default,
+ * swapped out for a real sender by picking a different provider name in
+ * `email.provider` (`'smtp'` for the built-in SMTP module, or any name a
+ * third-party provider module registers).
  */
 export function createLogEmailSender(logger: Logger, from: string): EmailSender {
   return {
     send(message) {
-      logger.info('email not sent: provider is "log"', {
+      logger.info('email not sent: no provider module registered', {
         from,
         to: message.to,
         subject: message.subject,
@@ -74,60 +61,3 @@ export function createLogEmailSender(logger: Logger, from: string): EmailSender
     },
   }
 }
-
-/**
- * What `createSmtpEmailSender` sends a message through. A real deployment gets
- * one backed by `nodemailer`; a test injects one that records calls, so the
- * sender is verifiable without a container running a real SMTP conversation.
- */
-export interface SmtpTransport {
-  sendMail(message: { from: string; to: string; subject: string; text: string }): Promise<unknown>
-}
-
-function createNodemailerTransport(config: SmtpEmailConfig): SmtpTransport {
-  return nodemailer.createTransport({
-    host: config.SMTP_HOST,
-    port: config.SMTP_PORT,
-    secure: config.SMTP_SECURE,
-    auth: { user: config.SMTP_USER, pass: config.SMTP_PASSWORD },
-  })
-}
-
-/** Sends over SMTP. `transport` defaults to a real connection built from `config`. */
-export function createSmtpEmailSender(
-  config: SmtpEmailConfig,
-  logger: Logger,
-  transport: SmtpTransport = createNodemailerTransport(config),
-): EmailSender {
-  return {
-    async send(message) {
-      try {
-        await transport.sendMail({
-          from: config.EMAIL_FROM,
-          to: message.to,
-          subject: message.subject,
-          text: message.body,
-        })
-      } catch (cause) {
-        const reason = describeThrown(cause)
-        logger.error('smtp send failed', { to: message.to, reason })
-        throw new Error(`Failed to send email to ${message.to} over SMTP: ${reason}`, { cause })
-      }
-    },
-  }
-}
-
-/**
- * Builds the configured sender.
- *
- * @throws Never. An unknown provider cannot reach here: the config schema is a
- *   discriminated union, so boot rejects it first.
- */
-export function createEmailSender(config: EmailConfig, logger: Logger): EmailSender {
-  switch (config.EMAIL_PROVIDER) {
-    case 'log':
-      return createLogEmailSender(logger, config.EMAIL_FROM)
-    case 'smtp':
-      return createSmtpEmailSender(config, logger)
-  }
-}

package/src/lib/fromEnv.ts

@@ -0,0 +1,143 @@
+import type { ZodType } from 'zod'
+
+import type { Environment } from './config.ts'
+
+/**
+ * A marker a `kelpie.config.ts` file uses to say "read this leaf from the
+ * environment." The assembly's config file is the shape and the defaults;
+ * `fromEnv` marks the leaves a deployment may override without a code change.
+ *
+ * Every marker names an env var, the Zod schema that parses it, and optionally
+ * a default. Without a default the marker is required: the env var must be set,
+ * or boot fails with the other configuration problems.
+ *
+ * The resolver walks the config object, replaces each marker with the parsed
+ * value, and returns the fully-resolved object. Nothing in the app reads
+ * `process.env` for these fields after boot.
+ */
+
+const FROM_ENV_MARKER = Symbol.for('kelpie.fromEnv')
+
+export interface FromEnvMarker<T> {
+  readonly [FROM_ENV_MARKER]: true
+  readonly envKey: string
+  readonly schema: ZodType<T>
+  readonly defaultValue: T | undefined
+  readonly hasDefault: boolean
+}
+
+/** A leaf in the config file: either a literal already-typed value, or a marker. */
+export type ConfigValue<T> = T | FromEnvMarker<T>
+
+export function fromEnv<T>(envKey: string, schema: ZodType<T>): FromEnvMarker<T>
+export function fromEnv<T>(envKey: string, schema: ZodType<T>, defaultValue: T): FromEnvMarker<T>
+export function fromEnv<T>(envKey: string, schema: ZodType<T>, defaultValue?: T): FromEnvMarker<T> {
+  const hasDefault = arguments.length >= 3
+
+  return {
+    [FROM_ENV_MARKER]: true,
+    envKey,
+    schema,
+    defaultValue: hasDefault ? (defaultValue as T) : undefined,
+    hasDefault,
+  }
+}
+
+export function isFromEnvMarker(value: unknown): value is FromEnvMarker<unknown> {
+  return typeof value === 'object' && value !== null && (value as Record<PropertyKey, unknown>)[FROM_ENV_MARKER] === true
+}
+
+/** One problem discovered while resolving markers. Path is the dotted field. */
+export interface FromEnvProblem {
+  readonly path: string
+  readonly message: string
+}
+
+export interface ResolveResult<T> {
+  readonly value: T | undefined
+  readonly problems: readonly FromEnvProblem[]
+}
+
+/**
+ * Resolves one marker against an environment.
+ *
+ * Missing and no default: one required problem.
+ * Missing with default: the default, unvalidated. A hardcoded default is
+ * trusted because the developer wrote it in the assembly file.
+ * Present: parsed through the marker's schema. Parse failures become problems.
+ */
+export function resolveMarker<T>(marker: FromEnvMarker<T>, environment: Environment, path: string): ResolveResult<T> {
+  const raw = environment[marker.envKey]
+
+  if (raw === undefined) {
+    if (marker.hasDefault) {
+      return { value: marker.defaultValue, problems: [] }
+    }
+
+    return {
+      value: undefined,
+      problems: [{ path, message: `${marker.envKey} is required` }],
+    }
+  }
+
+  const result = marker.schema.safeParse(raw)
+
+  if (!result.success) {
+    return {
+      value: undefined,
+      problems: result.error.issues.map((issue) => ({
+        path,
+        message: `${marker.envKey}: ${issue.message}`,
+      })),
+    }
+  }
+
+  return { value: result.data, problems: [] }
+}
+
+/**
+ * Walks any value, replacing every `FromEnvMarker` with its resolved value.
+ * Objects and arrays are walked recursively; other values pass through.
+ *
+ * Collects problems from every marker rather than throwing at the first one,
+ * so a self-hoster fixes their environment once rather than a variable at a
+ * time.
+ */
+export function resolveMarkers(
+  input: unknown,
+  environment: Environment,
+  path = '',
+): { readonly value: unknown; readonly problems: readonly FromEnvProblem[] } {
+  if (isFromEnvMarker(input)) {
+    return resolveMarker(input, environment, path)
+  }
+
+  if (Array.isArray(input)) {
+    const problems: FromEnvProblem[] = []
+    const value = input.map((item, index) => {
+      const childPath = `${path}[${String(index)}]`
+      const result = resolveMarkers(item, environment, childPath)
+      problems.push(...result.problems)
+
+      return result.value
+    })
+
+    return { value, problems }
+  }
+
+  if (typeof input === 'object' && input !== null) {
+    const problems: FromEnvProblem[] = []
+    const value: Record<string, unknown> = {}
+
+    for (const [key, child] of Object.entries(input)) {
+      const childPath = path.length > 0 ? `${path}.${key}` : key
+      const result = resolveMarkers(child, environment, childPath)
+      problems.push(...result.problems)
+      value[key] = result.value
+    }
+
+    return { value, problems }
+  }
+
+  return { value: input, problems: [] }
+}

package/src/lib/ids.ts

@@ -52,6 +52,12 @@ export const idPrefixes = {
    * a bucket is bookkeeping the rate limiter owns, not a resource with routes.
    */
   rateLimitBucket: 'rl',
+  /**
+   * One published domain event. Stamped on the envelope so downstream consumers
+   * (webhooks, MCP subscribers, an eventual outbox) have a stable idempotency
+   * key. Not persisted by core.
+   */
+  event: 'ev',
 } as const
 
 export type ObjectKind = keyof typeof idPrefixes