@kelpie/server 0.1.0

package/src/modules/webhooks/service.ts

@@ -0,0 +1,347 @@
+import { WEBHOOK_SECRET_OVERLAP_HOURS } from '@kelpie/schemas'
+import type { WebhookEvent, WebhookSettableStatus, WebhookStatus } from '@kelpie/schemas'
+
+import { changedKeys } from '../../lib/changes.ts'
+import type { Database } from '../../lib/database.ts'
+import { AppError } from '../../lib/errors.ts'
+import type { IdFactory } from '../../lib/ids.ts'
+import { mapPage, readListWindow, toPage } from '../../lib/pagination.ts'
+import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
+import type { SecretCipher } from '../../lib/secrets.ts'
+import { generateToken } from '../../lib/tokens.ts'
+import type { TransactionScope } from '../../runtime/transaction.ts'
+import type { Actor } from '../auth/actor.ts'
+import { requireWorkspaceId } from '../auth/actor.ts'
+import { roleAllows } from '../workspace/roles.ts'
+import * as repository from './repository.ts'
+import {
+  DEFAULT_DELIVERY_SORT,
+  DEFAULT_WEBHOOK_SORT,
+  DELIVERY_SORTS,
+  WEBHOOK_SORTS,
+} from './repository.ts'
+import type {
+  DeliveryFilters,
+  DeliveryRecord,
+  WebhookFilters,
+  WebhookRecord,
+} from './repository.ts'
+
+/**
+ * Webhook registration.
+ *
+ * Every verb needs the admin role, including the reads. A webhook URL routinely
+ * carries its own credential in the path — `hooks.slack.com/services/T…/B…/…`
+ * is the common case — so listing registrations is disclosing a secret, not
+ * describing a setting. That puts this alongside API keys rather than alongside
+ * the team list any member may read.
+ */
+
+/** `whsec_` is what a leak scanner greps for, so it lives in the secret itself. */
+const SECRET_PREFIX = 'whsec_'
+
+const SECRET_OVERLAP_MS = WEBHOOK_SECRET_OVERLAP_HOURS * 60 * 60 * 1000
+
+export interface WebhooksDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly cipher: SecretCipher
+  /** Injected only so tests can pin secrets. Production uses the crypto default. */
+  readonly newToken?: () => string
+}
+
+/** A webhook as the API returns one: never the secret, never the tenancy column. */
+export interface WebhookView {
+  readonly id: string
+  readonly url: string
+  readonly events: readonly WebhookEvent[]
+  readonly secretPrefix: string
+  readonly status: WebhookStatus
+  readonly lastDeliveryAt: Date | null
+  readonly lastDeliveryStatus: DeliveryRecord['status'] | null
+  readonly createdAt: Date
+  readonly updatedAt: Date
+}
+
+/** The one response that carries the signing secret. Nothing retrieves it later. */
+export interface CreatedWebhookView extends WebhookView {
+  readonly secret: string
+}
+
+export type DeliveryView = Omit<DeliveryRecord, 'workspaceId'>
+
+export interface CreateWebhookInput {
+  readonly url: string
+  readonly events: readonly WebhookEvent[]
+}
+
+export interface UpdateWebhookInput {
+  readonly url?: string | undefined
+  readonly events?: readonly WebhookEvent[] | undefined
+  readonly status?: WebhookSettableStatus | undefined
+}
+
+export interface RotateSecretInput {
+  /**
+   * Keep signing under the old secret for `SECRET_OVERLAP_HOURS` as well.
+   *
+   * Off by default, which replaces the secret at once and means deliveries fail
+   * until the endpoint is redeployed. On, a receiver holding either secret
+   * verifies, so nothing fails while the customer rolls the new one out.
+   */
+  readonly overlap: boolean
+}
+
+export interface WebhooksService {
+  list(actor: Actor, filters: WebhookFilters, query: ListQueryParameters): Promise<Page<WebhookView>>
+  get(actor: Actor, id: string): Promise<WebhookView>
+  create(actor: Actor, input: CreateWebhookInput): Promise<CreatedWebhookView>
+  update(actor: Actor, id: string, changes: UpdateWebhookInput): Promise<WebhookView>
+  /** Mints a replacement signing secret, answering with it exactly once. */
+  rotateSecret(actor: Actor, id: string, input: RotateSecretInput): Promise<CreatedWebhookView>
+  remove(actor: Actor, id: string): Promise<void>
+  listDeliveries(
+    actor: Actor,
+    webhookId: string,
+    filters: DeliveryFilters,
+    query: ListQueryParameters,
+  ): Promise<Page<DeliveryView>>
+}
+
+/**
+ * Mints a signing secret and the prefix stored beside it.
+ *
+ * The prefix shows the trailing characters rather than the leading ones, the
+ * same shape an API key's `display_prefix` has: two registrations are told
+ * apart by their ends, and the start of every secret is identical anyway.
+ */
+function mintSecret(randomToken: () => string): { secret: string; secretPrefix: string } {
+  const secret = `${SECRET_PREFIX}${randomToken()}`
+
+  return { secret, secretPrefix: `${SECRET_PREFIX}…${secret.slice(-4)}` }
+}
+
+export function createWebhooksService(dependencies: WebhooksDependencies): WebhooksService {
+  const newToken = dependencies.newToken ?? generateToken
+
+  /**
+   * 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.
+   */
+  function requireAdmin(actor: Actor): void {
+    if (actor.role === null || !roleAllows(actor.role, 'admin')) {
+      throw new AppError('forbidden', 'This action needs the admin role')
+    }
+  }
+
+  /** The workspace this actor administers, or a refusal. */
+  function requireAdminWorkspace(actor: Actor): string {
+    const workspaceId = requireWorkspaceId(actor)
+
+    requireAdmin(actor)
+
+    return workspaceId
+  }
+
+  async function require(workspaceId: string, id: string): Promise<WebhookRecord> {
+    const webhook = await repository.findWebhook(dependencies.db, workspaceId, id)
+
+    // A webhook in another workspace is indistinguishable from one that never
+    // existed, per `api.md`.
+    if (webhook === undefined) {
+      throw AppError.notFound('Webhook not found')
+    }
+
+    return webhook
+  }
+
+  async function toViews(records: readonly WebhookRecord[]): Promise<WebhookView[]> {
+    const lastDeliveries = await repository.findLastDeliveries(
+      dependencies.db,
+      records.map((record) => record.id),
+    )
+
+    return records.map((record) => {
+      const last = lastDeliveries.get(record.id)
+
+      return {
+        id: record.id,
+        url: record.url,
+        events: record.events,
+        secretPrefix: record.secretPrefix,
+        status: record.status,
+        lastDeliveryAt: last?.at ?? null,
+        lastDeliveryStatus: last?.status ?? null,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+      }
+    })
+  }
+
+  async function toView(record: WebhookRecord): Promise<WebhookView> {
+    const [view] = await toViews([record])
+
+    if (view === undefined) {
+      throw new Error(`Rendering webhook ${record.id} produced no view`)
+    }
+
+    return view
+  }
+
+  function toDeliveryView(record: DeliveryRecord): DeliveryView {
+    const { workspaceId: _workspaceId, ...view } = record
+
+    return view
+  }
+
+  return {
+    async list(actor, filters, query) {
+      const workspaceId = requireAdminWorkspace(actor)
+      const window = readListWindow(query, WEBHOOK_SORTS, DEFAULT_WEBHOOK_SORT)
+      const rows = await repository.listWebhooks(dependencies.db, workspaceId, filters, window)
+      const page = toPage(rows, window, (webhook) => webhook.id)
+
+      return { items: await toViews(page.items), nextCursor: page.nextCursor }
+    },
+
+    async get(actor, id) {
+      return toView(await require(requireAdminWorkspace(actor), id))
+    },
+
+    async create(actor, input) {
+      const workspaceId = requireAdminWorkspace(actor)
+      const { secret, secretPrefix } = mintSecret(newToken)
+      const id = dependencies.createId('webhook')
+
+      const created = await dependencies.transaction(({ tx }) =>
+        repository.insertWebhook(tx, {
+          id,
+          workspaceId,
+          url: input.url,
+          events: [...input.events],
+          secretEncrypted: dependencies.cipher.seal(secret),
+          secretPrefix,
+          status: 'active',
+        }),
+      )
+
+      // The only time the secret leaves this process. Nothing stores it.
+      return { ...(await toView(created)), secret }
+    },
+
+    async update(actor, id, changes) {
+      const workspaceId = requireAdminWorkspace(actor)
+      const existing = await require(workspaceId, id)
+
+      const columns: Partial<repository.WebhookColumns> = {
+        ...(changes.url === undefined ? {} : { url: changes.url }),
+        ...(changes.events === undefined ? {} : { events: [...changes.events] }),
+        ...(changes.status === undefined ? {} : { status: changes.status }),
+      }
+
+      // A PATCH that changes nothing is not a write. Bumping `updated_at` for
+      // it would make the registration look freshly touched, and that field is
+      // what a customer reads against `last_delivery_at` to tell whether a fix
+      // has been tried yet.
+      if (changedKeys(existing, columns).length === 0) {
+        return toView(existing)
+      }
+
+      const updated = await dependencies.transaction(async ({ tx }) => {
+        const row = await repository.updateWebhook(tx, workspaceId, id, {
+          ...columns,
+          updatedAt: dependencies.now(),
+        })
+
+        if (row === undefined) {
+          throw AppError.notFound('Webhook not found')
+        }
+
+        return row
+      })
+
+      return toView(updated)
+    },
+
+    /**
+     * The registration keeps its id, its subscriptions and its delivery log.
+     * Only the secret moves, which is the whole point: deleting and re-creating
+     * loses the log and forces the customer to re-subscribe.
+     *
+     * The status is left alone. A hook is `failing` because the engine found it
+     * failing, and rotating does not fix the endpoint; the next delivery is what
+     * decides whether it recovered.
+     */
+    async rotateSecret(actor, id, input) {
+      const workspaceId = requireAdminWorkspace(actor)
+      const existing = await require(workspaceId, id)
+      const { secret, secretPrefix } = mintSecret(newToken)
+      const now = dependencies.now()
+
+      const rotated = await dependencies.transaction(async ({ tx }) => {
+        const row = await repository.updateWebhook(tx, workspaceId, id, {
+          secretEncrypted: dependencies.cipher.seal(secret),
+          secretPrefix,
+          // The outgoing ciphertext is carried across as it is. It is already
+          // sealed under the current SECRET_ENCRYPTION_KEY, so re-sealing it
+          // would only spend a fresh IV to store the same plaintext.
+          //
+          // Without an overlap both columns are cleared, which is also what
+          // discards the previous secret from an earlier overlapping rotation
+          // rather than leaving its ciphertext at rest indefinitely.
+          previousSecretEncrypted: input.overlap ? existing.secretEncrypted : null,
+          previousSecretExpiresAt: input.overlap
+            ? new Date(now.getTime() + SECRET_OVERLAP_MS)
+            : null,
+          updatedAt: now,
+        })
+
+        if (row === undefined) {
+          throw AppError.notFound('Webhook not found')
+        }
+
+        return row
+      })
+
+      // The only time the new secret leaves this process. Nothing stores it.
+      return { ...(await toView(rotated)), secret }
+    },
+
+    async remove(actor, id) {
+      const workspaceId = requireAdminWorkspace(actor)
+
+      // No event of its own. The catalog has nothing for a webhook changing,
+      // and a hook that has just been deleted cannot be told about it anyway.
+      await dependencies.transaction(async ({ tx }) => {
+        await require(workspaceId, id)
+        await repository.deleteWebhook(tx, workspaceId, id)
+      })
+    },
+
+    async listDeliveries(actor, webhookId, filters, query) {
+      const workspaceId = requireAdminWorkspace(actor)
+
+      // Unlike a filtered CRM list, a missing parent here is a 404 rather than
+      // an empty page: the path names the webhook, so there is no list to be
+      // empty if it does not exist.
+      await require(workspaceId, webhookId)
+
+      const window = readListWindow(query, DELIVERY_SORTS, DEFAULT_DELIVERY_SORT)
+      const rows = await repository.listDeliveries(
+        dependencies.db,
+        workspaceId,
+        webhookId,
+        filters,
+        window,
+      )
+
+      return mapPage(
+        toPage(rows, window, (delivery) => delivery.id),
+        toDeliveryView,
+      )
+    },
+  }
+}

package/src/modules/webhooks/signing.ts

@@ -0,0 +1,95 @@
+import { createHmac } from 'node:crypto'
+
+import type { WebhookEvent } from './payloads.ts'
+
+/**
+ * What goes on the wire, and the signature over it.
+ *
+ * The body is rendered once and everything downstream uses that exact string:
+ * `api.md` computes the signature over the raw body, so re-serialising before
+ * sending would produce a signature for text the receiver never saw.
+ */
+
+/** `api.md` fixes this name and the `sha256=` prefix. */
+export const SIGNATURE_HEADER = 'Kelpie-Signature'
+
+/**
+ * Not in `api.md`, and both earn their place. Delivery is at-least-once, so a
+ * receiver needs a stable key to recognise a repeat; and reading the event name
+ * off a header lets one route the request before parsing the body.
+ */
+export const DELIVERY_HEADER = 'Kelpie-Delivery'
+export const EVENT_HEADER = 'Kelpie-Event'
+
+export interface DeliveryEnvelope {
+  readonly deliveryId: string
+  readonly event: WebhookEvent
+  readonly sentAt: Date
+  /**
+   * Included even though `api.md` keeps the workspace implicit everywhere else.
+   * A REST caller's workspace comes from its credential; a receiver has no
+   * credential, and two workspaces may point their webhooks at one endpoint.
+   */
+  readonly workspaceId: string
+  readonly data: Record<string, unknown>
+}
+
+/** The delivery body as an object, for storing in the log alongside the text sent. */
+export function deliveryBody(envelope: DeliveryEnvelope): Record<string, unknown> {
+  return {
+    id: envelope.deliveryId,
+    event: envelope.event,
+    created_at: envelope.sentAt.toISOString(),
+    workspace_id: envelope.workspaceId,
+    data: envelope.data,
+  }
+}
+
+/** @returns The exact JSON text to send and to sign. */
+export function renderDeliveryBody(body: Record<string, unknown>): string {
+  return JSON.stringify(body)
+}
+
+/**
+ * @param secret The plaintext signing secret, as the receiver holds it.
+ * @returns `sha256=<hex>`, one value of `Kelpie-Signature`.
+ */
+export function signDeliveryBody(secret: string, body: string): string {
+  return `sha256=${createHmac('sha256', secret).update(body, 'utf8').digest('hex')}`
+}
+
+/**
+ * Joins one or more signatures into the header value.
+ *
+ * A rotation with an overlap window signs under both the new secret and the old
+ * one, so an endpoint that has not been redeployed yet still finds a value it
+ * can verify. `api.md` therefore tells a receiver to split on `,` and accept if
+ * **any** value matches, rather than comparing the header to one expected
+ * string.
+ *
+ * That instruction has to hold outside a rotation too, which is why this is the
+ * only way the header is ever built. A receiver that compares the whole header
+ * would work perfectly until the first rotation and fail during it, which is
+ * precisely when a customer can least afford a surprise. One signature renders
+ * identically to the single value the header has always carried, so saying so
+ * costs nothing today and is what makes the overlap work at all.
+ */
+export function joinSignatures(signatures: readonly string[]): string {
+  if (signatures.length === 0) {
+    throw new Error('A delivery must carry at least one signature')
+  }
+
+  return signatures.join(',')
+}
+
+export function deliveryHeaders(
+  envelope: DeliveryEnvelope,
+  signatures: readonly string[],
+): Readonly<Record<string, string>> {
+  return {
+    'Content-Type': 'application/json',
+    [SIGNATURE_HEADER]: joinSignatures(signatures),
+    [DELIVERY_HEADER]: envelope.deliveryId,
+    [EVENT_HEADER]: envelope.event,
+  }
+}

package/src/modules/webhooks/tools.ts

@@ -0,0 +1,108 @@
+import { WEBHOOK_DELIVERY_STATUSES, WEBHOOK_STATUSES } from '@kelpie/schemas'
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { deleteResult, idArg, listWindowShape, pageResult, toListQuery } from '../crudTools.ts'
+import {
+  createBody,
+  createdWebhookResponse,
+  deliveryResponse,
+  rotateBody,
+  updateBody,
+  webhookResponse,
+} from './routes.ts'
+import type { WebhooksService } from './service.ts'
+
+/**
+ * `webhooks_*` and `webhook_deliveries_list`.
+ *
+ * Written out rather than built by `registerCrudTools`, because two of these
+ * answer with a secret the caller may never read again. The generic renderer
+ * would drop it, and a create whose secret went missing is a registration nobody
+ * can verify a delivery from.
+ */
+
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  status: z.enum(WEBHOOK_STATUSES).optional().describe('active, paused, or failing.'),
+})
+
+const deliveryListArgs = z.strictObject({
+  ...listWindowShape,
+  webhook_id: idArg.describe('The registration whose deliveries to read.'),
+  status: z.enum(WEBHOOK_DELIVERY_STATUSES).optional(),
+})
+
+export function registerWebhooksTools(mcp: McpToolRegistry, service: WebhooksService): void {
+  mcp.tool({
+    name: 'webhooks_list',
+    description: 'List this workspace\'s webhook registrations. Mirrors GET /v1/webhooks.',
+    inputSchema: listArgs,
+    invoke: async (args, actor) =>
+      pageResult(await service.list(actor, { status: args.status }, toListQuery(args)), webhookResponse),
+  })
+
+  mcp.tool({
+    name: 'webhooks_get',
+    description: 'Fetch one webhook registration. Mirrors GET /v1/webhooks/{id}.',
+    inputSchema: z.strictObject({ id: idArg }),
+    invoke: async ({ id }, actor) => webhookResponse(await service.get(actor, id)),
+  })
+
+  mcp.tool({
+    name: 'webhooks_create',
+    description:
+      'Register an endpoint for record.created, record.updated, record.deleted or ' +
+      'form.submitted. The reply carries the signing secret once and never again: hand it ' +
+      'to whoever runs the receiver. Admin only. Mirrors POST /v1/webhooks.',
+    inputSchema: createBody,
+    invoke: async (body, actor) =>
+      createdWebhookResponse(await service.create(actor, { url: body.url, events: body.events })),
+  })
+
+  mcp.tool({
+    name: 'webhooks_update',
+    description:
+      'Change a registration\'s url, events, or status. status takes active or paused; ' +
+      'failing is what delivery reports, not something to assert. Admin only. ' +
+      'Mirrors PATCH /v1/webhooks/{id}.',
+    inputSchema: updateBody.extend({ id: idArg }),
+    invoke: async ({ id, ...changes }, actor) => webhookResponse(await service.update(actor, id, changes)),
+  })
+
+  mcp.tool({
+    name: 'webhooks_rotate_secret',
+    description:
+      'Mint a replacement signing secret, answered once. overlap false retires the old one ' +
+      'at once, which is what a leak calls for; true keeps signing under both for 24 hours ' +
+      'so an un-redeployed receiver still verifies. Admin only. ' +
+      'Mirrors POST /v1/webhooks/{id}/rotate_secret.',
+    inputSchema: rotateBody.extend({ id: idArg }),
+    invoke: async ({ id, overlap }, actor) =>
+      createdWebhookResponse(await service.rotateSecret(actor, id, { overlap: overlap ?? false })),
+  })
+
+  mcp.tool({
+    name: 'webhooks_delete',
+    description: 'Remove a registration and its delivery log. Admin only. Mirrors DELETE /v1/webhooks/{id}.',
+    inputSchema: z.strictObject({ id: idArg }),
+    invoke: async ({ id }, actor) => {
+      await service.remove(actor, id)
+
+      return deleteResult(id)
+    },
+  })
+
+  mcp.tool({
+    name: 'webhook_deliveries_list',
+    description:
+      'Recent delivery attempts for one registration, for working out why a receiver is not ' +
+      'hearing them. Keeps 30 days by default. Mirrors GET /v1/webhooks/{id}/deliveries.',
+    inputSchema: deliveryListArgs,
+    invoke: async (args, actor) =>
+      pageResult(
+        await service.listDeliveries(actor, args.webhook_id, { status: args.status }, toListQuery(args)),
+        deliveryResponse,
+      ),
+  })
+}

package/src/modules/webhooks/url.ts

@@ -0,0 +1,21 @@
+import { endpointUrlProblem } from '../../lib/url.ts'
+import type { UrlProblem } from '../../lib/url.ts'
+
+/**
+ * What counts as a delivery target. The shared rules live in `lib/url.ts`;
+ * this binds the one webhook-specific part, the credentials advice.
+ */
+
+export type { UrlProblem } from '../../lib/url.ts'
+export { DELIVERABLE_PROTOCOLS } from '../../lib/url.ts'
+
+export function urlProblem(value: string): UrlProblem | undefined {
+  return endpointUrlProblem(
+    value,
+    'Remove the credentials from the URL; deliveries are signed instead',
+  )
+}
+
+export function isDeliverableUrl(value: string): boolean {
+  return urlProblem(value) === undefined
+}

package/src/modules/workspace/capabilities.ts

@@ -0,0 +1,14 @@
+import type { LimitCapability } from '../../runtime/entitlements.ts'
+
+/**
+ * Capabilities the workspace module declares.
+ *
+ * A capability is a name plus what kind of answer it takes. Services reference
+ * these constants rather than the string, so a typo is a compile error.
+ */
+
+export const SEATS_LIMIT: LimitCapability = {
+  name: 'seats.limit',
+  kind: 'limit',
+  description: 'How many people can belong to one workspace. Unlimited in open source.',
+}