@kelpie/server 0.1.0

package/src/modules/agent-tasks/wire.ts

@@ -0,0 +1,61 @@
+import type { AgentTaskTargetType } from '@kelpie/schemas'
+
+/**
+ * The resolved-task wire shape, in its own file because it has two consumers:
+ * the resolve route renders it as a response, and the dispatch engine POSTs it
+ * to a registered agent. One renderer is what keeps Copy and Run identical,
+ * which `agent-tasks.md` makes the whole point of resolve.
+ */
+
+export interface ContextPackView {
+  readonly targetLabel: string
+  readonly deepLink: string
+  readonly handbookSlugs: readonly string[]
+  readonly pinnedNoteIds: readonly string[]
+  readonly openPlanIds: readonly string[]
+  readonly openDecisionIds: readonly string[]
+  readonly related: Readonly<Record<string, readonly string[]>>
+}
+
+export interface ResolvedTaskView {
+  readonly taskId: string
+  readonly targetType: AgentTaskTargetType
+  readonly targetId: string
+  readonly prompt: string
+  readonly context: ContextPackView
+}
+
+export function resolvedTaskResponse(resolved: ResolvedTaskView): Record<string, unknown> {
+  return {
+    task_id: resolved.taskId,
+    target_type: resolved.targetType,
+    target_id: resolved.targetId,
+    prompt: resolved.prompt,
+    context: {
+      target_label: resolved.context.targetLabel,
+      deep_link: resolved.context.deepLink,
+      handbook_slugs: resolved.context.handbookSlugs,
+      pinned_note_ids: resolved.context.pinnedNoteIds,
+      open_plan_ids: resolved.context.openPlanIds,
+      open_decision_ids: resolved.context.openDecisionIds,
+      related: resolved.context.related,
+    },
+  }
+}
+
+/**
+ * What a registered agent receives. The resolved task plus two fields the
+ * receiver cannot infer: which run this is (the dedupe key, like a webhook's
+ * delivery id) and which workspace it belongs to (a receiver holds no
+ * credential context, and two workspaces can share one endpoint).
+ */
+export function dispatchPayload(
+  run: { readonly id: string; readonly workspaceId: string },
+  resolved: ResolvedTaskView,
+): Record<string, unknown> {
+  return {
+    run_id: run.id,
+    workspace_id: run.workspaceId,
+    ...resolvedTaskResponse(resolved),
+  }
+}

package/src/modules/api-keys/index.ts

@@ -0,0 +1,34 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { mountApiKeyRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createApiKeyService } from './service.ts'
+
+/**
+ * Workspace and personal API keys.
+ *
+ * Every key is bound to one workspace at creation, so there is no workspace
+ * header and no workspace path segment anywhere in the API.
+ */
+export function createApiKeysModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'api-keys',
+    requires: ['workspace'],
+    structural: true,
+
+    register(context) {
+      const service = createApiKeyService({
+        db: context.db,
+        createId: context.createId,
+        now: context.now,
+      })
+
+      context.schema(schema, migrationsDirectory)
+
+      context.routes((router) => {
+        mountApiKeyRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      return Promise.resolve()
+    },
+  }
+}

package/src/modules/api-keys/keys.ts

@@ -0,0 +1,59 @@
+import { generateToken, hashToken } from '../../lib/tokens.ts'
+
+/**
+ * Key formatting. The prefix is what a leak scanner greps for, so it stays in the
+ * secret itself rather than only in the database.
+ */
+
+export const KEY_KINDS = ['workspace', 'personal'] as const
+
+export type KeyKind = (typeof KEY_KINDS)[number]
+
+/** `api.md` pins these strings; they appear in every customer's credential store. */
+const SECRET_PREFIXES: Readonly<Record<KeyKind, string>> = {
+  workspace: 'kp_live_',
+  personal: 'kp_user_',
+}
+
+export interface MintedKey {
+  /** Shown once, at creation, and never retrievable again. */
+  readonly secret: string
+  readonly secretHash: string
+  /** Safe to store and display: prefix plus the last four characters. */
+  readonly displayPrefix: string
+}
+
+export function parseKeyKind(value: string): KeyKind | undefined {
+  return KEY_KINDS.find((kind) => kind === value)
+}
+
+/** The kind a secret claims to be, read from its prefix. */
+export function kindOfSecret(secret: string): KeyKind | undefined {
+  return KEY_KINDS.find((kind) => secret.startsWith(SECRET_PREFIXES[kind]))
+}
+
+export function mintKey(kind: KeyKind, randomToken: () => string = generateToken): MintedKey {
+  const secret = `${SECRET_PREFIXES[kind]}${randomToken()}`
+
+  return {
+    secret,
+    secretHash: hashToken(secret),
+    displayPrefix: `${SECRET_PREFIXES[kind]}…${secret.slice(-4)}`,
+  }
+}
+
+/**
+ * Pulls the credential out of an `Authorization` header.
+ *
+ * @returns The bearer value, or undefined when the header is absent or not a
+ *   bearer scheme. A malformed header is not an error here; the caller decides.
+ */
+export function readBearerToken(header: string | undefined): string | undefined {
+  if (header === undefined) {
+    return undefined
+  }
+
+  const match = /^Bearer\s+(?<token>\S+)$/iu.exec(header)
+
+  return match?.groups?.token
+}

package/src/modules/api-keys/repository.ts

@@ -0,0 +1,82 @@
+import { and, desc, eq, isNotNull, isNull } from 'drizzle-orm'
+
+import type { Database } from '../../lib/database.ts'
+import type { Transaction } from '../../runtime/transaction.ts'
+import { apiKeys } from './schema.ts'
+
+export type Queryable = Database | Transaction
+
+export type ApiKeyRecord = typeof apiKeys.$inferSelect
+
+export async function insertApiKey(
+  db: Queryable,
+  values: typeof apiKeys.$inferInsert,
+): Promise<ApiKeyRecord> {
+  const [created] = await db.insert(apiKeys).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting api key ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function findBySecretHash(
+  db: Queryable,
+  secretHash: string,
+): Promise<ApiKeyRecord | undefined> {
+  const [found] = await db.select().from(apiKeys).where(eq(apiKeys.secretHash, secretHash)).limit(1)
+
+  return found
+}
+
+/** Workspace keys: those with no user behind them. */
+export async function listWorkspaceKeys(db: Queryable, workspaceId: string): Promise<ApiKeyRecord[]> {
+  return db
+    .select()
+    .from(apiKeys)
+    .where(and(eq(apiKeys.workspaceId, workspaceId), isNull(apiKeys.userId)))
+    .orderBy(desc(apiKeys.createdAt))
+}
+
+/** Personal keys belonging to one user in one workspace. */
+export async function listPersonalKeys(
+  db: Queryable,
+  workspaceId: string,
+  userId: string,
+): Promise<ApiKeyRecord[]> {
+  return db
+    .select()
+    .from(apiKeys)
+    .where(
+      and(eq(apiKeys.workspaceId, workspaceId), isNotNull(apiKeys.userId), eq(apiKeys.userId, userId)),
+    )
+    .orderBy(desc(apiKeys.createdAt))
+}
+
+export async function findApiKey(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<ApiKeyRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(apiKeys)
+    .where(and(eq(apiKeys.workspaceId, workspaceId), eq(apiKeys.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function deleteApiKey(db: Queryable, workspaceId: string, id: string): Promise<number> {
+  const deleted = await db
+    .delete(apiKeys)
+    .where(and(eq(apiKeys.workspaceId, workspaceId), eq(apiKeys.id, id)))
+    .returning({ id: apiKeys.id })
+
+  return deleted.length
+}
+
+export async function touchLastUsed(db: Queryable, id: string, now: Date): Promise<void> {
+  await db.update(apiKeys).set({ lastUsedAt: now }).where(eq(apiKeys.id, id))
+}

package/src/modules/api-keys/routes.ts

@@ -0,0 +1,83 @@
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { AppError, toErrorDetails } from '../../lib/errors.ts'
+import type { Actor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import { KEY_KINDS } from './keys.ts'
+import type { ApiKeyService, ApiKeyView, MintedApiKey } from './service.ts'
+
+/** Wire shapes for `/v1/api-keys`. */
+
+const createBody = z.object({
+  name: z.string().min(1),
+  kind: z.enum(KEY_KINDS),
+})
+
+const listQuery = z.object({ kind: z.enum(KEY_KINDS) })
+
+export interface ApiKeyRoutesDependencies extends CredentialDependencies {
+  readonly service: ApiKeyService
+}
+
+async function readBody<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
+}
+
+function keyResponse(key: ApiKeyView): Record<string, unknown> {
+  return {
+    id: key.id,
+    name: key.name,
+    kind: key.kind,
+    display_prefix: key.displayPrefix,
+    last_used_at: key.lastUsedAt === null ? null : key.lastUsedAt.toISOString(),
+    created_at: key.createdAt.toISOString(),
+  }
+}
+
+export function mountApiKeyRoutes(router: Hono, dependencies: ApiKeyRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  /** The response carries `secret`. No later request can retrieve it. */
+  router.post('/api-keys', async (context) => {
+    const body = await readBody(context, createBody)
+    const minted: MintedApiKey = await dependencies.service.create(
+      await requireActor(context),
+      body.name,
+      body.kind,
+    )
+
+    return context.json({ ...keyResponse(minted), secret: minted.secret }, 201)
+  })
+
+  router.get('/api-keys', async (context) => {
+    const parsed = listQuery.safeParse({ kind: context.req.query('kind') })
+
+    if (!parsed.success) {
+      throw AppError.validationFailed(
+        'Specify which keys to list',
+        toErrorDetails(parsed.error.issues),
+      )
+    }
+
+    const keys = await dependencies.service.list(await requireActor(context), parsed.data.kind)
+
+    return context.json({ data: keys.map(keyResponse), next_cursor: null })
+  })
+
+  router.delete('/api-keys/:id', async (context) => {
+    await dependencies.service.revoke(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+}

package/src/modules/api-keys/schema.ts

@@ -0,0 +1,28 @@
+import { index, pgTable, text } from 'drizzle-orm/pg-core'
+
+import { createdAt, moment, primaryId, updatedAt } from '../../lib/columns.ts'
+import { users } from '../auth/schema.ts'
+import { workspaces } from '../workspace/schema.ts'
+
+/**
+ * Both kinds of key are bound to one workspace at creation (`api.md`). A null
+ * `user_id` is a workspace key; a set one is a personal key acting as that user
+ * within that workspace.
+ */
+export const apiKeys = pgTable(
+  'api_keys',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    userId: text('user_id').references(() => users.id, { onDelete: 'cascade' }),
+    name: text('name').notNull(),
+    secretHash: text('secret_hash').notNull().unique(),
+    displayPrefix: text('display_prefix').notNull(),
+    lastUsedAt: moment('last_used_at'),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [index('api_keys_workspace_idx').on(table.workspaceId)],
+)

package/src/modules/api-keys/service.ts

@@ -0,0 +1,152 @@
+import type { Database } from '../../lib/database.ts'
+import { AppError } from '../../lib/errors.ts'
+import type { IdFactory } from '../../lib/ids.ts'
+import type { Actor } from '../auth/actor.ts'
+import { roleAllows } from '../workspace/roles.ts'
+import { mintKey } from './keys.ts'
+import type { KeyKind } from './keys.ts'
+import * as repository from './repository.ts'
+
+/**
+ * API key management.
+ *
+ * A workspace key belongs to the workspace and needs admin authority to create or
+ * revoke. A personal key belongs to one member and is theirs alone: admins can
+ * see that it exists but cannot use or manage it.
+ */
+
+export interface ApiKeyDependencies {
+  readonly db: Database
+  readonly createId: IdFactory
+  readonly now: () => Date
+  /** Injected only so tests can pin secrets. Production uses the crypto default. */
+  readonly newToken?: () => string
+}
+
+export interface ApiKeyView {
+  readonly id: string
+  readonly name: string
+  readonly kind: KeyKind
+  readonly displayPrefix: string
+  readonly lastUsedAt: Date | null
+  readonly createdAt: Date
+}
+
+/** The one response that ever carries the secret. */
+export interface MintedApiKey extends ApiKeyView {
+  readonly secret: string
+}
+
+export interface ApiKeyService {
+  create(actor: Actor, name: string, kind: KeyKind): Promise<MintedApiKey>
+  list(actor: Actor, kind: KeyKind): Promise<readonly ApiKeyView[]>
+  revoke(actor: Actor, id: string): Promise<void>
+}
+
+function toView(record: repository.ApiKeyRecord): ApiKeyView {
+  return {
+    id: record.id,
+    name: record.name,
+    kind: record.userId === null ? 'workspace' : 'personal',
+    displayPrefix: record.displayPrefix,
+    lastUsedAt: record.lastUsedAt,
+    createdAt: record.createdAt,
+  }
+}
+
+export function createApiKeyService(dependencies: ApiKeyDependencies): ApiKeyService {
+  /**
+   * Keys are always workspace-bound, so an actor with no workspace cannot have
+   * any. That is the state between signup and the first workspace create.
+   */
+  function requireWorkspace(actor: Actor): string {
+    if (actor.workspaceId === null) {
+      throw new AppError('forbidden', 'Create a workspace before creating API keys')
+    }
+
+    return actor.workspaceId
+  }
+
+  /**
+   * Reads the role off the actor rather than re-querying the membership.
+   * `credentials.ts` resolves it from the live `workspace_members` row on every
+   * request, so it is already as fresh as a query here would be. A workspace key
+   * has no member row and carries `admin` by definition.
+   *
+   * `role` is null only for a session with no membership, which `requireWorkspace`
+   * has already refused: a session's workspace comes from that same row.
+   */
+  function requireAdmin(actor: Actor): void {
+    if (actor.role === null || !roleAllows(actor.role, 'admin')) {
+      throw new AppError('forbidden', 'This action needs the admin role')
+    }
+  }
+
+  /** A personal key needs a person. A workspace key cannot mint or manage one. */
+  function requireUser(actor: Actor): string {
+    if (actor.userId === null) {
+      throw new AppError('forbidden', 'A personal key belongs to a user, and this caller is not one')
+    }
+
+    return actor.userId
+  }
+
+  return {
+    async create(actor, name, kind) {
+      const workspaceId = requireWorkspace(actor)
+      const userId = kind === 'workspace' ? null : requireUser(actor)
+
+      if (kind === 'workspace') {
+        requireAdmin(actor)
+      }
+
+      const minted = mintKey(kind, dependencies.newToken)
+      const record = await repository.insertApiKey(dependencies.db, {
+        id: dependencies.createId('apiKey'),
+        workspaceId,
+        userId,
+        name,
+        secretHash: minted.secretHash,
+        displayPrefix: minted.displayPrefix,
+      })
+
+      // The only time the secret leaves this process. Nothing stores it.
+      return { ...toView(record), secret: minted.secret }
+    },
+
+    async list(actor, kind) {
+      const workspaceId = requireWorkspace(actor)
+
+      if (kind === 'workspace') {
+        requireAdmin(actor)
+
+        return (await repository.listWorkspaceKeys(dependencies.db, workspaceId)).map(toView)
+      }
+
+      const records = await repository.listPersonalKeys(dependencies.db, workspaceId, requireUser(actor))
+
+      return records.map(toView)
+    },
+
+    async revoke(actor, id) {
+      const workspaceId = requireWorkspace(actor)
+      const record = await repository.findApiKey(dependencies.db, workspaceId, id)
+
+      // A key in another workspace is indistinguishable from one that never
+      // existed, per `api.md`.
+      if (record === undefined) {
+        throw AppError.notFound('API key not found')
+      }
+
+      if (record.userId === null) {
+        requireAdmin(actor)
+      } else if (record.userId !== actor.userId) {
+        // An admin can see a colleague's personal key exists but cannot revoke it;
+        // removing their membership is how you cut off their access.
+        throw AppError.notFound('API key not found')
+      }
+
+      await repository.deleteApiKey(dependencies.db, workspaceId, id)
+    },
+  }
+}

package/src/modules/attachedRecords.ts

@@ -0,0 +1,85 @@
+import { PIPELINE_KINDS } from '@kelpie/schemas'
+import type { PipelineKind } from '@kelpie/schemas'
+import { and, eq } from 'drizzle-orm'
+
+import type { Queryable } from '../runtime/transaction.ts'
+import * as activityRepository from './activities/repository.ts'
+import * as decisionRepository from './decisions/repository.ts'
+import { candidates } from './hiring/schema.ts'
+import * as noteRepository from './notes/repository.ts'
+import * as planRepository from './plans/repository.ts'
+
+/**
+ * The polymorphic delete rule from `schema.md`, in one place.
+ *
+ * Notes, activities and decisions attach to a target through `target_type` plus
+ * `target_id` with no foreign key, so no cascade removes them. Whoever deletes
+ * the target deletes these, in the same transaction, or the rows outlive the
+ * record they described and reappear the day an id is reused.
+ *
+ * `plan_items` attach the same way but their check constraint allows only the
+ * four pipeline types, so they are removed only for those targets.
+ */
+
+/** Target types that can own attached records here. */
+export type AttachableTargetType = 'person' | 'company' | 'candidate' | PipelineKind
+
+const PLAN_TARGET_TYPES: ReadonlySet<string> = new Set(PIPELINE_KINDS)
+
+/**
+ * @param db Must be the caller's transaction. Called on its own, this deletes the
+ *   dependents of a record that still exists.
+ * @returns How many rows were removed, for the caller's activity trail.
+ */
+export async function deleteRecordsAttachedTo(
+  db: Queryable,
+  workspaceId: string,
+  targetType: AttachableTargetType,
+  targetId: string,
+): Promise<number> {
+  // Sequential, not concurrent: a transaction is one connection, and four
+  // statements racing down it is not something to rely on for a cheap delete.
+  const notes = await noteRepository.deleteForTarget(db, workspaceId, targetType, targetId)
+  const activities = await activityRepository.deleteForTarget(db, workspaceId, targetType, targetId)
+  const decisions = await decisionRepository.deleteForTarget(db, workspaceId, targetType, targetId)
+  const plans = PLAN_TARGET_TYPES.has(targetType)
+    ? await planRepository.deleteForTarget(db, workspaceId, targetType, targetId)
+    : 0
+
+  return notes + activities + decisions + plans
+}
+
+/**
+ * The same cleanup for the candidacies a person's delete takes with them.
+ *
+ * `candidates.person_id` cascades, so those rows go without any service seeing
+ * them, and the interview notes attached to each would outlive the candidacy
+ * they described. This is the only link in the schema that both dies by cascade
+ * and owns attached records, which is why it is the only one with a helper here.
+ *
+ * Reads the `candidates` *table* rather than the hiring repository: the module
+ * that owns those rows registers after `people`, and `architecture.md` allows a
+ * table read where a repository import would invert the dependency.
+ *
+ * @param db Must be the caller's transaction, so a refused person delete brings
+ *   these rows back with it.
+ * @returns How many attached rows were removed.
+ */
+export async function deleteRecordsAttachedToCandidaciesOf(
+  db: Queryable,
+  workspaceId: string,
+  personId: string,
+): Promise<number> {
+  const held = await db
+    .select({ id: candidates.id })
+    .from(candidates)
+    .where(and(eq(candidates.workspaceId, workspaceId), eq(candidates.personId, personId)))
+
+  let removed = 0
+
+  for (const candidacy of held) {
+    removed += await deleteRecordsAttachedTo(db, workspaceId, 'candidate', candidacy.id)
+  }
+
+  return removed
+}

package/src/modules/auth/actor.ts

@@ -0,0 +1,17 @@
+/**
+ * The actor a module reads its caller through.
+ *
+ * The definitions moved to `lib/actor.ts` so the module runtime can name the type
+ * without importing a feature module: an MCP tool is handed its caller exactly as
+ * a route handler is (`runtime/module.ts`). Auth remains where an actor is
+ * resolved from credentials, which is why modules still import it from here.
+ */
+
+export {
+  actorMemberId,
+  actorUserId,
+  actorWorkspaceId,
+  requireSessionActor,
+  requireWorkspaceId,
+} from '../../lib/actor.ts'
+export type { Actor, ApiKeyActor, SessionActor } from '../../lib/actor.ts'