@kelpie/server 0.5.1 → 0.6.0

package/src/modules/raises/service.ts

@@ -14,8 +14,10 @@ import {
   describeUpdate,
 } from '../activities/wording.ts'
 import type { FieldLabels } from '../activities/wording.ts'
+import { toEventActor } from '../../lib/actor.ts'
 import type { Actor } from '../auth/actor.ts'
 import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
+import './events.ts'
 import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
 import * as companyRepository from '../companies/repository.ts'
 import * as pipelineRepository from '../pipelines/repository.ts'
@@ -301,10 +303,10 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
           })
         }
 
-        events.emit('record.created', { workspaceId, objectType: 'raise', recordId: id })
+        events.emit('raises.raise.created', { type: 'raise', id }, {})
 
         return toView(created, personIds)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {
@@ -402,25 +404,22 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
           })
         }
 
-        events.emit('record.updated', {
-          workspaceId,
-          objectType: 'raise',
-          recordId: id,
-          changedFields: linksChanged ? [...changed, 'personIds'] : changed,
-        })
+        events.emit(
+          'raises.raise.updated',
+          { type: 'raise', id },
+          { changed: linksChanged ? [...changed, 'personIds'] : changed },
+        )
 
         if (stageMove !== undefined) {
-          events.emit('stage.changed', {
-            workspaceId,
-            objectType: 'raise',
-            recordId: id,
-            fromStageId: stageMove.from.id,
-            toStageId: stageMove.to.id,
-          })
+          events.emit(
+            'raises.raise.stage_changed',
+            { type: 'raise', id },
+            { fromStageId: stageMove.from.id, toStageId: stageMove.to.id },
+          )
         }
 
         return toView(updated, nextPeople ?? currentPeople)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async remove(actor, id) {
@@ -435,8 +434,8 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
         await deleteRecordsAttachedTo(tx, workspaceId, 'raise', id)
         await repository.deleteRaise(tx, workspaceId, id)
 
-        events.emit('record.deleted', { workspaceId, objectType: 'raise', recordId: id })
-      })
+        events.emit('raises.raise.deleted', { type: 'raise', id }, {})
+      }, { workspaceId, actor: toEventActor(actor) })
     },
   }
 }

package/src/modules/reseal.ts

@@ -1,7 +1,11 @@
 import { eq } from 'drizzle-orm'
 
+import { ConfigurationError } from '../lib/config.ts'
+import type { KelpieConfig } from '../lib/config.ts'
+import { connectDatabase } from '../lib/database.ts'
 import type { Database } from '../lib/database.ts'
-import { SecretDecryptionError } from '../lib/secrets.ts'
+import type { Logger } from '../lib/logger.ts'
+import { createSecretCipher, secretEncryptionConfigSchema, SecretDecryptionError } from '../lib/secrets.ts'
 import type { SecretCipher } from '../lib/secrets.ts'
 import { agentRegistrations } from './agent-tasks/schema.ts'
 import { webhooks } from './webhooks/schema.ts'
@@ -164,3 +168,142 @@ export async function resealStoredSecrets(
     unreadable: columns.reduce((total, column) => total + column.unreadable.length, 0),
   }
 }
+
+/**
+ * One reseal pass over some set of columns. Core's own pass is one; a module
+ * with its own sealed table exports one too, and the assembly wires it in as
+ * an `extraPasses` entry.
+ *
+ * The shape matches `resealStoredSecrets` on purpose, so a pass covering a
+ * single column returns a one-element `columns` and `runReseal` can print
+ * every pass the same way.
+ */
+export type ResealPass = (db: Database, cipher: SecretCipher) => Promise<ResealOutcome>
+
+export interface RunResealOptions {
+  readonly config: KelpieConfig
+  readonly logger: Logger
+  /**
+   * Extra passes to run after core's own. An assembly wires its modules'
+   * sealed columns in here; each pass covers columns core cannot see.
+   */
+  readonly extraPasses?: readonly ResealPass[]
+  /** Where the per-column report goes. Defaults to stdout. */
+  readonly report?: (message: string) => void
+  /** Where unreadable-row ids and the trailing failure summary go. Defaults to stderr. */
+  readonly reportFatal?: (message: string) => void
+}
+
+function defaultReport(message: string): void {
+  process.stdout.write(`${message}\n`)
+}
+
+function defaultReportFatal(message: string): void {
+  process.stderr.write(`${message}\n`)
+}
+
+/**
+ * Runs every reseal pass under the current `SECRET_ENCRYPTION_KEY` and
+ * prints a report. Returns the exit code a script should return: 0 if every
+ * examined value is now under the current key, 1 if any row was unreadable.
+ *
+ * The rotation procedure, in full:
+ *
+ *   1. Keep the current key. Add the new one as `SECRET_ENCRYPTION_KEY` and
+ *      move the old value to `SECRET_ENCRYPTION_KEY_PREVIOUS`.
+ *   2. Deploy. Deliveries keep signing: new secrets seal under the new key,
+ *      and existing ones still open under the previous one.
+ *   3. Run the reseal script. It rewrites every row still sealed under the
+ *      old key.
+ *   4. Remove `SECRET_ENCRYPTION_KEY_PREVIOUS` and deploy again.
+ *
+ * Safe to run at any point, including with no previous key set, where it
+ * reports that everything is already current and writes nothing.
+ *
+ * Prefers `config.secretEncryption` (the top-level field an assembly's
+ * `kelpie.config.ts` declares). Falls back to parsing `config.env` for
+ * older assemblies and for `loadConfig`-based callers that never populate
+ * the top-level field. Either path validates before the pass opens a row,
+ * so a mistyped key throws `ConfigurationError` at boot rather than
+ * reporting every row as unreadable.
+ *
+ * @throws ConfigurationError if neither `config.secretEncryption` nor the
+ *   fallback env parse produces a valid `SecretEncryptionConfig`. The
+ *   database is closed before the throw.
+ */
+export async function runReseal(options: RunResealOptions): Promise<number> {
+  const report = options.report ?? defaultReport
+  const reportFatal = options.reportFatal ?? defaultReportFatal
+  const database = connectDatabase(options.config.databaseUrl, options.logger)
+
+  let secretConfig = options.config.secretEncryption
+
+  if (secretConfig === undefined) {
+    const parsed = secretEncryptionConfigSchema.safeParse(options.config.env)
+
+    if (!parsed.success) {
+      await database.close()
+
+      throw new ConfigurationError(
+        parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`),
+      )
+    }
+
+    secretConfig = parsed.data
+  }
+
+  const hasPrevious =
+    secretConfig.SECRET_ENCRYPTION_KEY_PREVIOUS !== undefined &&
+    secretConfig.SECRET_ENCRYPTION_KEY_PREVIOUS.trim().length > 0
+
+  if (!hasPrevious) {
+    report('SECRET_ENCRYPTION_KEY_PREVIOUS is not set. Nothing sealed under an older key can be read.')
+  }
+
+  const cipher = createSecretCipher(secretConfig)
+  const passes: readonly ResealPass[] = [resealStoredSecrets, ...(options.extraPasses ?? [])]
+
+  try {
+    // Sequential rather than `Promise.all`, so two full-table passes never
+    // contend for the pool at once. Each pass is idempotent; a run that
+    // dies halfway leaves the finished rows current and re-running
+    // completes the rest.
+    const outcomes: ResealOutcome[] = []
+    for (const pass of passes) {
+      outcomes.push(await pass(database.db, cipher))
+    }
+
+    const columns = outcomes.flatMap((outcome) => outcome.columns)
+    const examined = outcomes.reduce((total, outcome) => total + outcome.examined, 0)
+    const resealed = outcomes.reduce((total, outcome) => total + outcome.resealed, 0)
+    const unreadable = outcomes.reduce((total, outcome) => total + outcome.unreadable, 0)
+
+    for (const column of columns) {
+      report(
+        `${column.label}: ${String(column.examined)} examined, ${String(column.resealed)} re-sealed, ${String(column.unreadable.length)} unreadable`,
+      )
+
+      for (const id of column.unreadable) {
+        reportFatal(`  unreadable: ${id}`)
+      }
+    }
+
+    if (unreadable > 0) {
+      reportFatal(
+        `\n${String(unreadable)} value(s) opened under neither key. They were sealed under a key that is not configured, or the rows have been altered. Nothing here can recover them: set SECRET_ENCRYPTION_KEY_PREVIOUS to the key they were sealed with and run this again, or have those records re-created.`,
+      )
+
+      return 1
+    }
+
+    report(
+      resealed === 0
+        ? `\nNothing to do: all ${String(examined)} value(s) are already sealed under the current key.`
+        : `\nRe-sealed ${String(resealed)} of ${String(examined)} value(s). You can now remove SECRET_ENCRYPTION_KEY_PREVIOUS.`,
+    )
+
+    return 0
+  } finally {
+    await database.close()
+  }
+}

package/src/modules/smtp-email/index.ts

@@ -0,0 +1,119 @@
+import nodemailer from 'nodemailer'
+import { z } from 'zod'
+
+import { describeThrown } from '../../lib/errors.ts'
+import type { EmailMessage, EmailSender } from '../../lib/email.ts'
+import type { Logger } from '../../lib/logger.ts'
+import type { KelpieModule } from '../../runtime/module.ts'
+
+/**
+ * The built-in SMTP email module.
+ *
+ * Registers a provider named `'smtp'` with core's email runtime. An assembly
+ * that sets `email.provider: 'smtp'` in its `kelpie.config.ts` uses this
+ * sender; any other value picks a different provider (`'log'` for the built-in
+ * or another provider module's name). Reads `EMAIL_FROM` and `SMTP_*` from the
+ * environment; missing or malformed values fail boot.
+ *
+ * A commercial email integration (Resend, Postmark) belongs in its own module
+ * following the same shape, registered under a different name.
+ */
+
+/**
+ * The name this module registers under. An assembly puts `provider: 'smtp'`
+ * in its `email` block to pick it.
+ */
+export const SMTP_EMAIL_PROVIDER = 'smtp'
+
+export type { EmailMessage } from '../../lib/email.ts'
+
+const smtpEmailConfigSchema = z.object({
+  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 type SmtpEmailConfig = z.infer<typeof smtpEmailConfigSchema>
+
+/**
+ * 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: EmailMessage) {
+      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 })
+      }
+    },
+  }
+}
+
+/**
+ * Options a caller may pass when building the module. `transport` is here for
+ * tests; a real deployment omits it and lets the module open a nodemailer
+ * connection from the resolved config.
+ */
+export interface SmtpEmailModuleOptions {
+  readonly transport?: SmtpTransport
+}
+
+/**
+ * The built-in SMTP module. Registers a factory under `SMTP_EMAIL_PROVIDER`;
+ * the factory reads the SMTP environment and builds the nodemailer sender, but
+ * only if the assembly's `email.provider` picks this module. Boot fails loudly
+ * if any SMTP variable is missing or malformed at that point.
+ *
+ * The module stays in `coreModules` unconditionally: on any other provider
+ * (e.g. `EMAIL_PROVIDER=log`) the factory never runs, so the SMTP environment
+ * is not checked.
+ */
+export function createSmtpEmailModule(options: SmtpEmailModuleOptions = {}): KelpieModule {
+  return {
+    id: 'smtp-email',
+    structural: true,
+
+    register(context) {
+      context.provideEmailSender(SMTP_EMAIL_PROVIDER, () => {
+        const config = context.config(smtpEmailConfigSchema)
+
+        return options.transport === undefined
+          ? createSmtpEmailSender(config, context.log)
+          : createSmtpEmailSender(config, context.log, options.transport)
+      })
+
+      return Promise.resolve()
+    },
+  }
+}

package/src/modules/webhooks/index.ts

@@ -48,7 +48,11 @@ export function createWebhooksModule(
       // when a customer's endpoint goes quiet is far too late. The retention
       // window is validated the same way for the same reason — a bad value
       // should stop boot, not prune by the wrong window.
-      const cipher = createSecretCipher(context.config(secretEncryptionConfigSchema))
+      //
+      // Prefer the top-level `secretEncryption` from the assembly's
+      // kelpie.config.ts; fall back to the schema read for older assemblies
+      // that don't declare it.
+      const cipher = createSecretCipher(context.secretEncryption ?? context.config(secretEncryptionConfigSchema))
       const retention = context.config(deliveryRetentionConfigSchema)
       const egress = createEgressGuard(context.config(egressConfigSchema))
 

package/src/modules/webhooks/payloads.ts

@@ -1,13 +1,21 @@
-import type { WebhookEvent } from '@kelpie/schemas'
+import type { KelpieEvent, WebhookEvent } from '@kelpie/schemas'
 
-import type { DomainEvents, EventBus } from '../../runtime/events.ts'
+import type { EventBus } from '../../runtime/events.ts'
+import { RECORD_OBJECT_TYPES } from '../../runtime/events.ts'
+import type { RecordObjectType } from '../../runtime/events.ts'
 
 /**
  * The bridge from the internal event catalog to what a webhook receiver sees.
  *
  * `modules.md` makes the webhooks engine a consumer of the bus, so this is the
  * only place that knows both vocabularies. Everything downstream works with a
- * `WebhookEventPayload` and never sees a `DomainEvents` key.
+ * `WebhookEventPayload` and never sees an internal event key.
+ *
+ * A single prefix subscribe (`''`) sees every envelope event, and the
+ * translator below decides whether the event corresponds to a deliverable wire
+ * event. Unrecognised names are dropped, so a module's private events (a
+ * `.stage_changed` on a deal, a `.added` on a note) never reach a receiver
+ * that never subscribed to them.
  *
  * Payload keys are `snake_case`, matching `api.md`, because a receiver has no
  * reason to expect a different convention from a webhook than from the REST
@@ -24,61 +32,99 @@ export interface WebhookEventPayload {
   readonly data: Record<string, unknown>
 }
 
+const recordObjectTypes = new Set<string>(RECORD_OBJECT_TYPES)
+
+interface RecordUpdatedData {
+  readonly changed?: readonly string[]
+}
+
+interface FormSubmittedData {
+  readonly formId?: string
+  readonly submissionId?: string
+}
+
 /**
- * Payload builders, one per deliverable event.
+ * Translates an envelope event into a `WebhookEventPayload`, or `undefined` if
+ * the event does not correspond to any deliverable wire event.
  *
- * `satisfies` is what keeps this honest: adding a name to `WEBHOOK_EVENTS`
- * without a builder here is a compile error rather than an event that resolves
- * to nothing at runtime.
+ * The last segment of the event name (`.created`, `.updated`, `.deleted`,
+ * `.submitted`) picks the wire event. A `.created`/`.updated`/`.deleted` event
+ * is only translated when its target type is one of the CRM record objects
+ * (`RECORD_OBJECT_TYPES`), because those are the only ones the wire catalog
+ * offers. Everything else is skipped.
  */
-const builders = {
-  'record.created': (payload: DomainEvents['record.created']): WebhookEventPayload => ({
-    workspaceId: payload.workspaceId,
-    event: 'record.created',
-    data: { object_type: payload.objectType, record_id: payload.recordId },
-  }),
-
-  'record.updated': (payload: DomainEvents['record.updated']): WebhookEventPayload => ({
-    workspaceId: payload.workspaceId,
-    event: 'record.updated',
-    data: {
-      object_type: payload.objectType,
-      record_id: payload.recordId,
-      // The values stay as the emitting service named them, which is camelCase
-      // (`parentId`, `sortOrder`) even though the keys around them are not.
-      // Translating them to the wire spelling would mean a second copy of every
-      // module's column naming, kept in step by hand.
-      changed_fields: [...payload.changedFields],
-    },
-  }),
+export function translateEnvelopeEvent(
+  event: KelpieEvent<string, unknown>,
+): WebhookEventPayload | undefined {
+  const suffix = event.name.slice(event.name.lastIndexOf('.') + 1)
+  const objectType = event.target.type
+
+  if (suffix === 'created' || suffix === 'deleted') {
+    if (!recordObjectTypes.has(objectType)) {
+      return undefined
+    }
 
-  'record.deleted': (payload: DomainEvents['record.deleted']): WebhookEventPayload => ({
-    workspaceId: payload.workspaceId,
-    event: 'record.deleted',
-    data: { object_type: payload.objectType, record_id: payload.recordId },
-  }),
+    return {
+      workspaceId: event.workspaceId,
+      event: suffix === 'created' ? 'record.created' : 'record.deleted',
+      data: { object_type: objectType as RecordObjectType, record_id: event.target.id },
+    }
+  }
 
-  'form.submitted': (payload: DomainEvents['form.submitted']): WebhookEventPayload => ({
-    workspaceId: payload.workspaceId,
-    event: 'form.submitted',
-    data: { form_id: payload.formId, submission_id: payload.submissionId },
-  }),
-} satisfies { [Name in WebhookEvent]: (payload: DomainEvents[Name]) => WebhookEventPayload }
+  if (suffix === 'updated') {
+    if (!recordObjectTypes.has(objectType)) {
+      return undefined
+    }
+
+    const data = event.data as RecordUpdatedData
+    return {
+      workspaceId: event.workspaceId,
+      event: 'record.updated',
+      data: {
+        object_type: objectType as RecordObjectType,
+        record_id: event.target.id,
+        changed_fields: data.changed !== undefined ? [...data.changed] : [],
+      },
+    }
+  }
+
+  if (suffix === 'submitted') {
+    // Form submission is the only `.submitted` wire event today. The forms
+    // module emits its envelope with `formId` and `submissionId` in `data`.
+    const data = event.data as FormSubmittedData
+    if (data.formId === undefined || data.submissionId === undefined) {
+      return undefined
+    }
+
+    return {
+      workspaceId: event.workspaceId,
+      event: 'form.submitted',
+      data: { form_id: data.formId, submission_id: data.submissionId },
+    }
+  }
+
+  return undefined
+}
 
 /**
- * Subscribes the engine to every deliverable event.
- *
- * Written out one call at a time rather than looped over `WEBHOOK_EVENTS`,
- * because TypeScript cannot correlate a payload type with a generic key: a loop
- * would need a cast, and the cast is exactly what would let a wrong payload
- * through. A literal key indexes `builders` at its precise signature.
+ * Subscribes the engine to every deliverable event through one prefix match on
+ * `''`, which every envelope event starts with. The translator inside decides
+ * whether the event corresponds to a deliverable wire event; unrecognised
+ * names are dropped.
  */
 export function subscribeDeliverableEvents(
   bus: EventBus,
   deliver: (payload: WebhookEventPayload) => Promise<void>,
 ): void {
-  bus.subscribe('record.created', (payload) => deliver(builders['record.created'](payload)))
-  bus.subscribe('record.updated', (payload) => deliver(builders['record.updated'](payload)))
-  bus.subscribe('record.deleted', (payload) => deliver(builders['record.deleted'](payload)))
-  bus.subscribe('form.submitted', (payload) => deliver(builders['form.submitted'](payload)))
+  bus.subscribePrefix(
+    '',
+    async (event) => {
+      const built = translateEnvelopeEvent(event)
+      if (built === undefined) {
+        return
+      }
+      await deliver(built)
+    },
+    { label: 'webhooks:envelope-bridge' },
+  )
 }

package/src/modules/workspace/events.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/**
+ * Domain events published by the workspace module.
+ *
+ * Workspace-level events (`workspace.workspace.*`) target the workspace itself.
+ * Membership events target the `workspace_members` row, with the user id in
+ * `data` so a consumer that watches identity does not need a second lookup.
+ */
+
+export const workspaceEvents = {
+  'workspace.workspace.created': z.object({ slug: z.string() }),
+  'workspace.workspace.deleted': z.object({ slug: z.string() }),
+  'workspace.member.invited': z.object({ inviteId: z.string(), email: z.string() }),
+  'workspace.member.joined': z.object({ userId: z.string() }),
+  'workspace.member.removed': z.object({ userId: z.string() }),
+} satisfies ModuleEventCatalog
+
+export interface WorkspaceCreatedData {
+  readonly slug: string
+}
+export interface WorkspaceDeletedData {
+  readonly slug: string
+}
+export interface MemberInvitedData {
+  readonly inviteId: string
+  readonly email: string
+}
+export interface MemberJoinedData {
+  readonly userId: string
+}
+export interface MemberRemovedData {
+  readonly userId: string
+}
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'workspace.workspace.created': WorkspaceCreatedData
+    'workspace.workspace.deleted': WorkspaceDeletedData
+    'workspace.member.invited': MemberInvitedData
+    'workspace.member.joined': MemberJoinedData
+    'workspace.member.removed': MemberRemovedData
+  }
+}

package/src/modules/workspace/index.ts

@@ -2,6 +2,7 @@ import { appUrlConfigSchema } from '../../lib/appUrl.ts'
 import type { KelpieModule } from '../../runtime/module.ts'
 import { parseModuleCapability } from '../../runtime/moduleConfig.ts'
 import { SEATS_LIMIT, WORKSPACE_ACCESS } from './capabilities.ts'
+import { workspaceEvents } from './events.ts'
 import * as repository from './repository.ts'
 import { mountWorkspaceRoutes } from './routes.ts'
 import * as schema from './schema.ts'
@@ -19,9 +20,12 @@ export function createWorkspaceModule(migrationsDirectory: string): KelpieModule
     id: 'workspace',
     requires: ['auth'],
     structural: true,
+    events: workspaceEvents,
 
     register(context) {
-      const config = context.config(appUrlConfigSchema)
+      // Prefer the top-level `appBaseUrl` from the assembly's kelpie.config.ts;
+      // fall back to the schema read for older assemblies that don't declare it.
+      const appBaseUrl = context.appBaseUrl ?? context.config(appUrlConfigSchema).APP_BASE_URL
 
       context.entitlements.declare(SEATS_LIMIT)
       context.entitlements.declare(WORKSPACE_ACCESS)
@@ -48,7 +52,7 @@ export function createWorkspaceModule(migrationsDirectory: string): KelpieModule
         createId: context.createId,
         now: context.now,
         entitlements: context.entitlements,
-        appBaseUrl: config.APP_BASE_URL,
+        appBaseUrl,
         toggleableModuleIds: context.moduleCatalog
           .filter((entry) => !entry.structural)
           .map((entry) => entry.id),