create-kelpie 0.5.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kelpie",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Scaffold a self-hosted Kelpie assembly. Run it with npm create kelpie.",
   "keywords": [
     "kelpie",

package/templates/README.md

@@ -40,10 +40,15 @@ Then open <http://localhost:__WEB_PORT__/signup> and create an account.
 Passwords need at least 12 characters. Signup names your workspace, invites your
 team, and leaves you on People with a starter handbook in place.
 
-This default configuration doesn't send email. `EMAIL_PROVIDER=log` prints
-invitation and password-reset links to the API's log instead of mailing them;
-copy them from there to follow either flow. Set `EMAIL_PROVIDER=smtp` below to
-send them for real.
+This install picks its transactional-mail sender through `EMAIL_PROVIDER` in
+`.env`. Out of the box it is `log`, which writes invitation and password-reset
+messages to the API's log instead of sending them; copy the link from there
+to follow either flow locally. Set `EMAIL_PROVIDER=smtp` and fill in the
+`SMTP_*` variables below to send them over SMTP through the built-in
+`smtp-email` core module (no install needed). Other provider modules
+(Resend, Postmark, …) register their own name; install one, add it to
+`kelpie.config.ts`'s `modules:`, and set `EMAIL_PROVIDER` to that name to
+use it instead.
 
 ## Adding a module
 
@@ -66,13 +71,13 @@ lists every problem at once.
 | `DATABASE_URL` | A `postgres://` or `postgresql://` connection string |
 | `APP_BASE_URL` | The address people reach this Kelpie on. Emailed links (verification, password reset, invitations) are built from it. In development that is the Vite dev server; a deployment sets its real origin |
 | `LOG_LEVEL` | `debug`, `info`, `warn`, or `error` |
-| `EMAIL_PROVIDER` | `log` or `smtp`. `log` writes invitations and resets to the log instead of sending them |
+| `EMAIL_PROVIDER` | Name of the transactional-mail sender to use. `log` (built in) writes to the log instead of sending; `smtp` sends over SMTP through the built-in `smtp-email` core module; other names come from third-party provider modules |
 | `EMAIL_FROM` | The address transactional mail comes from |
-| `SMTP_HOST` | Required when `EMAIL_PROVIDER=smtp`. The mail server to connect to |
-| `SMTP_PORT` | Required when `EMAIL_PROVIDER=smtp`. The mail server's port |
-| `SMTP_SECURE` | Required when `EMAIL_PROVIDER=smtp`. `true` or `false`. Whether to connect over TLS from the start (typically port 465) rather than upgrading with STARTTLS (typically port 587 or 25) |
-| `SMTP_USER` | Required when `EMAIL_PROVIDER=smtp`. The SMTP username |
-| `SMTP_PASSWORD` | Required when `EMAIL_PROVIDER=smtp`. The SMTP password |
+| `SMTP_HOST` | Read by the built-in `smtp-email` module when `EMAIL_PROVIDER=smtp`. The mail server to connect to |
+| `SMTP_PORT` | Read by the built-in `smtp-email` module when `EMAIL_PROVIDER=smtp`. The mail server's port |
+| `SMTP_SECURE` | Read by the built-in `smtp-email` module when `EMAIL_PROVIDER=smtp`. `true` or `false`. Whether to connect over TLS from the start (typically port 465) rather than upgrading with STARTTLS (typically port 587 or 25) |
+| `SMTP_USER` | Read by the built-in `smtp-email` module when `EMAIL_PROVIDER=smtp`. The SMTP username |
+| `SMTP_PASSWORD` | Read by the built-in `smtp-email` module when `EMAIL_PROVIDER=smtp`. The SMTP password |
 | `SECRET_ENCRYPTION_KEY` | 32 bytes of base64, generated for this project |
 | `SECRET_ENCRYPTION_KEY_PREVIOUS` | Optional. Set only while rotating the key above |
 | `WEBHOOK_DELIVERY_RETENTION_DAYS` | Optional, default 30 |

package/templates/env

@@ -26,17 +26,22 @@ APP_BASE_URL=http://localhost:__WEB_PORT__
 # changing it needs the rotation procedure in README.md.
 SECRET_ENCRYPTION_KEY=__SECRET_ENCRYPTION_KEY__
 
-# `log` writes invitations and password resets to the log instead of sending
-# them. `smtp` sends for real, through the server and credentials below.
+# EMAIL_PROVIDER picks a named sender the runtime resolves. `log` is a
+# built-in that writes messages to the log instead of sending them; `smtp`
+# comes from `@kelpie/module-smtp-email`, which reads the SMTP variables
+# below. A different provider module (Resend, Postmark, …) registers its
+# own name — set EMAIL_PROVIDER to that name to use it.
 EMAIL_PROVIDER=log
 EMAIL_FROM=__EMAIL_FROM__
 
-# Required only when EMAIL_PROVIDER=smtp; ignored otherwise. SMTP_SECURE is
-# "true" for a server that expects TLS from the first byte (usually port 465),
-# "false" for one you connect to in plain text and that upgrades with STARTTLS
-# (usually port 587 or 25).
-# SMTP_HOST=smtp.example.com
-# SMTP_PORT=587
-# SMTP_SECURE=false
-# SMTP_USER=
-# SMTP_PASSWORD=
+# Read by `@kelpie/module-smtp-email` when EMAIL_PROVIDER=smtp. Ignored
+# otherwise.
+#
+# SMTP_SECURE is "true" for a server that expects TLS from the first byte
+# (usually port 465), "false" for one you connect to in plain text and that
+# upgrades with STARTTLS (usually port 587 or 25).
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=
+SMTP_PASSWORD=

package/templates/kelpie.config.ts

@@ -1,21 +1,114 @@
-import { coreModules } from '@kelpie/server'
-import type { KelpieModule } from '@kelpie/server'
+import {
+  appUrlConfigSchema,
+  coreModules,
+  defineKelpieConfig,
+  fromEnv,
+  secretEncryptionConfigSchema,
+} from '@kelpie/server'
+import { z } from 'zod'
 
 /**
- * The server module list, and the only place it is declared.
+ * Your Kelpie service's configuration, and the only place it is declared.
  *
- * Boot registers these in order, after resolving what each one requires. An
- * unknown id, an unmet dependency, or invalid module configuration stops boot
- * rather than starting a service that is missing a feature.
+ * Every leaf is either a literal, committed to git and locked in for this
+ * deployment, or `fromEnv(...)`, marking a leaf the environment fills in. Edit
+ * this file for anything that should not change per deploy, and set environment
+ * variables (in `.env`, `.env.local`, or your process manager) for anything
+ * that does (secrets, per-tier limits, per-environment URLs).
  *
- * Add a module by installing it and putting it in this array:
+ * `resolveKelpieConfig(config, process.env)` at boot walks this object,
+ * resolves markers, validates, and produces the typed `KelpieConfig` the app
+ * runs on. Nothing in the app reads `process.env` for these fields after boot.
  *
- *   import { smtpEmail } from '@kelpie/module-smtp-email'
- *
- *   export const modules: readonly KelpieModule[] = [...coreModules, smtpEmail]
- *
- * Removing one from `coreModules` is possible too, but core modules depend on
- * each other, so boot will tell you if you have taken out something another
- * module needs.
+ * Add a module by installing it and putting it in the `modules` array below.
+ * `coreModules` already includes the built-in `smtp-email` module; set
+ * `EMAIL_PROVIDER=log` to fall back to the log sender.
  */
-export const modules: readonly KelpieModule[] = [...coreModules]
+
+const runtimeMode = z.enum(['development', 'test', 'production'])
+const logLevel = z.enum(['debug', 'info', 'warn', 'error'])
+const positiveInt = z.coerce.number().int().positive()
+const nonNegativeInt = z.coerce.number().int().nonnegative()
+const port = positiveInt.max(65535)
+const postgresUrl = z.string().refine(
+  (value) => {
+    try {
+      const { protocol } = new URL(value)
+      return protocol === 'postgres:' || protocol === 'postgresql:'
+    } catch {
+      return false
+    }
+  },
+  { message: 'must be a postgres:// or postgresql:// connection string' },
+)
+
+export default defineKelpieConfig({
+  runtimeMode: fromEnv('NODE_ENV', runtimeMode),
+  port: fromEnv('PORT', port),
+  databaseUrl: fromEnv('DATABASE_URL', postgresUrl),
+
+  // Every log line writes to each entry in `destinations`. Stdout is the
+  // default. Add a destination by extending the `LoggingDestination` union in
+  // `@kelpie/server` and placing an entry here.
+  logging: {
+    level: fromEnv('LOG_LEVEL', logLevel),
+    destinations: [{ kind: 'stdout' }],
+  },
+
+  webBundleDirectory: fromEnv<string | undefined>('WEB_BUNDLE_DIR', z.string().min(1).optional(), undefined),
+  moduleConfigPath: fromEnv<string | undefined>('KELPIE_MODULE_CONFIG_PATH', z.string().min(1).optional(), undefined),
+  trustedProxyHopCount: fromEnv('TRUSTED_PROXY_HOP_COUNT', nonNegativeInt, 0),
+
+  // The deployment's base URL. Every emailed link (invite, password reset,
+  // email verification) is built from it.
+  appBaseUrl: fromEnv('APP_BASE_URL', appUrlConfigSchema.shape.APP_BASE_URL),
+
+  // Keys that seal stored secrets. Generate one with:
+  //   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+  // To rotate, set the current key as `previousKey`, put the new key here,
+  // deploy, then run `npm run reseal`.
+  secretEncryption: {
+    key: fromEnv('SECRET_ENCRYPTION_KEY', secretEncryptionConfigSchema.shape.SECRET_ENCRYPTION_KEY),
+    previousKey: fromEnv<string | undefined>(
+      'SECRET_ENCRYPTION_KEY_PREVIOUS',
+      secretEncryptionConfigSchema.shape.SECRET_ENCRYPTION_KEY_PREVIOUS,
+      undefined,
+    ),
+  },
+
+  // `provider` picks a named sender from the runtime's registry: `'log'` is
+  // built in and writes the message to the log instead of sending it. `'smtp'`
+  // is registered by the built-in `smtp-email` core module and reads the
+  // `SMTP_*` variables at boot when it is picked. Other names come from
+  // third-party provider modules (Resend, Postmark) added to `modules` below.
+  // `from` is the address on every outgoing message.
+  email: {
+    provider: fromEnv('EMAIL_PROVIDER', z.string().min(1)),
+    from: fromEnv('EMAIL_FROM', z.string().min(1)),
+  },
+
+  rateLimit: {
+    forms: {
+      limit: fromEnv('RATE_LIMIT_FORMS_LIMIT', positiveInt, 20),
+      windowSeconds: fromEnv('RATE_LIMIT_FORMS_WINDOW_SECONDS', positiveInt, 60),
+    },
+    auth: {
+      limit: fromEnv('RATE_LIMIT_AUTH_LIMIT', positiveInt, 10),
+      windowSeconds: fromEnv('RATE_LIMIT_AUTH_WINDOW_SECONDS', positiveInt, 60),
+    },
+    loginAccount: {
+      limit: fromEnv('RATE_LIMIT_LOGIN_ACCOUNT_LIMIT', positiveInt, 10),
+      windowSeconds: fromEnv('RATE_LIMIT_LOGIN_ACCOUNT_WINDOW_SECONDS', positiveInt, 900),
+    },
+    api: {
+      limit: fromEnv('RATE_LIMIT_API_LIMIT', positiveInt, 600),
+      windowSeconds: fromEnv('RATE_LIMIT_API_WINDOW_SECONDS', positiveInt, 60),
+    },
+  },
+
+  // `coreModules` already includes the built-in `smtp-email` module, which
+  // registers a `'smtp'` provider. Set `EMAIL_PROVIDER=log` to fall back to
+  // the built-in log sender; the `smtp-email` module only reads the SMTP
+  // environment when `email.provider` picks its name.
+  modules: [...coreModules],
+})

package/templates/src/reseal.ts

@@ -1,101 +1,33 @@
 import {
   ConfigurationError,
-  connectDatabase,
   createLogger,
-  createSecretCipher,
-  loadConfig,
-  resealStoredSecrets,
-  secretEncryptionConfigSchema,
+  createTransportForDestination,
+  resolveKelpieConfig,
+  runReseal,
 } from '@kelpie/server'
 
+import kelpieConfig from '../kelpie.config.ts'
+
 /**
  * Re-seals stored secrets after `SECRET_ENCRYPTION_KEY` changes.
  *
- * 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 `npm run reseal`. 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.
- *
- * A script rather than a subcommand because the repository has no CLI surface
- * yet. When self-host packaging adds one, this becomes a subcommand of it and
- * the body moves across unchanged.
+ * The rotation procedure lives on `runReseal`'s JSDoc; this file only wires
+ * the assembly's config in and hands `ConfigurationError` a fix hint on the
+ * way out. A future `kelpie` CLI turns this into a subcommand and the body
+ * stays the same size.
  */
 
-function report(message: string): void {
-  process.stdout.write(`${message}\n`)
-}
-
 function reportFatal(message: string): void {
   process.stderr.write(`${message}\n`)
 }
 
-async function reseal(): Promise<number> {
-  const config = loadConfig(process.env)
-  const logger = createLogger(config.logLevel)
-  const database = connectDatabase(config.databaseUrl, logger)
-
-  // Validated here rather than trusted, so a mistyped key fails before the pass
-  // opens a single row instead of reporting every row unreadable.
-  const secretConfig = secretEncryptionConfigSchema.safeParse(process.env)
-
-  if (!secretConfig.success) {
-    await database.close()
-
-    throw new ConfigurationError(
-      secretConfig.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`),
-    )
-  }
-
-  const hasPrevious =
-    secretConfig.data.SECRET_ENCRYPTION_KEY_PREVIOUS !== undefined &&
-    secretConfig.data.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.')
-  }
-
-  try {
-    const outcome = await resealStoredSecrets(database.db, createSecretCipher(secretConfig.data))
-
-    for (const column of outcome.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 (outcome.unreadable > 0) {
-      reportFatal(
-        `\n${String(outcome.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(
-      outcome.resealed === 0
-        ? `\nNothing to do: all ${String(outcome.examined)} value(s) are already sealed under the current key.`
-        : `\nRe-sealed ${String(outcome.resealed)} of ${String(outcome.examined)} value(s). You can now remove SECRET_ENCRYPTION_KEY_PREVIOUS.`,
-    )
-
-    return 0
-  } finally {
-    await database.close()
-  }
-}
-
 try {
-  process.exit(await reseal())
+  const config = resolveKelpieConfig(kelpieConfig, process.env)
+  const logger = createLogger({
+    level: config.logging.level,
+    transports: config.logging.destinations.map(createTransportForDestination),
+  })
+  process.exit(await runReseal({ config, logger }))
 } catch (error: unknown) {
   if (error instanceof ConfigurationError) {
     reportFatal(error.message)

package/templates/src/server.ts

@@ -7,22 +7,22 @@ import {
   WebBundleError,
   connectDatabase,
   createApp,
-  createEmailSender,
   createEventBus,
   createIdFactory,
   createLogger,
   createTransactionScope,
-  loadConfig,
+  createTransportForDestination,
   readModuleConfigFile,
   registerModules,
   resolveActorFrom,
   resolveClientIpFrom,
+  resolveKelpieConfig,
   runMigrations,
   serveWebBundle,
 } from '@kelpie/server'
 import type { CredentialDependencies } from '@kelpie/server'
 
-import { modules } from '../kelpie.config.ts'
+import kelpieConfig from '../kelpie.config.ts'
 
 /**
  * The entry point. It reads the environment, registers the configured modules,
@@ -41,27 +41,36 @@ function reportFatal(message: string): void {
 }
 
 async function start(): Promise<void> {
-  const config = loadConfig(process.env)
-  const logger = createLogger(config.logLevel)
+  const config = resolveKelpieConfig(kelpieConfig, process.env)
+  const logger = createLogger({
+    level: config.logging.level,
+    transports: config.logging.destinations.map(createTransportForDestination),
+  })
   const database = connectDatabase(config.databaseUrl, logger)
   const events = createEventBus(logger)
   const createId = createIdFactory()
   const credentials: CredentialDependencies = { db: database.db, now: () => new Date() }
   const moduleConfig = readModuleConfigFile(config.moduleConfigPath)
   const contributions = await registerModules({
-    modules,
-    environment: process.env,
+    modules: kelpieConfig.modules,
+    environment: config.env,
     logger,
     events,
     moduleConfig,
     resolveActor: (context) => resolveActorFrom(credentials, context),
     services: {
       db: database.db,
-      transaction: createTransactionScope({ db: database.db, bus: events, logger }),
-      email: createEmailSender(config.email, logger),
+      transaction: createTransactionScope({ db: database.db, bus: events, logger, createId }),
       createId,
       now: () => new Date(),
+      appBaseUrl: config.appBaseUrl,
+      secretEncryption: config.secretEncryption,
     },
+    // `provider` picks a named sender from the runtime's registry. `'log'` is
+    // built in; `'smtp'` is registered by the built-in `smtp-email` core
+    // module; other names come from third-party provider modules listed in
+    // `kelpie.config.ts`. `from` is the address on every outgoing message.
+    email: { provider: config.email.EMAIL_PROVIDER, from: config.email.EMAIL_FROM },
   })
 
   if (process.argv.includes('--no-migrate')) {