@kelpie/server 0.1.0

package/src/lib/http.ts

@@ -0,0 +1,109 @@
+import type { Context } from 'hono'
+import type { z } from 'zod'
+
+import { AppError, toErrorDetails } from './errors.ts'
+import type { ListQueryParameters, Page } from './pagination.ts'
+
+/** The parsing every route repeats: read the wire, reject it, or hand back a typed value. */
+
+/**
+ * Where unauthenticated routes mount (`architecture.md` boot step 5).
+ *
+ * Shared because two places need to agree on it: the app mounts the public
+ * routers here, and a module that builds an absolute URL to one of its own
+ * public endpoints has to spell the same prefix.
+ */
+export const PUBLIC_ROUTE_PREFIX = '/v1/public'
+
+/**
+ * The scheme and host a request arrived on.
+ *
+ * Used to build absolute URLs a customer pastes into their own site. It follows
+ * the request rather than configuration, so it is right wherever the service is
+ * reached from and needs no new environment variable. Behind a proxy it is only
+ * right if that proxy preserves the external `Host`, which is the same condition
+ * every redirect and cookie domain already depends on.
+ */
+export function requestOrigin(context: Context): string {
+  return new URL(context.req.url).origin
+}
+
+/**
+ * Reads and validates a JSON request body.
+ *
+ * @throws AppError 400 when the body is not JSON at all, 422 when it is JSON the
+ *   schema refuses. The two are different client mistakes and `api.md` gives them
+ *   different statuses.
+ */
+export async function readJsonBody<T>(context: Context, schema: z.ZodType<T>): Promise<T> {
+  const raw: unknown = await context.req.json().catch(() => {
+    throw new AppError('bad_request', 'Body must be valid JSON')
+  })
+  const parsed = schema.safeParse(raw)
+
+  if (!parsed.success) {
+    throw AppError.validationFailed('Request body is invalid', toErrorDetails(parsed.error.issues))
+  }
+
+  return parsed.data
+}
+
+/** Lifts `?limit=`, `?sort=` and `?cursor=` off a request. Validated where the sort fields are known. */
+export function readListParameters(context: Context): ListQueryParameters {
+  return {
+    limit: context.req.query('limit'),
+    sort: context.req.query('sort'),
+    cursor: context.req.query('cursor'),
+  }
+}
+
+/**
+ * The most ids one filter may name, matching the `?limit=` ceiling in `api.md`.
+ *
+ * The two are the same number on purpose. A caller resolving a page of records
+ * asks about at most one page of ids, so a filter that allowed fewer would make
+ * the maximum page size unusable, and one that allowed more would invite a query
+ * no page could have produced.
+ */
+export const MAX_FILTER_IDS = 200
+
+/**
+ * Reads an id filter that may be given more than once: `?person_id=a&person_id=b`.
+ *
+ * Repeated parameters rather than a comma-separated list, because an id needs no
+ * escaping this way and there is no separator to get wrong. One occurrence is
+ * the ordinary case and reads the same as it always did.
+ *
+ * @returns The ids, or undefined when the parameter is absent.
+ * @throws AppError 422 for a blank value or more than `MAX_FILTER_IDS` of them.
+ *   Silently dropping either would answer a different question than the one asked.
+ */
+export function readIdFilter(context: Context, name: string): readonly string[] | undefined {
+  const values = context.req.queries(name)
+
+  if (values === undefined || values.length === 0) {
+    return undefined
+  }
+
+  if (values.some((value) => value.length === 0)) {
+    throw AppError.validationFailed(`"${name}" cannot be blank`, [
+      { field: name, message: 'Expected an id' },
+    ])
+  }
+
+  if (values.length > MAX_FILTER_IDS) {
+    throw AppError.validationFailed(`"${name}" takes at most ${String(MAX_FILTER_IDS)} ids`, [
+      { field: name, message: `Given ${String(values.length)}` },
+    ])
+  }
+
+  return values
+}
+
+/** The `{ data, next_cursor }` envelope from `api.md`. */
+export function pageBody<T>(
+  page: Page<T>,
+  render: (item: T) => Record<string, unknown>,
+): { data: Record<string, unknown>[]; next_cursor: string | null } {
+  return { data: page.items.map(render), next_cursor: page.nextCursor }
+}

package/src/lib/ids.ts

@@ -0,0 +1,61 @@
+import { ulid } from 'ulid'
+
+/**
+ * Identifiers are `<prefix>_<ulid>`. This table is the single source of the
+ * prefixes documented in `api.md`; nothing else may hardcode one.
+ */
+export const idPrefixes = {
+  workspace: 'ws',
+  user: 'usr',
+  session: 'ses',
+  passwordResetToken: 'pwr',
+  teamMember: 'mem',
+  invite: 'inv',
+  apiKey: 'key',
+  person: 'per',
+  company: 'com',
+  position: 'pos',
+  pipelineStage: 'stage',
+  deal: 'deal',
+  opportunity: 'opp',
+  partnership: 'prt',
+  raise: 'rse',
+  role: 'role',
+  candidate: 'cand',
+  planItem: 'plan',
+  decision: 'dec',
+  note: 'note',
+  activity: 'act',
+  handbookPage: 'hb',
+  form: 'form',
+  formField: 'ff',
+  formSubmission: 'sub',
+  webhook: 'wh',
+  /** One settled delivery. `api.md` gained the prefix with the delivery log. */
+  webhookDelivery: 'whd',
+  agentRegistration: 'ag',
+  agentRun: 'run',
+  importJob: 'imp',
+  integrationConnection: 'int',
+  /** Never returns over the wire either: identified by `(workspace_id, module_id)` instead. */
+  moduleSetting: 'mset',
+  /**
+   * `idempotency_keys` has no routes of its own and never returns this id over
+   * the wire, so it is not in `api.md`'s public prefix table. It still comes
+   * from this factory rather than a bare `ulid()` call, so every id in the
+   * database is generated the same, injectable way.
+   */
+  idempotencyKey: 'idem',
+} as const
+
+export type ObjectKind = keyof typeof idPrefixes
+
+export type IdFactory = (kind: ObjectKind) => string
+
+/**
+ * Builds the id factory. The ULID generator is injected so tests can pin ids;
+ * production passes nothing and gets time-ordered ULIDs.
+ */
+export function createIdFactory(generateUlid: () => string = ulid): IdFactory {
+  return (kind: ObjectKind): string => `${idPrefixes[kind]}_${generateUlid()}`
+}

package/src/lib/logger.ts

@@ -0,0 +1,73 @@
+import type { LogLevel } from './config.ts'
+
+/**
+ * Structured logging as JSON lines. The sink is injected so tests capture output
+ * instead of writing to stdout, and so a deployment can redirect it.
+ */
+
+export type LogFields = Readonly<Record<string, unknown>>
+
+export interface Logger {
+  debug(message: string, fields?: LogFields): void
+  info(message: string, fields?: LogFields): void
+  warn(message: string, fields?: LogFields): void
+  error(message: string, fields?: LogFields): void
+  /** Returns a logger that stamps `fields` onto every line, e.g. a request id. */
+  child(fields: LogFields): Logger
+}
+
+export type LogSink = (line: string) => void
+
+const severityByLevel: Readonly<Record<LogLevel, number>> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+}
+
+function writeToStdout(line: string): void {
+  process.stdout.write(`${line}\n`)
+}
+
+/**
+ * @param level Minimum level to emit. Lines below it are dropped.
+ * @param sink Receives one complete JSON line per log call.
+ * @param now Injected so tests get deterministic timestamps.
+ */
+export function createLogger(
+  level: LogLevel,
+  sink: LogSink = writeToStdout,
+  now: () => Date = () => new Date(),
+): Logger {
+  const threshold = severityByLevel[level]
+
+  function build(boundFields: LogFields): Logger {
+    function emit(lineLevel: LogLevel, message: string, fields?: LogFields): void {
+      if (severityByLevel[lineLevel] < threshold) {
+        return
+      }
+      // The envelope is written last so a field called `message`, `level`, or
+      // `time` cannot overwrite it. A colliding field is dropped; a corrupted
+      // envelope would make the whole line untrustworthy.
+      sink(
+        JSON.stringify({
+          ...boundFields,
+          ...fields,
+          time: now().toISOString(),
+          level: lineLevel,
+          message,
+        }),
+      )
+    }
+
+    return {
+      debug: (message, fields) => emit('debug', message, fields),
+      info: (message, fields) => emit('info', message, fields),
+      warn: (message, fields) => emit('warn', message, fields),
+      error: (message, fields) => emit('error', message, fields),
+      child: (fields) => build({ ...boundFields, ...fields }),
+    }
+  }
+
+  return build({})
+}

package/src/lib/moduleConfig.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs'
+
+import { z } from 'zod'
+
+/**
+ * Reads `modules.md`'s deploy-time module override file, the mechanism a
+ * self-hoster uses to lock a module on or off for every workspace the process
+ * serves, ahead of whatever a workspace's own settings screen would otherwise
+ * decide (`runtime/moduleConfig.ts` is where that override wins).
+ *
+ * Shape:
+ * ```json
+ * { "modules": { "raises": false, "hiring": false } }
+ * ```
+ */
+
+const moduleConfigFileSchema = z.object({
+  modules: z.record(z.string(), z.boolean()),
+})
+
+/** Thrown when a configured path exists but does not hold a valid module config file. */
+export class ModuleConfigFileError extends Error {
+  constructor(path: string, reason: string) {
+    super(`${path} is not a valid module config file: ${reason}`)
+    this.name = 'ModuleConfigFileError'
+  }
+}
+
+/**
+ * @param path Absolute or relative path, normally `KELPIE_MODULE_CONFIG_PATH`.
+ *   Undefined when the deployment sets no path, which is the ordinary case: a
+ *   workspace's own settings decide instead.
+ * @returns The module id to enabled map the file declares, or undefined when no
+ *   path was given.
+ * @throws ModuleConfigFileError if a given path cannot be read or parsed.
+ */
+export function readModuleConfigFile(path: string | undefined): Readonly<Record<string, boolean>> | undefined {
+  if (path === undefined) {
+    return undefined
+  }
+
+  let raw: string
+
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch (error: unknown) {
+    throw new ModuleConfigFileError(path, error instanceof Error ? error.message : String(error))
+  }
+
+  let parsed: unknown
+
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error: unknown) {
+    throw new ModuleConfigFileError(path, error instanceof Error ? error.message : String(error))
+  }
+
+  const result = moduleConfigFileSchema.safeParse(parsed)
+
+  if (!result.success) {
+    throw new ModuleConfigFileError(path, result.error.issues.map((issue) => issue.message).join('; '))
+  }
+
+  return result.data.modules
+}

package/src/lib/normalisation.ts

@@ -0,0 +1,36 @@
+/**
+ * Values stored in a normalised form, per `schema.md`. The columns are `citext`
+ * as a second line of defence, so a missed normalisation still compares
+ * correctly rather than creating a duplicate.
+ *
+ * Blank normalises to null rather than to `''`. Both columns are unique within a
+ * workspace, so a stored empty string would make the second record without an
+ * address a 409.
+ */
+
+/** A scheme prefix: `https://`, `mailto:` and anything else shaped like one. */
+const SCHEME = /^[a-z][a-z0-9+.-]*:\/\//u
+
+export function normaliseEmail(raw: string): string | null {
+  const email = raw.trim().toLowerCase()
+
+  return email.length === 0 ? null : email
+}
+
+/**
+ * Reduces a domain to its host: no scheme, no path, no trailing dot.
+ *
+ * Deliberately permissive. This normalises what was given; it does not decide
+ * whether the domain resolves, and a CRM regularly holds a company whose site is
+ * not up yet.
+ */
+export function normaliseDomain(raw: string): string | null {
+  const host = raw
+    .trim()
+    .toLowerCase()
+    .replace(SCHEME, '')
+    .split('/')[0]
+    ?.replace(/\.$/u, '')
+
+  return host === undefined || host.length === 0 ? null : host
+}

package/src/lib/pagination.ts

@@ -0,0 +1,291 @@
+import { asc, desc, sql } from 'drizzle-orm'
+import type { Column, SQL } from 'drizzle-orm'
+import { z } from 'zod'
+
+import { AppError } from './errors.ts'
+
+/**
+ * Cursor pagination from `api.md`: `?limit=` and `?cursor=`, an opaque cursor,
+ * and `{ data, next_cursor }` on the wire.
+ *
+ * The cursor is a keyset rather than an offset. It carries the sort value and id
+ * of the last row on the page, so a page boundary stays put when rows are
+ * inserted or deleted underneath a client. Offsets skip and repeat rows when that
+ * happens, which for a CRM that agents write to is not a rare case.
+ *
+ * A cursor is bound to the sort it was issued under. Reusing one against a
+ * different `?sort=` is a client bug, and it is reported as one rather than
+ * silently paging through a different order.
+ */
+
+export const DEFAULT_PAGE_SIZE = 50
+export const MAX_PAGE_SIZE = 200
+
+/** A field a list may be ordered by, and how its value survives a round trip through a cursor. */
+export interface SortableField<TRecord> {
+  readonly column: Column
+  /** Reads the cursor value out of the last row of a page. */
+  readonly valueOf: (record: TRecord) => string
+  /** Turns that string back into something comparable against the column. */
+  readonly parse: (value: string) => Date | string | number
+}
+
+/** The documented sort fields of one resource, keyed by their wire name. */
+export type SortableFields<TRecord> = Readonly<Record<string, SortableField<TRecord>>>
+
+/** Where the previous page stopped. */
+export interface CursorPosition {
+  readonly value: Date | string | number
+  readonly id: string
+}
+
+export interface ListWindow<TRecord> {
+  /** How many rows the caller asked for. */
+  readonly limit: number
+  /** What to ask the database for: one more than `limit`, to detect a next page. */
+  readonly fetchLimit: number
+  /** The canonical sort spec, `-created_at` style. Cursors are bound to it. */
+  readonly sort: string
+  readonly field: SortableField<TRecord>
+  readonly descending: boolean
+  readonly position: CursorPosition | undefined
+}
+
+export interface Page<TRecord> {
+  readonly items: readonly TRecord[]
+  readonly nextCursor: string | null
+}
+
+export interface ListQueryParameters {
+  readonly limit?: string | undefined
+  readonly sort?: string | undefined
+  readonly cursor?: string | undefined
+}
+
+/** The cursor payload. It is client-supplied, so it is parsed, never trusted. */
+const cursorSchema = z.strictObject({
+  sort: z.string().min(1),
+  value: z.string(),
+  id: z.string().min(1),
+})
+
+function invalidCursor(reason: string): AppError {
+  return AppError.validationFailed('That cursor is not one this API issued', [
+    { field: 'cursor', message: reason },
+  ])
+}
+
+export function textSort<TRecord>(
+  column: Column,
+  valueOf: (record: TRecord) => string,
+): SortableField<TRecord> {
+  return { column, valueOf, parse: (value) => value }
+}
+
+export function integerSort<TRecord>(
+  column: Column,
+  valueOf: (record: TRecord) => number,
+): SortableField<TRecord> {
+  return {
+    column,
+    valueOf: (record) => String(valueOf(record)),
+    parse: (value) => {
+      const parsed = Number(value)
+
+      if (!Number.isInteger(parsed)) {
+        throw invalidCursor('Its position is not a whole number')
+      }
+
+      return parsed
+    },
+  }
+}
+
+export function timestampSort<TRecord>(
+  column: Column,
+  valueOf: (record: TRecord) => Date,
+): SortableField<TRecord> {
+  return {
+    column,
+    valueOf: (record) => valueOf(record).toISOString(),
+    parse: (value) => {
+      const parsed = new Date(value)
+
+      if (Number.isNaN(parsed.getTime())) {
+        throw invalidCursor('Its position is not a timestamp')
+      }
+
+      return parsed
+    },
+  }
+}
+
+function encodeCursor(sort: string, value: string, id: string): string {
+  return Buffer.from(JSON.stringify({ sort, value, id }), 'utf8').toString('base64url')
+}
+
+function decodeCursor(raw: string): z.infer<typeof cursorSchema> {
+  let payload: unknown
+
+  try {
+    payload = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'))
+  } catch {
+    // Base64 and JSON both refuse the same way here: the string did not come
+    // from `encodeCursor`. The client cannot act on which of the two failed.
+    throw invalidCursor('It is not readable')
+  }
+
+  const parsed = cursorSchema.safeParse(payload)
+
+  if (!parsed.success) {
+    throw invalidCursor('It does not carry a position')
+  }
+
+  return parsed.data
+}
+
+/**
+ * Reads `?limit=` against the `api.md` range.
+ *
+ * Exported for the endpoints that take the same parameter without being paged
+ * lists. The dashboard is the case: it caps several embedded lists at once and
+ * issues no cursor, but the ceiling a caller may ask for is the same one.
+ *
+ * @throws AppError 422 for anything but a whole number in range.
+ */
+export function readPageSize(raw: string | undefined): number {
+  if (raw === undefined) {
+    return DEFAULT_PAGE_SIZE
+  }
+
+  const limit = Number(raw)
+
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_PAGE_SIZE) {
+    throw AppError.validationFailed('That page size is out of range', [
+      { field: 'limit', message: `Use a whole number from 1 to ${String(MAX_PAGE_SIZE)}` },
+    ])
+  }
+
+  return limit
+}
+
+/**
+ * Reads `?limit=`, `?sort=` and `?cursor=` into a window a repository can apply.
+ *
+ * @param defaultSort The resource's own default, `-created_at` style. Naming a
+ *   field the resource does not declare is a programming error, not a request
+ *   error, so it throws rather than producing a 422.
+ * @throws AppError 422 for an out-of-range limit, an undocumented sort field, or
+ *   a cursor that is unreadable or belongs to a different sort order.
+ */
+export function readListWindow<TRecord>(
+  query: ListQueryParameters,
+  fields: SortableFields<TRecord>,
+  defaultSort: string,
+): ListWindow<TRecord> {
+  const sort = query.sort ?? defaultSort
+  const descending = sort.startsWith('-')
+  const name = descending ? sort.slice(1) : sort
+  const field = fields[name]
+
+  if (field === undefined) {
+    const documented = Object.keys(fields).sort().join(', ')
+
+    if (query.sort === undefined) {
+      throw new Error(`Default sort "${defaultSort}" is not one of: ${documented}`)
+    }
+
+    throw AppError.validationFailed('That sort field is not available on this resource', [
+      { field: 'sort', message: `Sort by one of: ${documented}` },
+    ])
+  }
+
+  const position = ((): CursorPosition | undefined => {
+    if (query.cursor === undefined) {
+      return undefined
+    }
+
+    const decoded = decodeCursor(query.cursor)
+
+    if (decoded.sort !== sort) {
+      throw invalidCursor(`It was issued for sort=${decoded.sort}`)
+    }
+
+    return { value: field.parse(decoded.value), id: decoded.id }
+  })()
+
+  const limit = readPageSize(query.limit)
+
+  return { limit, fetchLimit: limit + 1, sort, field, descending, position }
+}
+
+/**
+ * The keyset predicate: everything after the cursor's row in the window's order.
+ *
+ * Values go through `sql.param` with their own column as the encoder. A bare
+ * `${value}` in a template reaches the driver unconverted, and postgres.js has no
+ * column to infer from, so a `Date` arrives where it wants a string.
+ *
+ * @returns undefined on the first page, where there is nothing to seek past.
+ */
+export function keysetCondition<TRecord>(
+  window: ListWindow<TRecord>,
+  idColumn: Column,
+): SQL | undefined {
+  if (window.position === undefined) {
+    return undefined
+  }
+
+  const { column } = window.field
+  const after = sql.param(window.position.value, column)
+  const afterId = sql.param(window.position.id, idColumn)
+
+  return window.descending
+    ? sql`(${column} < ${after} or (${column} = ${after} and ${idColumn} < ${afterId}))`
+    : sql`(${column} > ${after} or (${column} = ${after} and ${idColumn} > ${afterId}))`
+}
+
+/**
+ * The ordering, id included. Without the id tiebreak two rows sharing a sort
+ * value could straddle a page boundary in either order, and one of them would be
+ * lost or repeated.
+ */
+export function orderByWindow<TRecord>(window: ListWindow<TRecord>, idColumn: Column): SQL[] {
+  const direction = window.descending ? desc : asc
+
+  return [direction(window.field.column), direction(idColumn)]
+}
+
+/**
+ * Trims the extra row a repository fetched and turns it into a next cursor.
+ *
+ * @param rows Up to `window.fetchLimit` rows, in the window's order.
+ */
+export function toPage<TRecord>(
+  rows: readonly TRecord[],
+  window: ListWindow<TRecord>,
+  idOf: (record: TRecord) => string,
+): Page<TRecord> {
+  if (rows.length < window.fetchLimit) {
+    return { items: rows, nextCursor: null }
+  }
+
+  const items = rows.slice(0, window.limit)
+  const last = items.at(-1)
+
+  if (last === undefined) {
+    throw new Error('unreachable: a full page cannot be empty')
+  }
+
+  return { items, nextCursor: encodeCursor(window.sort, window.field.valueOf(last), idOf(last)) }
+}
+
+/**
+ * Re-shapes the items of a page, leaving the cursor alone.
+ *
+ * A service pages over stored rows and answers with views, and the cursor is
+ * built from the row it came from, not from what the caller is handed back.
+ */
+export function mapPage<TFrom, TTo>(page: Page<TFrom>, render: (item: TFrom) => TTo): Page<TTo> {
+  return { items: page.items.map(render), nextCursor: page.nextCursor }
+}

package/src/lib/passwords.ts

@@ -0,0 +1,56 @@
+import { MINIMUM_PASSWORD_LENGTH } from '@kelpie/schemas'
+import { hash, verify } from '@node-rs/argon2'
+
+/**
+ * Password hashing. Argon2id, the parameters the library defaults to, which
+ * follow the OWASP recommendation at time of writing.
+ *
+ * The algorithm and its parameters are embedded in the hash string, so raising
+ * the cost later does not invalidate existing hashes: they verify with the
+ * parameters they were made with, and `needsRehash` says when to upgrade one.
+ */
+
+/**
+ * Rejected before hashing. Argon2 will happily hash an empty string.
+ *
+ * The number lives in `@kelpie/schemas` because the browser's change-password
+ * form states the rule before submitting, and two copies would be two rules.
+ * Re-exported here so callers keep reading it off the module that enforces it.
+ */
+export { MINIMUM_PASSWORD_LENGTH }
+
+export class WeakPasswordError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'WeakPasswordError'
+  }
+}
+
+/**
+ * @throws WeakPasswordError when the password is too short to be worth hashing.
+ */
+export async function hashPassword(plaintext: string): Promise<string> {
+  if (plaintext.length < MINIMUM_PASSWORD_LENGTH) {
+    throw new WeakPasswordError(`Password must be at least ${MINIMUM_PASSWORD_LENGTH} characters`)
+  }
+
+  return hash(plaintext)
+}
+
+/**
+ * Constant-time within argon2 itself. Returns false rather than throwing on a
+ * malformed stored hash, because a corrupted row must not become a login bypass
+ * or a 500 that distinguishes it from a wrong password.
+ */
+export async function verifyPassword(storedHash: string, plaintext: string): Promise<boolean> {
+  try {
+    return await verify(storedHash, plaintext)
+  } catch {
+    // A hash argon2 cannot parse is not a match. The row is corrupt, not correct.
+    return false
+  }
+}
+
+export function isPasswordStrongEnough(plaintext: string): boolean {
+  return plaintext.length >= MINIMUM_PASSWORD_LENGTH
+}