@kelpie/server 0.1.0

package/dist/modules/webhooks/schema.js

@@ -0,0 +1,61 @@
+import { WEBHOOK_DELIVERY_STATUSES, WEBHOOK_EVENTS, WEBHOOK_STATUSES, } from '@kelpie/schemas';
+import { index, integer, jsonb, pgTable, text } from 'drizzle-orm/pg-core';
+import { checkOneOf, createdAt, moment, primaryId, updatedAt } from '../../lib/columns.js';
+import { workspaces } from '../workspace/schema.js';
+export { WEBHOOK_DELIVERY_STATUSES, WEBHOOK_EVENTS, WEBHOOK_STATUSES };
+/** Outbound HTTP deliveries driven by the internal event bus. */
+export const webhooks = pgTable('webhooks', {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+        .notNull()
+        .references(() => workspaces.id, { onDelete: 'cascade' }),
+    url: text('url').notNull(),
+    events: text('events').array().$type().notNull().default([]),
+    /**
+     * The signing secret, sealed by `lib/secrets.ts`.
+     *
+     * Not a hash, unlike every other secret in the schema, because `api.md`
+     * signs each delivery *with* this secret and the receiver holds the
+     * plaintext we showed them once. A hash could never produce a signature
+     * anything off the shelf can verify.
+     */
+    secretEncrypted: text('secret_encrypted').notNull(),
+    secretPrefix: text('secret_prefix').notNull(),
+    /**
+     * The secret this one replaced, kept only while a rotation overlaps.
+     *
+     * Set when a customer rotates and asks for an overlap window, so a delivery
+     * carries a signature under both secrets and an endpoint that has not been
+     * redeployed yet still verifies. Null the rest of the time, which is every
+     * webhook that has never rotated and every rotation taken immediately.
+     */
+    previousSecretEncrypted: text('previous_secret_encrypted'),
+    /** When the value above stops being signed with. Null together with it. */
+    previousSecretExpiresAt: moment('previous_secret_expires_at'),
+    status: text('status').$type().notNull().default('active'),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+}, (table) => [
+    index('webhooks_workspace_idx').on(table.workspaceId),
+    checkOneOf('webhooks_status_check', table.status, WEBHOOK_STATUSES),
+]);
+/** Append-only delivery log, pruned by retention rather than updated. */
+export const webhookDeliveries = pgTable('webhook_deliveries', {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+        .notNull()
+        .references(() => workspaces.id, { onDelete: 'cascade' }),
+    webhookId: text('webhook_id')
+        .notNull()
+        .references(() => webhooks.id, { onDelete: 'cascade' }),
+    event: text('event').$type().notNull(),
+    payload: jsonb('payload').$type().notNull(),
+    status: text('status').$type().notNull(),
+    attempts: integer('attempts').notNull().default(0),
+    deliveredAt: moment('delivered_at'),
+    createdAt: createdAt(),
+}, (table) => [
+    index('webhook_deliveries_webhook_idx').on(table.webhookId),
+    checkOneOf('webhook_deliveries_status_check', table.status, WEBHOOK_DELIVERY_STATUSES),
+]);
+//# sourceMappingURL=schema.js.map

package/dist/modules/webhooks/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/modules/webhooks/schema.ts"],"names":[],"mappings":"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"}

package/dist/modules/webhooks/service.d.ts

@@ -0,0 +1,65 @@
+import type { WebhookEvent, WebhookSettableStatus, WebhookStatus } from '@kelpie/schemas';
+import type { Database } from '../../lib/database.ts';
+import type { IdFactory } from '../../lib/ids.ts';
+import type { ListQueryParameters, Page } from '../../lib/pagination.ts';
+import type { SecretCipher } from '../../lib/secrets.ts';
+import type { TransactionScope } from '../../runtime/transaction.ts';
+import type { Actor } from '../auth/actor.ts';
+import type { DeliveryFilters, DeliveryRecord, WebhookFilters } from './repository.ts';
+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>>;
+}
+export declare function createWebhooksService(dependencies: WebhooksDependencies): WebhooksService;
+//# sourceMappingURL=service.d.ts.map

package/dist/modules/webhooks/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/modules/webhooks/service.ts"],"names":[],"mappings":"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"}

package/dist/modules/webhooks/service.js

@@ -0,0 +1,202 @@
+import { WEBHOOK_SECRET_OVERLAP_HOURS } from '@kelpie/schemas';
+import { changedKeys } from '../../lib/changes.js';
+import { AppError } from '../../lib/errors.js';
+import { mapPage, readListWindow, toPage } from '../../lib/pagination.js';
+import { generateToken } from '../../lib/tokens.js';
+import { requireWorkspaceId } from '../auth/actor.js';
+import { roleAllows } from '../workspace/roles.js';
+import * as repository from './repository.js';
+import { DEFAULT_DELIVERY_SORT, DEFAULT_WEBHOOK_SORT, DELIVERY_SORTS, WEBHOOK_SORTS, } from './repository.js';
+/**
+ * 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;
+/**
+ * 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) {
+    const secret = `${SECRET_PREFIX}${randomToken()}`;
+    return { secret, secretPrefix: `${SECRET_PREFIX}…${secret.slice(-4)}` };
+}
+export function createWebhooksService(dependencies) {
+    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) {
+        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) {
+        const workspaceId = requireWorkspaceId(actor);
+        requireAdmin(actor);
+        return workspaceId;
+    }
+    async function require(workspaceId, id) {
+        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) {
+        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) {
+        const [view] = await toViews([record]);
+        if (view === undefined) {
+            throw new Error(`Rendering webhook ${record.id} produced no view`);
+        }
+        return view;
+    }
+    function toDeliveryView(record) {
+        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 = {
+                ...(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);
+        },
+    };
+}
+//# sourceMappingURL=service.js.map

package/dist/modules/webhooks/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../src/modules/webhooks/service.ts"],"names":[],"mappings":"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"}

package/dist/modules/webhooks/signing.d.ts

@@ -0,0 +1,57 @@
+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 declare 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 declare const DELIVERY_HEADER = "Kelpie-Delivery";
+export declare 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 declare function deliveryBody(envelope: DeliveryEnvelope): Record<string, unknown>;
+/** @returns The exact JSON text to send and to sign. */
+export declare function renderDeliveryBody(body: Record<string, unknown>): string;
+/**
+ * @param secret The plaintext signing secret, as the receiver holds it.
+ * @returns `sha256=<hex>`, one value of `Kelpie-Signature`.
+ */
+export declare function signDeliveryBody(secret: string, body: string): string;
+/**
+ * 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 declare function joinSignatures(signatures: readonly string[]): string;
+export declare function deliveryHeaders(envelope: DeliveryEnvelope, signatures: readonly string[]): Readonly<Record<string, string>>;
+//# sourceMappingURL=signing.d.ts.map

package/dist/modules/webhooks/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../../../src/modules/webhooks/signing.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD;;;;;;GAMG;AAEH,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,qBAAqB,CAAA;AAElD;;;;GAIG;AACH,eAAO,MAAM,eAAe,oBAAoB,CAAA;AAChD,eAAO,MAAM,YAAY,iBAAiB,CAAA;AAE1C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACvC;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQhF;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAExE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMpE;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,gBAAgB,EAC1B,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAOlC"}

package/dist/modules/webhooks/signing.js

@@ -0,0 +1,69 @@
+import { createHmac } from 'node:crypto';
+/**
+ * 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';
+/** The delivery body as an object, for storing in the log alongside the text sent. */
+export function deliveryBody(envelope) {
+    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) {
+    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, body) {
+    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) {
+    if (signatures.length === 0) {
+        throw new Error('A delivery must carry at least one signature');
+    }
+    return signatures.join(',');
+}
+export function deliveryHeaders(envelope, signatures) {
+    return {
+        'Content-Type': 'application/json',
+        [SIGNATURE_HEADER]: joinSignatures(signatures),
+        [DELIVERY_HEADER]: envelope.deliveryId,
+        [EVENT_HEADER]: envelope.event,
+    };
+}
+//# sourceMappingURL=signing.js.map

package/dist/modules/webhooks/signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.js","sourceRoot":"","sources":["../../../src/modules/webhooks/signing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAIxC;;;;;;GAMG;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAA;AAElD;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAChD,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAA;AAe1C,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,QAA0B;IACrD,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,UAAU;QACvB,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE;QACzC,YAAY,EAAE,QAAQ,CAAC,WAAW;QAClC,IAAI,EAAE,QAAQ,CAAC,IAAI;KACpB,CAAA;AACH,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,kBAAkB,CAAC,IAA6B;IAC9D,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,IAAY;IAC3D,OAAO,UAAU,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;AACpF,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAAC,UAA6B;IAC1D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAA;IACjE,CAAC;IAED,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC7B,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,QAA0B,EAC1B,UAA6B;IAE7B,OAAO;QACL,cAAc,EAAE,kBAAkB;QAClC,CAAC,gBAAgB,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC;QAC9C,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,UAAU;QACtC,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,KAAK;KAC/B,CAAA;AACH,CAAC"}

package/dist/modules/webhooks/tools.d.ts

@@ -0,0 +1,4 @@
+import type { McpToolRegistry } from '../../runtime/module.ts';
+import type { WebhooksService } from './service.ts';
+export declare function registerWebhooksTools(mcp: McpToolRegistry, service: WebhooksService): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/modules/webhooks/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/modules/webhooks/tools.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAU9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAsBnD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAwE1F"}

package/dist/modules/webhooks/tools.js

@@ -0,0 +1,77 @@
+import { WEBHOOK_DELIVERY_STATUSES, WEBHOOK_STATUSES } from '@kelpie/schemas';
+import { z } from 'zod';
+import { deleteResult, idArg, listWindowShape, pageResult, toListQuery } from '../crudTools.js';
+import { createBody, createdWebhookResponse, deliveryResponse, rotateBody, updateBody, webhookResponse, } from './routes.js';
+/**
+ * `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, service) {
+    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),
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/modules/webhooks/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/modules/webhooks/tools.ts"],"names":[],"mappings":"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"}

package/dist/modules/webhooks/url.d.ts

@@ -0,0 +1,10 @@
+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 declare function urlProblem(value: string): UrlProblem | undefined;
+export declare function isDeliverableUrl(value: string): boolean;
+//# sourceMappingURL=url.d.ts.map

package/dist/modules/webhooks/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../../src/modules/webhooks/url.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;;GAGG;AAEH,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAExD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAKhE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvD"}

package/dist/modules/webhooks/url.js

@@ -0,0 +1,9 @@
+import { endpointUrlProblem } from '../../lib/url.js';
+export { DELIVERABLE_PROTOCOLS } from '../../lib/url.js';
+export function urlProblem(value) {
+    return endpointUrlProblem(value, 'Remove the credentials from the URL; deliveries are signed instead');
+}
+export function isDeliverableUrl(value) {
+    return urlProblem(value) === undefined;
+}
+//# sourceMappingURL=url.js.map

package/dist/modules/webhooks/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../../src/modules/webhooks/url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AASrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAExD,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,kBAAkB,CACvB,KAAK,EACL,oEAAoE,CACrE,CAAA;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,UAAU,CAAC,KAAK,CAAC,KAAK,SAAS,CAAA;AACxC,CAAC"}

package/dist/modules/workspace/capabilities.d.ts

@@ -0,0 +1,9 @@
+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 declare const SEATS_LIMIT: LimitCapability;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/modules/workspace/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAEpE;;;;;GAKG;AAEH,eAAO,MAAM,WAAW,EAAE,eAIzB,CAAA"}