@kelpie/server 0.1.0

package/migrations/meta/_journal.json

@@ -0,0 +1,118 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1785667075768,
+      "tag": "0000_initial_schema",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1785669418397,
+      "tag": "0001_uneven_lockjaw",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1785724794993,
+      "tag": "0002_neat_madame_web",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1785843956943,
+      "tag": "0003_bright_shockwave",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1785847908978,
+      "tag": "0004_drop_unused_import_columns",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1785847917016,
+      "tag": "0005_import_job_rows",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1785883939645,
+      "tag": "0006_drop_webhook_secret_hash",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1785883949172,
+      "tag": "0007_add_webhook_secret_encrypted",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1785909185173,
+      "tag": "0008_rich_mister_sinister",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1785921217462,
+      "tag": "0009_natural_proemial_gods",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1785921229472,
+      "tag": "0010_fine_brood",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1785982653650,
+      "tag": "0011_add_webhook_previous_secret",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1786255151449,
+      "tag": "0012_idempotency_keys_response_nullable",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1786255151450,
+      "tag": "0013_add_agent_run_failure_reason",
+      "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "7",
+      "when": 1786265590851,
+      "tag": "0014_right_shinko_yamashiro",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1786278323968,
+      "tag": "0015_peaceful_chimera",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@kelpie/server",
+  "version": "0.1.0",
+  "description": "The Kelpie service as a library: module runtime, core CRM modules, REST API, MCP surface, and the shared migration pipeline.",
+  "keywords": [
+    "kelpie",
+    "crm",
+    "hono",
+    "drizzle",
+    "mcp",
+    "agent"
+  ],
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velvet-tiger/kelpie.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/velvet-tiger/kelpie/tree/main/packages/server#readme",
+  "bugs": "https://github.com/velvet-tiger/kelpie/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "migrations"
+  ],
+  "exports": {
+    ".": {
+      "kelpie-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "kelpie-source": "./src/testing/index.ts",
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "db:generate": "node --env-file-if-exists=../../.env --env-file-if-exists=../../.env.local ../../node_modules/drizzle-kit/bin.cjs generate"
+  },
+  "dependencies": {
+    "@kelpie/schemas": "^0.1.0",
+    "@node-rs/argon2": "^2.0.2",
+    "drizzle-orm": "^0.45.2",
+    "hono": "^4.12.32",
+    "postgres": "^3.4.9",
+    "ulid": "^3.0.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "drizzle-kit": "^0.31.10",
+    "vite": "^8.2.0",
+    "vitest": "^4.1.10"
+  }
+}

package/src/app.ts

@@ -0,0 +1,157 @@
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+
+import type { DatabaseProbe } from './lib/database.ts'
+import { AppError, internalErrorBody, toErrorBody } from './lib/errors.ts'
+import { PUBLIC_ROUTE_PREFIX } from './lib/http.ts'
+import { createIdFactory } from './lib/ids.ts'
+import type { IdFactory } from './lib/ids.ts'
+import type { Logger } from './lib/logger.ts'
+import type { CredentialDependencies } from './modules/auth/credentials.ts'
+import { MCP_INSTRUCTIONS, MCP_ROUTE_PREFIX, MCP_SERVER_INFO } from './modules/mcp/index.ts'
+import { createMcpEndpoint } from './modules/mcp/router.ts'
+import { createIdempotencyMiddleware } from './modules/workspace/idempotencyMiddleware.ts'
+import type { ModuleContributions } from './runtime/registry.ts'
+
+/**
+ * Builds the HTTP application. Everything it touches arrives as a dependency, so
+ * the app can be exercised without a database or a listening socket.
+ */
+
+export interface AppDependencies {
+  readonly logger: Logger
+  readonly probeDatabase: () => Promise<DatabaseProbe>
+  /** Produced by the registration pass. Routers mount under `/v1`. */
+  readonly contributions: ModuleContributions
+  /**
+   * What `/mcp` checks a bearer key against. The REST routes resolve their own
+   * actor inside each module; the MCP endpoint is mounted here rather than by a
+   * module, because its tools come from every module and the last of those has to
+   * have registered before the listing exists.
+   */
+  readonly credentials: CredentialDependencies
+  /** Injected so tests can pin the id echoed on responses. */
+  readonly generateRequestId?: () => string
+  /** Injected so tests can pin the ids `idempotencyMiddleware` reserves rows under. */
+  readonly createId?: IdFactory
+}
+
+/** Per-request values the middleware chain sets and handlers read. */
+export interface AppBindings {
+  Variables: {
+    requestId: string
+    logger: Logger
+  }
+}
+
+const REQUEST_ID_HEADER = 'X-Request-Id'
+
+/**
+ * Any origin, because a public endpoint exists to be called from a customer's
+ * own website and Kelpie does not know that site's address.
+ *
+ * `credentials` stays off, which is what keeps this safe: a browser will not
+ * attach the session cookie to these requests, so an embedded form on an
+ * attacker's page cannot borrow a signed-in reader's identity. A public handler
+ * has no `Actor` in any case (`runtime/module.ts`).
+ */
+const PUBLIC_CORS = cors({
+  origin: '*',
+  allowMethods: ['GET', 'POST', 'OPTIONS'],
+  allowHeaders: ['Content-Type'],
+  credentials: false,
+  maxAge: 86_400,
+})
+
+export function createApp(dependencies: AppDependencies): Hono<AppBindings> {
+  const generateRequestId = dependencies.generateRequestId ?? (() => crypto.randomUUID())
+  const createId = dependencies.createId ?? createIdFactory()
+  const app = new Hono<AppBindings>()
+
+  app.use('*', async (context, next) => {
+    const requestId = context.req.header(REQUEST_ID_HEADER) ?? generateRequestId()
+    const logger = dependencies.logger.child({ requestId })
+
+    context.set('requestId', requestId)
+    context.set('logger', logger)
+    context.header(REQUEST_ID_HEADER, requestId)
+
+    const startedAt = performance.now()
+    await next()
+
+    logger.info('request', {
+      method: context.req.method,
+      path: context.req.path,
+      status: context.res.status,
+      durationMs: Math.round(performance.now() - startedAt),
+    })
+  })
+
+  // Every module's `POST` gets this the same way, decided once here rather than
+  // per route (`api.md`). It skips `/v1/public/*` itself — a public request has
+  // no `Actor` to scope a key to — so it is mounted ahead of the public CORS
+  // middleware without conflicting with it.
+  app.use(
+    '/v1/*',
+    createIdempotencyMiddleware({
+      db: dependencies.credentials.db,
+      now: dependencies.credentials.now,
+      createId,
+      credentials: dependencies.credentials,
+      log: dependencies.logger,
+    }),
+  )
+
+  // Public first. `/v1/public/...` cannot collide with a `/v1` route unless a
+  // module names a resource `public`, and mounting in this order means the CORS
+  // middleware is attached before anything can answer under the prefix.
+  app.use(`${PUBLIC_ROUTE_PREFIX}/*`, PUBLIC_CORS)
+
+  for (const { router } of dependencies.contributions.publicRouters) {
+    app.route(PUBLIC_ROUTE_PREFIX, router)
+  }
+
+  for (const { router } of dependencies.contributions.routers) {
+    app.route('/v1', router)
+  }
+
+  const mcp = createMcpEndpoint({
+    ...dependencies.credentials,
+    tools: dependencies.contributions.mcpTools,
+    serverInfo: MCP_SERVER_INFO,
+    instructions: MCP_INSTRUCTIONS,
+    logger: dependencies.logger,
+  })
+
+  app.route(MCP_ROUTE_PREFIX, mcp.transport)
+  app.route('/v1', mcp.catalog)
+
+  app.onError((error, context) => {
+    if (error instanceof AppError) {
+      return context.json(toErrorBody(error), error.status)
+    }
+
+    context.get('logger').error('unhandled error', {
+      method: context.req.method,
+      path: context.req.path,
+      error: error.message,
+      stack: error.stack,
+    })
+    return context.json(internalErrorBody(), 500)
+  })
+
+  app.notFound((context) => context.json(toErrorBody(AppError.notFound()), 404))
+
+  app.get('/healthz', async (context) => {
+    const probe = await dependencies.probeDatabase()
+
+    if (!probe.reachable) {
+      context.get('logger').error('database unreachable', { reason: probe.reason })
+      return context.json({ status: 'degraded', database: 'down' }, 503)
+    }
+
+    return context.json({ status: 'ok', database: 'up' }, 200)
+  })
+
+  return app
+}

package/src/index.ts

@@ -0,0 +1,113 @@
+export { createApp } from './app.ts'
+export type { AppDependencies } from './app.ts'
+
+export { ConfigurationError, loadConfig } from './lib/config.ts'
+export type { Environment, KelpieConfig, LogLevel, RuntimeMode } from './lib/config.ts'
+
+export { ModuleConfigFileError, readModuleConfigFile } from './lib/moduleConfig.ts'
+
+export {
+  FOREIGN_KEY_VIOLATION,
+  RESTRICT_VIOLATION,
+  UNIQUE_VIOLATION,
+  connectDatabase,
+  isReferenceViolation,
+  postgresErrorCode,
+} from './lib/database.ts'
+export type { Database, DatabaseConnection, DatabaseProbe } from './lib/database.ts'
+
+export * as schema from './schema/index.ts'
+
+export { createEmailSender, createLogEmailSender, emailConfigSchema } from './lib/email.ts'
+export type { EmailConfig, EmailMessage, EmailSender } from './lib/email.ts'
+
+export { MINIMUM_PASSWORD_LENGTH, hashPassword, isPasswordStrongEnough, verifyPassword } from './lib/passwords.ts'
+export { generateToken, hashToken, tokenHashesMatch } from './lib/tokens.ts'
+
+export {
+  SecretDecryptionError,
+  createSecretCipher,
+  secretEncryptionConfigSchema,
+} from './lib/secrets.ts'
+export type { SecretCipher, SecretEncryptionConfig } from './lib/secrets.ts'
+
+export {
+  AppError,
+  describeThrown,
+  describeValidationIssue,
+  internalErrorBody,
+  toErrorBody,
+  toErrorDetails,
+} from './lib/errors.ts'
+export type { ErrorBody, ErrorCode, ErrorDetail, ErrorStatus, ValidationIssue } from './lib/errors.ts'
+
+export { createIdFactory, idPrefixes } from './lib/ids.ts'
+export type { IdFactory, ObjectKind } from './lib/ids.ts'
+
+export { createLogger } from './lib/logger.ts'
+export type { LogFields, Logger, LogSink } from './lib/logger.ts'
+
+export type {
+  KelpieModule,
+  McpTool,
+  McpToolDefinition,
+  McpToolRegistry,
+  ModuleCatalogEntry,
+  ModuleContext,
+  SchemaContribution,
+} from './runtime/module.ts'
+
+export { ModuleBootError, orderModules } from './runtime/order.ts'
+
+export { createEntitlementRegistry, limitFor, requireCapability } from './runtime/entitlements.ts'
+export type {
+  Capability,
+  Entitlement,
+  EntitlementRegistry,
+  FlagCapability,
+  GrantProvider,
+  LimitCapability,
+} from './runtime/entitlements.ts'
+
+export { SEATS_LIMIT } from './modules/workspace/capabilities.ts'
+
+export { DOMAIN_EVENT_NAMES, RECORD_OBJECT_TYPES, createEventBus } from './runtime/events.ts'
+export type {
+  DomainEventName,
+  DomainEvents,
+  EventBus,
+  EventHandler,
+  RecordObjectType,
+  StagedObjectType,
+} from './runtime/events.ts'
+
+export { createTransactionScope } from './runtime/transaction.ts'
+export type {
+  BufferedEvents,
+  Transaction,
+  TransactionContext,
+  TransactionScope,
+  TransactionScopeDependencies,
+} from './runtime/transaction.ts'
+
+export { planMigrations, runMigrations } from './runtime/migrate.ts'
+export type { MigrationPlanStep } from './runtime/migrate.ts'
+
+export { coreMigrationsDirectory, coreModules } from './modules/core.ts'
+
+export { resealStoredSecrets } from './modules/reseal.ts'
+export type { ResealColumnOutcome, ResealOutcome } from './modules/reseal.ts'
+
+export { KEY_KINDS, kindOfSecret, mintKey, parseKeyKind, readBearerToken } from './modules/api-keys/keys.ts'
+export type { KeyKind, MintedKey } from './modules/api-keys/keys.ts'
+
+export { registerModules } from './runtime/registry.ts'
+export type { ModuleContributions, ModuleRouter, ModuleRuntimeOptions } from './runtime/registry.ts'
+export type { ModuleServices } from './runtime/module.ts'
+
+export type { Actor, ApiKeyActor, SessionActor } from './modules/auth/actor.ts'
+export { actorUserId, actorWorkspaceId, requireSessionActor } from './modules/auth/actor.ts'
+export { resolveActor, resolveActorFrom } from './modules/auth/credentials.ts'
+export type { CredentialDependencies } from './modules/auth/credentials.ts'
+export { MEMBER_ROLES, INVITABLE_ROLES, parseMemberRole, roleAllows } from './modules/workspace/roles.ts'
+export type { InvitableRole, MemberRole } from './modules/workspace/roles.ts'

package/src/lib/actor.ts

@@ -0,0 +1,99 @@
+import type { MemberRole } from '@kelpie/schemas'
+
+import { AppError } from './errors.ts'
+
+/**
+ * Who is making a request. Resolved from credentials and passed explicitly to
+ * services; nothing reads auth state from a global.
+ *
+ * A union rather than a bag of optional fields, so a handler that needs a signed-in
+ * human cannot silently accept a workspace key that has no user behind it.
+ *
+ * It lives in `lib/` rather than in the auth module because the module runtime has
+ * to name it: an MCP tool receives its caller the same way a route handler does
+ * (`runtime/module.ts`), and `runtime/` must not import a feature module. Auth is
+ * still where an actor is *resolved* (`modules/auth/credentials.ts`), and
+ * `modules/auth/actor.ts` is still where modules read the type from.
+ */
+
+/** A browser session. `workspaceId` is null between signup and the first workspace. */
+export interface SessionActor {
+  readonly kind: 'session'
+  readonly userId: string
+  readonly sessionId: string
+  readonly workspaceId: string | null
+  readonly role: MemberRole | null
+  /** The `workspace_members` row behind this actor. Null when there is no membership. */
+  readonly memberId: string | null
+}
+
+/**
+ * A bearer key, always bound to one workspace at creation (`api.md`).
+ *
+ * `userId` is set for a personal key, which acts as its user, and null for a
+ * workspace key, which acts as the workspace itself.
+ */
+export interface ApiKeyActor {
+  readonly kind: 'api_key'
+  readonly apiKeyId: string
+  readonly userId: string | null
+  readonly workspaceId: string
+  readonly role: MemberRole
+  /** Null for a workspace key: it belongs to the workspace, not to a member. */
+  readonly memberId: string | null
+}
+
+export type Actor = SessionActor | ApiKeyActor
+
+/** The workspace an actor is operating in, or null if a fresh account has none yet. */
+export function actorWorkspaceId(actor: Actor): string | null {
+  return actor.workspaceId
+}
+
+/**
+ * The same thing, for the endpoints that cannot work without one.
+ *
+ * CRM routes carry no workspace path segment and read no workspace header: a key
+ * is bound to its workspace at creation and a session carries its active one
+ * (`api.md`). The only actor without a workspace is an account between signup and
+ * its first workspace create.
+ *
+ * @throws AppError 403 when the actor has no workspace.
+ */
+export function requireWorkspaceId(actor: Actor): string {
+  if (actor.workspaceId === null) {
+    throw new AppError('forbidden', 'Create or join a workspace before using this endpoint')
+  }
+
+  return actor.workspaceId
+}
+
+/**
+ * Narrows to a signed-in human.
+ *
+ * @throws AppError 403 for a key, which has no session to manage and no password
+ *   to change.
+ */
+export function requireSessionActor(actor: Actor): SessionActor {
+  if (actor.kind !== 'session') {
+    throw new AppError('forbidden', 'This endpoint needs a signed-in user, not an API key')
+  }
+
+  return actor
+}
+
+/** The user behind the request, if there is one. A workspace key has none. */
+export function actorUserId(actor: Actor): string | null {
+  return actor.userId
+}
+
+/**
+ * The member row to attribute a write to: a note's author, an activity's actor.
+ *
+ * Null means nobody on the team did this. A workspace key is the case that
+ * reaches here today; an integration writing on the workspace's behalf is the
+ * one the `actor_label` column exists for.
+ */
+export function actorMemberId(actor: Actor): string | null {
+  return actor.memberId
+}

package/src/lib/changes.ts

@@ -0,0 +1,43 @@
+/**
+ * Which fields a PATCH actually changed.
+ *
+ * `record.updated` carries the changed fields, and a consumer that acts on
+ * "summary changed" should not be woken by a request that resent the summary it
+ * already had. A PATCH that changes nothing is also a write worth not doing:
+ * bumping `updated_at` for it would make every record look freshly touched.
+ */
+
+/** Dates compare by instant. Everything else compares by its JSON form, which covers arrays and objects. */
+function sameValue(before: unknown, after: unknown): boolean {
+  if (before instanceof Date && after instanceof Date) {
+    return before.getTime() === after.getTime()
+  }
+
+  return JSON.stringify(before) === JSON.stringify(after)
+}
+
+/**
+ * @param before The stored record.
+ * @param changes Partial by PATCH semantics: an absent key means "leave it", so
+ *   only the keys present here are considered. A key `before` does not carry
+ *   counts as a change, which is what a column added since the row was written
+ *   should look like.
+ */
+export function changedKeys(
+  before: Readonly<Record<string, unknown>>,
+  changes: Readonly<Record<string, unknown>>,
+): readonly string[] {
+  const changed: string[] = []
+
+  for (const [key, value] of Object.entries(changes)) {
+    if (value === undefined) {
+      continue
+    }
+
+    if (!sameValue(before[key], value)) {
+      changed.push(key)
+    }
+  }
+
+  return changed
+}