@techelusive/nest-auth 0.0.0-stage → 0.2.1

package/dist/features/webhooks/webhook-delivery.worker.js

@@ -0,0 +1,175 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookDeliveryWorker = void 0;
+const common_1 = require("@nestjs/common");
+const network_safety_1 = require("../../common/network-safety.js");
+const constants_1 = require("../../constants.js");
+const entities_1 = require("../../database/entities/index.js");
+const webhook_signature_1 = require("./webhook-signature");
+const webhooks_service_1 = require("./webhooks.service");
+/**
+ * Sends queued webhook deliveries in the background.
+ *
+ * - Runs every few seconds on every server. Each server claims different rows
+ *   (FOR UPDATE SKIP LOCKED), so nothing is sent twice.
+ * - A 2xx response = delivered. Anything else is retried with growing delays
+ *   (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h), then marked failed.
+ * - Redirects are not followed, and the URL is re-checked before every send, so a receiver
+ *   can't later point us at a private address.
+ */
+let WebhookDeliveryWorker = class WebhookDeliveryWorker {
+    webhooks;
+    logger = new common_1.Logger(constants_1.LOG_CONTEXT.webhookDelivery);
+    database;
+    timer;
+    isRunning = false;
+    constructor(options, webhooks) {
+        this.webhooks = webhooks;
+        this.database = options.dataSource;
+    }
+    /**
+     * Starts the timer that sends due deliveries every few seconds.
+     */
+    onApplicationBootstrap() {
+        this.timer = setInterval(() => void this.sendDueDeliveries(), constants_1.WEBHOOK_WORKER_INTERVAL_MS);
+        this.timer.unref(); // Never keeps the process alive on shutdown.
+    }
+    /**
+     * Stops the timer when the app shuts down.
+     */
+    onModuleDestroy() {
+        if (this.timer)
+            clearInterval(this.timer);
+    }
+    /**
+     * One round: claim due deliveries and send them. Public so tests and scripts can call it.
+     * A round is skipped if the previous one is still running. Errors are logged, never thrown.
+     */
+    async sendDueDeliveries() {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        try {
+            const claimedDeliveries = await this.claimDueDeliveries();
+            await Promise.all(claimedDeliveries.map((delivery) => this.sendOne(delivery)));
+        }
+        catch (error) {
+            this.logger.error(`Webhook round failed: ${error.message}`);
+        }
+        finally {
+            this.isRunning = false;
+        }
+    }
+    /**
+     * Takes due rows and pushes their next attempt a little into the future, in one statement.
+     * If this server crashes mid-send, another server picks them up after the claim times out.
+     *
+     * @returns The deliveries this server should send now.
+     */
+    async claimDueDeliveries() {
+        // For UPDATE ... RETURNING, TypeORM's postgres driver returns [rows, affectedRowCount].
+        const [rows] = await this.database.query(`UPDATE auth_webhook_deliveries
+          SET next_attempt_at = now() + make_interval(secs => $1)
+        WHERE id IN (
+          SELECT id FROM auth_webhook_deliveries
+           WHERE status = $3 AND next_attempt_at <= now()
+           ORDER BY next_attempt_at
+           LIMIT $2
+           FOR UPDATE SKIP LOCKED)
+        RETURNING id, webhook_id, event_name, payload, attempt_count`, [constants_1.WEBHOOK_CLAIM_TIMEOUT_SECONDS, constants_1.WEBHOOK_WORKER_BATCH_SIZE, constants_1.WEBHOOK_DELIVERY_STATUS.pending]);
+        return rows.map((row) => Object.assign(new entities_1.WebhookDeliveryEntity(), {
+            id: row.id,
+            webhookId: row.webhook_id,
+            eventName: row.event_name,
+            payload: row.payload,
+            attemptCount: row.attempt_count,
+        }));
+    }
+    /**
+     * Sends one delivery and records what happened. The webhook's URL is checked again first.
+     *
+     * @param delivery - A claimed delivery.
+     */
+    async sendOne(delivery) {
+        const webhook = await this.database.getRepository(entities_1.WebhookEntity).findOne({ where: { id: delivery.webhookId } });
+        if (!webhook || !webhook.isEnabled) {
+            await this.recordOutcome(delivery, { isDelivered: false, isFinal: true, error: constants_1.WEBHOOK_DELIVERY_ERROR.webhookUnavailable });
+            return;
+        }
+        const urlProblem = await (0, network_safety_1.findUrlSafetyProblem)(webhook.url);
+        if (urlProblem) {
+            await this.recordOutcome(delivery, { isDelivered: false, isFinal: false, error: constants_1.WEBHOOK_DELIVERY_ERROR.unsafeUrl(urlProblem) });
+            return;
+        }
+        const body = JSON.stringify({ id: delivery.id, ...delivery.payload });
+        const signingSecret = await this.webhooks.decryptSigningSecret(webhook);
+        try {
+            const response = await fetch(webhook.url, {
+                method: constants_1.HTTP_METHOD.post,
+                redirect: constants_1.FETCH_REDIRECT_MODE_MANUAL,
+                signal: AbortSignal.timeout(constants_1.WEBHOOK_REQUEST_TIMEOUT_MS),
+                headers: {
+                    [constants_1.HTTP_HEADER.contentType]: constants_1.JSON_CONTENT_TYPE,
+                    [constants_1.HTTP_HEADER.outgoingUserAgent]: constants_1.WEBHOOK_USER_AGENT,
+                    [constants_1.WEBHOOK_SIGNATURE_HEADER]: (0, webhook_signature_1.createWebhookSignature)(signingSecret, body),
+                    [constants_1.WEBHOOK_EVENT_HEADER]: delivery.eventName,
+                    [constants_1.WEBHOOK_DELIVERY_ID_HEADER]: delivery.id,
+                },
+                body,
+            });
+            const isDelivered = response.status >= constants_1.SUCCESS_STATUS_RANGE.from && response.status < constants_1.SUCCESS_STATUS_RANGE.toExclusive;
+            await this.recordOutcome(delivery, {
+                isDelivered,
+                isFinal: isDelivered,
+                responseStatus: response.status,
+                error: isDelivered ? null : constants_1.WEBHOOK_DELIVERY_ERROR.httpStatus(response.status),
+            });
+        }
+        catch (error) {
+            await this.recordOutcome(delivery, { isDelivered: false, isFinal: false, error: error.message });
+        }
+    }
+    /**
+     * Saves the result of an attempt and schedules the next retry, or marks the delivery
+     * delivered or failed.
+     *
+     * @param delivery - The delivery that was attempted.
+     * @param outcome - Whether it was delivered, whether to stop retrying, the HTTP status and the error.
+     */
+    async recordOutcome(delivery, outcome) {
+        const attemptCount = delivery.attemptCount + 1;
+        const retryDelaySeconds = constants_1.WEBHOOK_RETRY_DELAYS_SECONDS[attemptCount - 1];
+        const hasRetriesLeft = !outcome.isFinal && retryDelaySeconds !== undefined;
+        await this.database.getRepository(entities_1.WebhookDeliveryEntity).update({ id: delivery.id }, {
+            attemptCount,
+            status: outcome.isDelivered
+                ? constants_1.WEBHOOK_DELIVERY_STATUS.delivered
+                : hasRetriesLeft
+                    ? constants_1.WEBHOOK_DELIVERY_STATUS.pending
+                    : constants_1.WEBHOOK_DELIVERY_STATUS.failed,
+            deliveredAt: outcome.isDelivered ? new Date() : null,
+            lastResponseStatus: outcome.responseStatus ?? null,
+            lastError: outcome.error?.slice(0, constants_1.WEBHOOK_ERROR_MAX_LENGTH) ?? null,
+            nextAttemptAt: hasRetriesLeft ? new Date(Date.now() + retryDelaySeconds * constants_1.SECOND_IN_MILLISECONDS) : new Date(),
+        });
+    }
+};
+exports.WebhookDeliveryWorker = WebhookDeliveryWorker;
+exports.WebhookDeliveryWorker = WebhookDeliveryWorker = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(constants_1.AUTH_OPTIONS_TOKEN)),
+    __metadata("design:paramtypes", [Object, webhooks_service_1.WebhooksService])
+], WebhookDeliveryWorker);
+//# sourceMappingURL=webhook-delivery.worker.js.map

package/dist/features/webhooks/webhook-delivery.worker.js.map

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

package/dist/features/webhooks/webhook-signature.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Webhook signatures, in the same style as Stripe:
+ *
+ *   X-Techelusive-Signature: t=1792600000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
+ *
+ * v1 = HMAC-SHA256(signingSecret, `${t}.${rawRequestBody}`) in hex.
+ * Including the time stops an attacker from replaying an old delivery later.
+ *
+ * @param signingSecret - The webhook's signing secret.
+ * @param rawBody - The exact JSON body being sent.
+ * @param unixTimeSeconds - The signing time; only passed in tests.
+ * @returns The value for the signature header.
+ */
+export declare function createWebhookSignature(signingSecret: string, rawBody: string, unixTimeSeconds?: number): string;
+/**
+ * For the RECEIVING app: checks a delivery is genuine and recent. Exported from the library so
+ * your other services can verify webhooks with one call.
+ *
+ * @param signingSecret - The secret shown when the webhook was created.
+ * @param rawBody - The request body exactly as received (not re-serialized JSON).
+ * @param signatureHeader - The X-Techelusive-Signature header.
+ * @param unixTimeSeconds - The current time; only passed in tests.
+ * @returns True when the signature is valid and the delivery is not too old.
+ * @example
+ * const isGenuine = verifyWebhookSignature(secret, req.rawBody, req.headers['x-techelusive-signature']);
+ * if (!isGenuine) return res.status(400).end();
+ */
+export declare function verifyWebhookSignature(signingSecret: string, rawBody: string, signatureHeader: string | undefined, unixTimeSeconds?: number): boolean;

package/dist/features/webhooks/webhook-signature.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWebhookSignature = createWebhookSignature;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+const node_crypto_1 = require("node:crypto");
+const random_secrets_1 = require("../../common/crypto/random-secrets.js");
+const constants_1 = require("../../constants.js");
+const time_1 = require("../../common/time.js");
+/**
+ * Webhook signatures, in the same style as Stripe:
+ *
+ *   X-Techelusive-Signature: t=1792600000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
+ *
+ * v1 = HMAC-SHA256(signingSecret, `${t}.${rawRequestBody}`) in hex.
+ * Including the time stops an attacker from replaying an old delivery later.
+ *
+ * @param signingSecret - The webhook's signing secret.
+ * @param rawBody - The exact JSON body being sent.
+ * @param unixTimeSeconds - The signing time; only passed in tests.
+ * @returns The value for the signature header.
+ */
+function createWebhookSignature(signingSecret, rawBody, unixTimeSeconds = (0, time_1.currentUnixTimeSeconds)()) {
+    return formatSignatureHeader(unixTimeSeconds, computeSignature(signingSecret, rawBody, unixTimeSeconds));
+}
+/**
+ * For the RECEIVING app: checks a delivery is genuine and recent. Exported from the library so
+ * your other services can verify webhooks with one call.
+ *
+ * @param signingSecret - The secret shown when the webhook was created.
+ * @param rawBody - The request body exactly as received (not re-serialized JSON).
+ * @param signatureHeader - The X-Techelusive-Signature header.
+ * @param unixTimeSeconds - The current time; only passed in tests.
+ * @returns True when the signature is valid and the delivery is not too old.
+ * @example
+ * const isGenuine = verifyWebhookSignature(secret, req.rawBody, req.headers['x-techelusive-signature']);
+ * if (!isGenuine) return res.status(400).end();
+ */
+function verifyWebhookSignature(signingSecret, rawBody, signatureHeader, unixTimeSeconds = (0, time_1.currentUnixTimeSeconds)()) {
+    if (!signatureHeader)
+        return false;
+    const parts = parseSignatureHeader(signatureHeader);
+    const signedAt = Number(parts[constants_1.WEBHOOK_SIGNATURE_FORMAT.timestampKey]);
+    const presentedSignature = parts[constants_1.WEBHOOK_SIGNATURE_FORMAT.signatureKey];
+    if (!Number.isInteger(signedAt) || typeof presentedSignature !== 'string')
+        return false;
+    if (Math.abs(unixTimeSeconds - signedAt) > constants_1.WEBHOOK_SIGNATURE_TOLERANCE_SECONDS)
+        return false;
+    return (0, random_secrets_1.constantTimeEquals)(computeSignature(signingSecret, rawBody, signedAt), presentedSignature);
+}
+/**
+ * HMAC-SHA256 of "<unix time>.<raw body>", in hex.
+ *
+ * @param signingSecret - The webhook's signing secret.
+ * @param rawBody - The exact JSON body.
+ * @param unixTimeSeconds - The signing time.
+ * @returns The signature in hex.
+ */
+function computeSignature(signingSecret, rawBody, unixTimeSeconds) {
+    const signedContent = [String(unixTimeSeconds), rawBody].join(constants_1.WEBHOOK_SIGNATURE_FORMAT.signedContentSeparator);
+    return (0, node_crypto_1.createHmac)(constants_1.HASH_ALGORITHM.sha256, signingSecret).update(signedContent).digest(constants_1.TEXT_ENCODING.hex);
+}
+/**
+ * Builds the header value: "t=1792600000,v1=abc..."
+ *
+ * @param unixTimeSeconds - The signing time.
+ * @param signature - The hex signature.
+ * @returns The header value.
+ */
+function formatSignatureHeader(unixTimeSeconds, signature) {
+    const { timestampKey, signatureKey, keyValueSeparator, partSeparator } = constants_1.WEBHOOK_SIGNATURE_FORMAT;
+    return [timestampKey + keyValueSeparator + unixTimeSeconds, signatureKey + keyValueSeparator + signature].join(partSeparator);
+}
+/**
+ * Splits the header into its parts: "t=1,v1=abc" -> { t: "1", v1: "abc" }
+ *
+ * @param signatureHeader - The header value.
+ * @returns The parts by key.
+ */
+function parseSignatureHeader(signatureHeader) {
+    return Object.fromEntries(signatureHeader.split(constants_1.WEBHOOK_SIGNATURE_FORMAT.partSeparator).map((part) => {
+        const separatorIndex = part.indexOf(constants_1.WEBHOOK_SIGNATURE_FORMAT.keyValueSeparator);
+        return [part.slice(0, separatorIndex).trim(), part.slice(separatorIndex + 1).trim()];
+    }));
+}
+//# sourceMappingURL=webhook-signature.js.map

package/dist/features/webhooks/webhook-signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-signature.js","sourceRoot":"","sources":["../../../src/features/webhooks/webhook-signature.ts"],"names":[],"mappings":";;AAuBA,wDAEC;AAeD,wDAcC;AAtDD,6CAAyC;AACzC,mEAAoE;AACpE,2CAKqB;AACrB,wCAAuD;AAEvD;;;;;;;;;;;;GAYG;AACH,SAAgB,sBAAsB,CAAC,aAAqB,EAAE,OAAe,EAAE,eAAe,GAAG,IAAA,6BAAsB,GAAE;IACvH,OAAO,qBAAqB,CAAC,eAAe,EAAE,gBAAgB,CAAC,aAAa,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;AAC3G,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,sBAAsB,CACpC,aAAqB,EACrB,OAAe,EACf,eAAmC,EACnC,eAAe,GAAG,IAAA,6BAAsB,GAAE;IAE1C,IAAI,CAAC,eAAe;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,KAAK,GAAG,oBAAoB,CAAC,eAAe,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,oCAAwB,CAAC,YAAY,CAAC,CAAC,CAAC;IACtE,MAAM,kBAAkB,GAAG,KAAK,CAAC,oCAAwB,CAAC,YAAY,CAAC,CAAC;IACxE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,OAAO,kBAAkB,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACxF,IAAI,IAAI,CAAC,GAAG,CAAC,eAAe,GAAG,QAAQ,CAAC,GAAG,+CAAmC;QAAE,OAAO,KAAK,CAAC;IAE7F,OAAO,IAAA,mCAAkB,EAAC,gBAAgB,CAAC,aAAa,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,kBAAkB,CAAC,CAAC;AACpG,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,gBAAgB,CAAC,aAAqB,EAAE,OAAe,EAAE,eAAuB;IACvF,MAAM,aAAa,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,oCAAwB,CAAC,sBAAsB,CAAC,CAAC;IAC/G,OAAO,IAAA,wBAAU,EAAC,0BAAc,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,yBAAa,CAAC,GAAG,CAAC,CAAC;AAC1G,CAAC;AAED;;;;;;GAMG;AACH,SAAS,qBAAqB,CAAC,eAAuB,EAAE,SAAiB;IACvE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,GAAG,oCAAwB,CAAC;IAClG,OAAO,CAAC,YAAY,GAAG,iBAAiB,GAAG,eAAe,EAAE,YAAY,GAAG,iBAAiB,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AAChI,CAAC;AAED;;;;;GAKG;AACH,SAAS,oBAAoB,CAAC,eAAuB;IACnD,OAAO,MAAM,CAAC,WAAW,CACvB,eAAe,CAAC,KAAK,CAAC,oCAAwB,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACzE,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,oCAAwB,CAAC,iBAAiB,CAAC,CAAC;QAChF,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACvF,CAAC,CAAC,CACH,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,144 @@
+import { AuthOptions } from '../../auth-options.js';
+import { EncryptionService } from '../../common/encryption.service.js';
+import { WebhookDeliveryEntity, WebhookEntity } from '../../database/entities/index.js';
+export interface WebhookInput {
+    url: string;
+    /** Event names to receive, e.g. ["user.created"]. Empty = every event. */
+    eventNames?: string[];
+    description?: string | null;
+    isEnabled?: boolean;
+}
+/** A webhook as shown to admins. The signing secret is only shown when created or rotated. */
+export type WebhookSummary = Omit<WebhookEntity, 'encryptedSigningSecret'>;
+/**
+ * Admin management of webhooks: URLs that receive auth events as signed HTTP POSTs.
+ * Deliveries themselves are sent by WebhookDeliveryWorker.
+ */
+export declare class WebhooksService {
+    private readonly encryption;
+    private readonly database;
+    constructor(options: AuthOptions, encryption: EncryptionService);
+    /**
+     * Creates a webhook. Returns the signing secret ONCE: the receiver needs it to verify deliveries.
+     *
+     * @param input - URL, event names (empty = every event), description and on/off state.
+     * @returns The webhook and its plain signing secret.
+     * @throws AuthError UNSAFE_WEBHOOK_URL when the URL is not https or points at a private address.
+     * @throws AuthError VALIDATION_ERROR for unknown event names or too many webhooks.
+     */
+    createWebhook(input: WebhookInput): Promise<{
+        success: true;
+        webhook: WebhookSummary;
+        signingSecret: string;
+    }>;
+    /**
+     * Lists every webhook, oldest first.
+     *
+     * @returns The webhooks, without their secrets.
+     */
+    listWebhooks(): Promise<WebhookSummary[]>;
+    /**
+     * Changes a webhook. Fields left undefined are not touched.
+     *
+     * @param webhookId - The webhook.
+     * @param changes - The fields to change.
+     * @returns The updated webhook.
+     * @throws AuthError NOT_FOUND when there is no such webhook.
+     * @throws AuthError UNSAFE_WEBHOOK_URL or VALIDATION_ERROR for a bad URL or event name.
+     */
+    updateWebhook(webhookId: string, changes: Partial<WebhookInput>): Promise<{
+        success: true;
+        webhook: WebhookSummary;
+    }>;
+    /**
+     * Deletes a webhook (its deliveries are deleted with it).
+     *
+     * @param webhookId - The webhook.
+     * @returns `{ success: true }`.
+     * @throws AuthError NOT_FOUND when there is no such webhook.
+     */
+    deleteWebhook(webhookId: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * Replaces the signing secret (e.g. it leaked). The old one stops working at once.
+     *
+     * @param webhookId - The webhook.
+     * @returns The new plain signing secret, shown only this once.
+     * @throws AuthError NOT_FOUND when there is no such webhook.
+     */
+    rotateSigningSecret(webhookId: string): Promise<{
+        success: true;
+        signingSecret: string;
+    }>;
+    /**
+     * Recent deliveries of one webhook, newest first, for debugging a receiver.
+     *
+     * @param webhookId - The webhook.
+     * @param page - 1-based page number.
+     * @param pageSize - Rows per page (capped at MAXIMUM_PAGE_SIZE).
+     * @returns One page of deliveries, plus the total.
+     */
+    listDeliveries(webhookId: string, page?: number, pageSize?: number): Promise<{
+        success: true;
+        deliveries: WebhookDeliveryEntity[];
+        total: number;
+        page: number;
+        pageSize: number;
+    }>;
+    /**
+     * Sends a failed (or any) delivery again, right away, with a fresh set of retries.
+     *
+     * @param webhookId - The webhook the delivery belongs to.
+     * @param deliveryId - The delivery.
+     * @returns `{ success: true }`.
+     * @throws AuthError NOT_FOUND when the delivery doesn't exist for this webhook.
+     */
+    retryDelivery(webhookId: string, deliveryId: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * Queues a "webhook.test" delivery so the receiver can be checked end to end.
+     *
+     * @param webhookId - The webhook.
+     * @returns `{ success: true }`.
+     * @throws AuthError NOT_FOUND when there is no such webhook.
+     */
+    sendTestDelivery(webhookId: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * Reads a webhook's signing secret. Used by the delivery worker.
+     *
+     * @param webhook - The webhook row.
+     * @returns The plain signing secret.
+     */
+    decryptSigningSecret(webhook: WebhookEntity): Promise<string>;
+    /**
+     * @param url - The webhook URL.
+     * @throws AuthError UNSAFE_WEBHOOK_URL (with `problem`) when the server must not call it.
+     */
+    private assertUrlIsSafe;
+    /**
+     * @param eventNames - The event names the admin chose.
+     * @returns The names without duplicates.
+     * @throws AuthError VALIDATION_ERROR listing any names that are not real events.
+     */
+    private validateEventNames;
+    /**
+     * @returns A new random signing secret like "whsec_...".
+     */
+    private createSigningSecret;
+    /**
+     * Binds the encrypted secret to its webhook, so a secret copied to another row won't decrypt.
+     *
+     * @param webhookId - The webhook.
+     * @returns The context for `EncryptionService`.
+     */
+    private encryptionContext;
+    /**
+     * @param webhook - The webhook row.
+     * @returns The webhook without its encrypted secret, safe to show to admins.
+     */
+    private toSummary;
+}