@kelpie/server 0.1.0

package/src/lib/search.ts

@@ -0,0 +1,29 @@
+import { sql } from 'drizzle-orm'
+import type { Column, SQL } from 'drizzle-orm'
+
+/**
+ * The `?q=` free-text filter from `api.md`: a case-insensitive substring match
+ * over the fields the mockup's `FilterBar` matches for that object.
+ *
+ * Substring matching, not full-text search. A user typing three characters into a
+ * filter box expects to see partial words, which `to_tsquery` will not give them.
+ * Search across resources is its own feature with its own index.
+ */
+
+/** `%`, `_` and `\` steer LIKE. A user typing one means the character, not the pattern. */
+const LIKE_WILDCARDS = /[\\%_]/gu
+
+/** Wraps a search term as a LIKE pattern, escaping anything the user did not mean as a wildcard. */
+export function containsPattern(term: string): string {
+  return `%${term.trim().replace(LIKE_WILDCARDS, (match) => `\\${match}`)}%`
+}
+
+/**
+ * True when any element of a `text[]` column matches the pattern.
+ *
+ * `tags @> '{…}'` would only find whole-tag equality, and the filter box is a
+ * substring filter.
+ */
+export function arrayContainsPattern(column: Column, pattern: string): SQL {
+  return sql`exists (select 1 from unnest(${column}) as element where element ilike ${pattern})`
+}

package/src/lib/secrets.ts

@@ -0,0 +1,223 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
+import { z } from 'zod'
+
+/**
+ * Reversible storage for secrets the service itself has to use again.
+ *
+ * Distinct from `lib/tokens.ts`, and the difference is what a secret is *for*.
+ * A session cookie or an API key is only ever compared against, so it is stored
+ * as a SHA-256 hash and nothing can read it back. A webhook signing secret is
+ * different: `api.md` computes the delivery signature *with* it, and the
+ * receiver holds the plaintext we showed them once, so the service must be able
+ * to produce the same bytes months later. Hashing it would make signing
+ * impossible; storing it bare would put every workspace's signing secret in any
+ * database dump.
+ *
+ * `schema.md` already anticipates this for `agent_registrations.auth_header_encrypted`,
+ * and `modules.md` for integration connection records. They share this module.
+ */
+
+/** AES-256-GCM: authenticated, so a tampered ciphertext fails rather than decodes to noise. */
+const ALGORITHM = 'aes-256-gcm'
+const KEY_BYTES = 32
+/** 96 bits, the size GCM is specified for. A fresh one per seal, never reused. */
+const IV_BYTES = 12
+const TAG_BYTES = 16
+
+/**
+ * Marks the format so a future scheme can be introduced without guessing at
+ * what an existing row holds. Rotation reads the version, not the length.
+ */
+const FORMAT_VERSION = 'v1'
+
+/** Thrown when sealed text cannot be read back: wrong key, or tampered ciphertext. */
+export class SecretDecryptionError extends Error {
+  constructor(reason: string, options?: { cause?: unknown }) {
+    super(`Could not decrypt a stored secret: ${reason}`)
+    this.name = 'SecretDecryptionError'
+
+    if (options?.cause !== undefined) {
+      this.cause = options.cause
+    }
+  }
+}
+
+export interface SecretCipher {
+  /** @returns `v1.<base64url iv>.<base64url tag>.<base64url ciphertext>`, safe to store as text. */
+  seal(plaintext: string): string
+  /**
+   * Reads a stored value, trying the current key and then the previous one.
+   *
+   * @throws SecretDecryptionError when the text is malformed, tampered with, or
+   *   sealed under a key this cipher does not hold.
+   */
+  open(sealed: string): string
+  /**
+   * The same value sealed under the current key, or undefined when it already is.
+   *
+   * This is what makes a re-seal pass idempotent: it is the only way to tell
+   * "readable because it is current" from "readable because the previous key is
+   * still configured", which `open` deliberately hides from everything else.
+   *
+   * @throws SecretDecryptionError when neither key opens it.
+   */
+  reseal(sealed: string): string | undefined
+}
+
+const KEY_MESSAGE = `must be ${String(KEY_BYTES)} bytes of base64, e.g. from: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`
+
+/**
+ * The environment slice a module needs to build a cipher. Modules validate it
+ * through `context.config`, so a missing or malformed key stops boot with the
+ * module named rather than failing on the first delivery attempt.
+ */
+export const secretEncryptionConfigSchema = z.object({
+  SECRET_ENCRYPTION_KEY: z
+    .string()
+    .refine((value) => decodeKey(value) !== undefined, { message: KEY_MESSAGE }),
+
+  /**
+   * The key being rotated away from. Optional, and only set while a rotation is
+   * in progress: `open` falls back to it, so the service keeps signing
+   * deliveries between the moment the new key is deployed and the moment
+   * `npm run reseal` finishes. Remove it once that pass reports nothing left.
+   *
+   * Blank counts as absent. An operator ending a rotation empties the line far
+   * more often than they delete it, and refusing to boot over that would punish
+   * the tidy step of the procedure.
+   */
+  SECRET_ENCRYPTION_KEY_PREVIOUS: z
+    .string()
+    .refine((value) => isBlank(value) || decodeKey(value) !== undefined, { message: KEY_MESSAGE })
+    .optional(),
+})
+
+function isBlank(value: string): boolean {
+  return value.trim().length === 0
+}
+
+export type SecretEncryptionConfig = z.infer<typeof secretEncryptionConfigSchema>
+
+/** @returns The key bytes, or undefined when the value is not base64 of exactly `KEY_BYTES`. */
+function decodeKey(value: string): Buffer | undefined {
+  // Buffer.from is lenient: it ignores what it cannot decode rather than
+  // throwing, so the length check is the whole validation. A 64-character hex
+  // key decodes to 48 bytes and is rejected here rather than silently truncated.
+  const decoded = Buffer.from(value, 'base64')
+
+  return decoded.length === KEY_BYTES ? decoded : undefined
+}
+
+/**
+ * Builds the cipher from validated configuration.
+ *
+ * @throws Error when the key is not `KEY_BYTES` of base64. Unreachable through
+ *   `secretEncryptionConfigSchema`, which rejects it at boot first.
+ */
+/** A stored value split into its parts, before any key has been tried. */
+interface SealedParts {
+  readonly iv: Buffer
+  readonly tag: Buffer
+  readonly ciphertext: Buffer
+}
+
+/** @throws SecretDecryptionError when the text is not a `v1` sealed value. */
+function parseSealed(sealed: string): SealedParts {
+  const [version, rawIv, rawTag, rawCiphertext] = sealed.split('.')
+
+  if (version !== FORMAT_VERSION || rawIv === undefined || rawTag === undefined || rawCiphertext === undefined) {
+    throw new SecretDecryptionError('the stored value is not in the expected format')
+  }
+
+  const iv = Buffer.from(rawIv, 'base64url')
+  const tag = Buffer.from(rawTag, 'base64url')
+
+  if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) {
+    throw new SecretDecryptionError('the stored value has a malformed header')
+  }
+
+  return { iv, tag, ciphertext: Buffer.from(rawCiphertext, 'base64url') }
+}
+
+/** @returns The plaintext, or undefined when this key is not the one it was sealed with. */
+function openWith(key: Buffer, parts: SealedParts): string | undefined {
+  const decipher = createDecipheriv(ALGORITHM, key, parts.iv)
+  decipher.setAuthTag(parts.tag)
+
+  try {
+    return Buffer.concat([decipher.update(parts.ciphertext), decipher.final()]).toString('utf8')
+  } catch {
+    // GCM raises here when the tag does not match, which means either the wrong
+    // key or a modified row. Undefined rather than a throw because the caller is
+    // working through a list of keys and a miss is expected on all but one.
+    return undefined
+  }
+}
+
+/** @throws Error when the value is not `KEY_BYTES` of base64. */
+function requireKey(name: string, value: string): Buffer {
+  const key = decodeKey(value)
+
+  if (key === undefined) {
+    throw new Error(`${name} must be ${String(KEY_BYTES)} bytes of base64`)
+  }
+
+  return key
+}
+
+export function createSecretCipher(config: SecretEncryptionConfig): SecretCipher {
+  const current = requireKey('SECRET_ENCRYPTION_KEY', config.SECRET_ENCRYPTION_KEY)
+  const previousValue = config.SECRET_ENCRYPTION_KEY_PREVIOUS
+
+  // Blank counts as absent, which is how an operator normally ends a rotation.
+  const previous =
+    previousValue === undefined || isBlank(previousValue)
+      ? undefined
+      : requireKey('SECRET_ENCRYPTION_KEY_PREVIOUS', previousValue)
+
+  /** Current first: the common case is a value that needs no fallback at all. */
+  const keys = previous === undefined ? [current] : [current, previous]
+
+  function seal(plaintext: string): string {
+    const iv = randomBytes(IV_BYTES)
+    const cipher = createCipheriv(ALGORITHM, current, iv)
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])
+
+    return [
+      FORMAT_VERSION,
+      iv.toString('base64url'),
+      cipher.getAuthTag().toString('base64url'),
+      ciphertext.toString('base64url'),
+    ].join('.')
+  }
+
+  function open(sealed: string): string {
+    const parts = parseSealed(sealed)
+
+    for (const key of keys) {
+      const plaintext = openWith(key, parts)
+
+      if (plaintext !== undefined) {
+        return plaintext
+      }
+    }
+
+    throw new SecretDecryptionError(
+      previous === undefined
+        ? 'it was sealed with a different key, or has been altered'
+        : 'neither the current nor the previous key opens it, or it has been altered',
+    )
+  }
+
+  function reseal(sealed: string): string | undefined {
+    if (openWith(current, parseSealed(sealed)) !== undefined) {
+      return undefined
+    }
+
+    // Not readable under the current key, so `open` either finds it under the
+    // previous one or throws, which is exactly the caller's answer either way.
+    return seal(open(sealed))
+  }
+
+  return { seal, open, reseal }
+}

package/src/lib/timezones.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod'
+
+/**
+ * An IANA zone name, checked by asking `Intl` to build a formatter for it.
+ *
+ * A stored zone the platform cannot resolve would throw at render time, in a
+ * component far from the request that accepted it, so the refusal belongs here.
+ *
+ * What `Intl` resolves is wider than the canonical list: it is case-insensitive
+ * and takes legacy aliases, so `australia/sydney` and `Asia/Calcutta` both pass.
+ * The value is stored as it was sent, so nothing downstream may assume a stored
+ * zone is in canonical form. It is also whatever the running Node's ICU knows,
+ * so a self-hosted deployment on a long-stale runtime could refuse a zone a
+ * current browser resolved. Node 24 ships full ICU and knows every zone added
+ * so far.
+ *
+ * This runs on write only, and there is no backfill. Every route that sets a
+ * workspace zone has validated it since the first one shipped, so a stored zone
+ * `dayIn` cannot resolve is corrupt data rather than a row that predates the
+ * check. Refusing the next write hands the correction to whoever is editing it.
+ */
+export const timezoneSchema = z.string().refine(
+  (value) => {
+    try {
+      new Intl.DateTimeFormat('en', { timeZone: value })
+
+      return true
+    } catch {
+      // Only a RangeError for an unknown zone reaches this. Intl throws nothing
+      // else for a well-formed options object.
+      return false
+    }
+  },
+  { message: 'Must be an IANA time zone name, e.g. Australia/Sydney' },
+)
+
+/**
+ * The calendar day it is in `timezone` at the instant `at`, as `YYYY-MM-DD`.
+ *
+ * Overdue is a question about days, not instants, and which day it is depends on
+ * where the workspace is. Reading the server's own clock would put a Melbourne
+ * workspace on yesterday's date for ten hours of every day.
+ *
+ * `en-CA` renders `YYYY-MM-DD` already, so the parts need no reassembling. The
+ * formatter is built per call rather than cached, because the zone varies by
+ * workspace and a cache keyed on it would outlive the request that needed it.
+ *
+ * @throws RangeError when the platform cannot resolve `timezone`. Every write
+ *   path validates against `timezoneSchema`, so one that fails here is corrupt
+ *   data; a 500 naming it is more use than silently answering in UTC.
+ */
+export function dayIn(timezone: string, at: Date): string {
+  return new Intl.DateTimeFormat('en-CA', {
+    timeZone: timezone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).format(at)
+}

package/src/lib/tokens.ts

@@ -0,0 +1,37 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+
+/**
+ * Bearer secrets: session cookies, password reset links, invite links, API keys.
+ *
+ * These are high-entropy random strings, not passwords, so SHA-256 is the right
+ * store. A slow KDF here would buy nothing: there is no dictionary to attack.
+ * Passwords use argon2 (`lib/passwords.ts`); the two must not be confused.
+ */
+
+/** 256 bits. Long enough that guessing is not a threat model. */
+const TOKEN_BYTES = 32
+
+export function generateToken(randomSource: (size: number) => Buffer = randomBytes): string {
+  return randomSource(TOKEN_BYTES).toString('base64url')
+}
+
+export function hashToken(token: string): string {
+  return createHash('sha256').update(token, 'utf8').digest('hex')
+}
+
+/**
+ * Compares two token hashes without leaking their difference through timing.
+ *
+ * Lookups are by hash, so this is for the cases that compare a stored hash to a
+ * freshly computed one rather than querying by it.
+ */
+export function tokenHashesMatch(left: string, right: string): boolean {
+  const leftBytes = Buffer.from(left, 'utf8')
+  const rightBytes = Buffer.from(right, 'utf8')
+
+  if (leftBytes.length !== rightBytes.length) {
+    return false
+  }
+
+  return timingSafeEqual(leftBytes, rightBytes)
+}

package/src/lib/url.ts

@@ -0,0 +1,52 @@
+/**
+ * What counts as an outbound endpoint Kelpie may POST to — webhook deliveries
+ * and agent-task dispatches share the rules.
+ *
+ * Deliberately permissive about *where* it points. A self-hosted Kelpie
+ * legitimately posts to `http://automation.internal:8080`, so there is no
+ * private-address filter here; adding one would break the self-hosted case to
+ * defend a cloud that does not exist yet. Registration is credentialled and the
+ * endpoint is the customer's own, which is what makes that acceptable today. A
+ * hosted deployment needs egress filtering, and it belongs there rather than in
+ * this check.
+ */
+
+export const DELIVERABLE_PROTOCOLS: readonly string[] = ['http:', 'https:']
+
+export interface UrlProblem {
+  readonly message: string
+}
+
+/**
+ * @param credentialsMessage What to tell a caller whose URL embeds credentials.
+ *   Each registration type names its own alternative — a webhook signs its
+ *   deliveries, an agent carries `auth_header` — so the advice is the caller's.
+ * @returns The problem with this URL, or undefined when it can be posted to.
+ *   A message rather than a boolean, so the `422` says which rule was broken.
+ */
+export function endpointUrlProblem(
+  value: string,
+  credentialsMessage: string,
+): UrlProblem | undefined {
+  let parsed: URL
+
+  try {
+    parsed = new URL(value)
+  } catch {
+    // The only thing `new URL` throws for is a string it cannot parse, which is
+    // exactly the answer wanted here.
+    return { message: 'Expected an absolute URL, e.g. https://example.com/hooks/kelpie' }
+  }
+
+  if (!DELIVERABLE_PROTOCOLS.includes(parsed.protocol)) {
+    return { message: 'Expected an http:// or https:// URL' }
+  }
+
+  // Credentials in the URL would be sent on every POST and stored in plaintext
+  // beside it, which is a secret the registration's own mechanism replaces.
+  if (parsed.username.length > 0 || parsed.password.length > 0) {
+    return { message: credentialsMessage }
+  }
+
+  return undefined
+}

package/src/modules/activities/index.ts

@@ -0,0 +1,43 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createActivityRecorder } from './recorder.ts'
+import type { ActivityDraft, ActivityRecorder } from './recorder.ts'
+import { mountActivitiesRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createActivitiesService } from './service.ts'
+import { registerActivitiesTools } from './tools.ts'
+
+/**
+ * Activities: the history every other module writes into.
+ *
+ * This module owns the table and the read side. The write side is the recorder,
+ * which the emitting modules build for themselves from `context.createId` and
+ * `context.now` inside their own `register`. It holds no state, so three
+ * instances of it are three closures over the same two injectables, not three
+ * copies of anything. The alternative was threading one instance through
+ * `core.ts` into every module that emits, or a service locator, and neither is
+ * worth avoiding a stateless factory call.
+ */
+export function createActivitiesModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'activities',
+    requires: ['workspace'],
+    structural: true,
+
+    register(context) {
+      const service = createActivitiesService({ db: context.db })
+
+      context.schema(schema, migrationsDirectory)
+
+      context.routes((router) => {
+        mountActivitiesRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      registerActivitiesTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}
+
+export { createActivityRecorder }
+export type { ActivityDraft, ActivityRecorder }

package/src/modules/activities/recorder.ts

@@ -0,0 +1,108 @@
+import type { IdFactory } from '../../lib/ids.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import type { Actor } from '../auth/actor.ts'
+import { actorMemberId } from '../auth/actor.ts'
+import type { RecordTargetType } from '../recordTargets.ts'
+import * as repository from './repository.ts'
+import type { ActivityKind } from './schema.ts'
+import type { ActivityWording } from './wording.ts'
+
+/**
+ * How a service writes history.
+ *
+ * The write goes through the caller's transaction, not through the event bus.
+ * The bus publishes after commit and its publication is not awaited
+ * (`runtime/events.ts`), which is right for a webhook and wrong for this: an
+ * activity is the record of what happened, so a change that commits while its
+ * activity is lost leaves a timeline that quietly disagrees with the data. Same
+ * transaction means both land or neither does.
+ *
+ * Services take this as a dependency rather than importing the repository, so a
+ * service can be built with a recorder that collects instead of writing.
+ */
+
+/** What happened, minus who did it and when. */
+export interface ActivityDraft extends ActivityWording {
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  readonly kind: ActivityKind
+}
+
+/**
+ * Something that acts on the workspace without being anybody in it.
+ *
+ * A public form submit is the case this exists for: the request carries no
+ * credentials, so there is no `Actor` to resolve and no member to attribute the
+ * row to, but the timeline still has to say where it came from. `kind` keeps it
+ * a discriminated union with `Actor`, whose members are `session` and `api_key`.
+ */
+export interface SystemActor {
+  readonly kind: 'system'
+  /** What the timeline prints in place of a member's name: `Form`, `Gmail`. */
+  readonly label: string
+}
+
+/** Who a timeline row is attributed to. */
+export type ActivityAuthor = Actor | SystemActor
+
+/**
+ * @param workspaceId Passed rather than read off the author. Every caller has
+ *   already resolved it — through `requireWorkspaceId`, or from a form's
+ *   `publicKey` — and reaching for a nullable field here would need a default
+ *   that silently mis-files a row.
+ */
+export type ActivityRecorder = (
+  db: Queryable,
+  workspaceId: string,
+  author: ActivityAuthor,
+  draft: ActivityDraft,
+) => Promise<void>
+
+/**
+ * The display name to show for a workspace key.
+ *
+ * A workspace key belongs to the workspace rather than to a person, so there is
+ * no member row to name. Anything else with no member behind it says so through
+ * a `SystemActor` and its own label.
+ */
+const WORKSPACE_KEY_LABEL = 'API key'
+
+export interface ActivityRecorderDependencies {
+  readonly createId: IdFactory
+  readonly now: () => Date
+}
+
+/** The member row and the fallback label, exactly one of which is set. */
+function attribute(author: ActivityAuthor): {
+  readonly memberId: string | null
+  readonly label: string | null
+} {
+  if (author.kind === 'system') {
+    return { memberId: null, label: author.label }
+  }
+
+  const memberId = actorMemberId(author)
+
+  return { memberId, label: memberId === null ? WORKSPACE_KEY_LABEL : null }
+}
+
+export function createActivityRecorder(
+  dependencies: ActivityRecorderDependencies,
+): ActivityRecorder {
+  return async (db, workspaceId, author, draft) => {
+    const { memberId, label } = attribute(author)
+
+    await repository.insertActivity(db, {
+      id: dependencies.createId('activity'),
+      workspaceId,
+      targetType: draft.targetType,
+      targetId: draft.targetId,
+      kind: draft.kind,
+      actorMemberId: memberId,
+      actorLabel: label,
+      action: draft.action,
+      detail: draft.detail,
+      createdAt: dependencies.now(),
+    })
+  }
+}