create-kelpie 0.4.0 → 0.5.0

package/README.md

@@ -20,6 +20,7 @@ package.json           @kelpie/server and @kelpie/ui, pinned to this version
 kelpie.config.ts       the server module list
 kelpie.ui.config.ts    the UI module list
 src/server.ts          the entry point: config, modules, migrations, serve
+src/reseal.ts          re-seals stored secrets after a SECRET_ENCRYPTION_KEY change
 web/index.html         the web entry
 web/main.tsx
 vite.config.ts         dev server, proxying /v1 to the API

package/dist/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,wEAAwE;AACxE,qBAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AA2DD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAkBtD;AAED,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,MAAM,EAAE,CAsBpE"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,wEAAwE;AACxE,qBAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AA4DD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAkBtD;AAED,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,MAAM,EAAE,CAsBpE"}

package/dist/scaffold.js

@@ -29,6 +29,7 @@ const TEMPLATE_FILES = new Map([
     ['kelpie.config.ts', 'kelpie.config.ts'],
     ['kelpie.ui.config.ts', 'kelpie.ui.config.ts'],
     ['src/server.ts', 'src/server.ts'],
+    ['src/reseal.ts', 'src/reseal.ts'],
     ['web/index.html', 'web/index.html'],
     ['web/main.tsx', 'web/main.tsx'],
     ['vite.config.ts', 'vite.config.ts'],

package/dist/scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/src/scaffold.ts

@@ -50,6 +50,7 @@ const TEMPLATE_FILES: ReadonlyMap<string, string> = new Map([
   ['kelpie.config.ts', 'kelpie.config.ts'],
   ['kelpie.ui.config.ts', 'kelpie.ui.config.ts'],
   ['src/server.ts', 'src/server.ts'],
+  ['src/reseal.ts', 'src/reseal.ts'],
   ['web/index.html', 'web/index.html'],
   ['web/main.tsx', 'web/main.tsx'],
   ['vite.config.ts', 'vite.config.ts'],

package/templates/README.md

@@ -40,8 +40,10 @@ 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.
 
-Kelpie does not send email yet. Invitation and password-reset links print to the
-API's log. Copy them from there to follow either flow.
+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.
 
 ## Adding a module
 
@@ -51,8 +53,9 @@ on an unknown id or an unmet dependency rather than starting without it.
 
 ## Configuration
 
-Everything below is required unless marked optional. A missing or invalid value
-stops the service at boot and lists every problem at once.
+Everything below is required unless marked optional or conditional on another
+variable's value. A missing or invalid value stops the service at boot and
+lists every problem at once.
 
 | Variable | Values |
 | --- | --- |
@@ -61,9 +64,15 @@ stops the service at boot and lists every problem at once.
 | `API_PORT` | The same number again, for the dev server's proxy |
 | `WEB_PORT` | The Vite dev server's port. Development only |
 | `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`. Writes invitations and resets to the log instead of sending them |
+| `EMAIL_PROVIDER` | `log` or `smtp`. `log` writes invitations and resets to the log instead of sending them |
 | `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 |
 | `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 |
@@ -81,7 +90,8 @@ unreadable, so rotate rather than replace:
    `SECRET_ENCRYPTION_KEY`.
 2. Deploy. New secrets seal under the new key; existing ones still read with the
    previous one.
-3. Re-encrypt everything still under the old key. Safe to run more than once.
+3. Run `npm run reseal`. It rewrites every row still sealed under the old key.
+   Safe to run more than once.
 4. Remove `SECRET_ENCRYPTION_KEY_PREVIOUS` and deploy again.
 
 ## Deploying

package/templates/env

@@ -16,12 +16,27 @@ WEB_PORT=__WEB_PORT__
 
 DATABASE_URL=__DATABASE_URL__
 
+# The address people reach this Kelpie on, used to build the links in emails
+# (verification, password reset, invitations). In development that is the Vite
+# dev server below; a deployment sets its real origin.
+APP_BASE_URL=http://localhost:__WEB_PORT__
+
 # Seals secrets the service reads back, such as webhook signing secrets. This
 # one was generated for this project. Losing it makes those secrets unreadable;
 # 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. Real providers ship as modules.
+# them. `smtp` sends for real, through the server and credentials below.
 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=

package/templates/package.json

@@ -11,6 +11,7 @@
     "dev:api": "node --watch --env-file-if-exists=.env src/server.ts",
     "dev:web": "vite",
     "start": "node --env-file-if-exists=.env src/server.ts",
+    "reseal": "node --env-file-if-exists=.env src/reseal.ts",
     "build": "vite build",
     "typecheck": "tsc --project tsconfig.server.json && tsc --project tsconfig.web.json"
   },

package/templates/src/reseal.ts

@@ -0,0 +1,107 @@
+import {
+  ConfigurationError,
+  connectDatabase,
+  createLogger,
+  createSecretCipher,
+  loadConfig,
+  resealStoredSecrets,
+  secretEncryptionConfigSchema,
+} from '@kelpie/server'
+
+/**
+ * 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.
+ */
+
+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())
+} catch (error: unknown) {
+  if (error instanceof ConfigurationError) {
+    reportFatal(error.message)
+    reportFatal('Set SECRET_ENCRYPTION_KEY, and SECRET_ENCRYPTION_KEY_PREVIOUS if you are mid-rotation.')
+    process.exit(1)
+  }
+
+  throw error
+}

package/templates/src/server.ts

@@ -16,6 +16,7 @@ import {
   readModuleConfigFile,
   registerModules,
   resolveActorFrom,
+  resolveClientIpFrom,
   runMigrations,
   serveWebBundle,
 } from '@kelpie/server'
@@ -76,10 +77,16 @@ async function start(): Promise<void> {
     credentials,
     createId,
     rateLimit: config.rateLimit,
-    // The real socket address. A header-based fallback would be spoofable, so
-    // this is resolved from the connection itself rather than defaulted
-    // inside `createApp`.
-    resolveClientIp: (context) => getConnInfo(context).remote.address ?? 'unknown',
+    // The socket address, then `X-Forwarded-For` only as far as the configured
+    // number of trusted proxies allows. Resolved from the connection itself
+    // rather than defaulted inside `createApp`, and trusting the header any
+    // further than `TRUSTED_PROXY_HOP_COUNT` would be spoofable.
+    resolveClientIp: (context) =>
+      resolveClientIpFrom(
+        getConnInfo(context).remote.address ?? 'unknown',
+        context.req.header('X-Forwarded-For'),
+        config.trustedProxyHopCount,
+      ),
   })
 
   // After `createApp`, so every API route is registered ahead of the fallback.