@serve.zone/gitops 3.1.1 → 32.1.0

package/dist_ts_interfaces/requests/webhook.d.ts

@@ -1,4 +1,5 @@
 import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
 export interface IReq_WebhookNotification extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_WebhookNotification> {
     method: 'webhookNotification';
     request: {
@@ -11,3 +12,33 @@ export interface IReq_WebhookNotification extends plugins.typedrequestInterfaces
         ok: boolean;
     };
 }
+export interface IReq_GetWebhookSettings extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetWebhookSettings> {
+    method: 'getWebhookSettings';
+    request: {
+        identity: data.IIdentity;
+        connectionId: string;
+    };
+    response: {
+        webhookSettings: data.IWebhookSettings;
+    };
+}
+export interface IReq_RotateWebhookSecret extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RotateWebhookSecret> {
+    method: 'rotateWebhookSecret';
+    request: {
+        identity: data.IIdentity;
+        connectionId: string;
+    };
+    response: {
+        webhookSettings: data.IWebhookSettings;
+    };
+}
+export interface IReq_ConfirmWebhookSecret extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ConfirmWebhookSecret> {
+    method: 'confirmWebhookSecret';
+    request: {
+        identity: data.IIdentity;
+        connectionId: string;
+    };
+    response: {
+        status: data.TWebhookStatus;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/gitops",
-  "version": "3.1.1",
+  "version": "32.1.0",
   "description": "GitOps management app for Gitea and GitLab - manage secrets, browse projects, view CI pipelines, and stream build logs",
   "main": "./dist_ts/index.js",
   "typings": "./dist_ts/index.d.ts",
@@ -34,18 +34,18 @@
     "@push.rocks/smartdata": "7.1.7",
     "@push.rocks/smartguard": "^3.1.0",
     "@push.rocks/smartjwt": "^2.2.2",
-    "@push.rocks/smartmongo": "^7.0.0",
+    "@push.rocks/smartmongo": "9.0.0",
     "@push.rocks/smartsecret": "^1.0.2"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsbundle": "^2.10.4",
-    "@git.zone/tsdeno": "^1.5.0",
-    "@git.zone/tsdocker": "2.4.3",
-    "@git.zone/tsrun": "^2.0.4",
-    "@git.zone/tstest": "^3.6.6",
+    "@git.zone/tsbuild": "^4.5.0",
+    "@git.zone/tsbundle": "^2.13.0",
+    "@git.zone/tsdeno": "^1.8.0",
+    "@git.zone/tsdocker": "^3.6.0",
+    "@git.zone/tsrun": "^2.0.6",
+    "@git.zone/tstest": "6.1.1",
     "@git.zone/tswatch": "^3.3.5",
-    "@types/node": "^25.9.1"
+    "@types/node": "^26.5.1"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -15,7 +15,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - Mirrors repositories from a source connection to a target connection with group offset support, stable source-project mapping for subgroup/path shifts, metadata sync, optional release/asset and OCI image sync, stale target handling, and live sync logs.
 - Manages reusable secret definitions that can be pushed to selected project or group targets.
 - Runs scheduled jobs, currently focused on syncing `readme.md`, `changelog.md`, and `docs/*.md` content into BookStack shelves, books, and pages.
-- Receives provider webhooks at `POST /webhook/:connectionId` and broadcasts events to connected browser clients.
+- Receives provider webhooks at `POST /webhook/:connectionId`, verifies every delivery against the connection's webhook secret, and broadcasts accepted events to connected browser clients.
 
 ## Runtime Shape
 
@@ -78,7 +78,7 @@ import type * as gitopsInterfaces from '@serve.zone/gitops/interfaces';
 | `GITOPS_ADMIN_USERNAME` | `admin` | Dashboard login username. |
 | `GITOPS_ADMIN_PASSWORD` | `admin` | Dashboard login password. |
 
-Provider connections, sync configs, jobs, managed secrets, and action logs are persisted as JSON records below `~/.serve.zone/gitops/storage/`. Cached projects and secrets live in the embedded SmartMongo directory below `~/.serve.zone/gitops/tsmdb/`.
+Provider connections, sync configs, jobs, managed secrets, and action logs are persisted as JSON records below `~/.serve.zone/gitops/storage/`. Cached projects and secrets use a disposable NoSQLDB memory server through SmartMongo 9. The initial provider scan repopulates this cache after startup; it does not persist between processes.
 
 Provider connections may also define `registryUrl`, `registryUsername`, and `registryToken` for OCI registry mirroring. Registry tokens are stored through SmartSecret and masked in API/UI responses. GitLab image sync falls back to `oauth2:<provider token>` when no dedicated registry credentials are configured; Gitea requires an explicit registry username when registry auth is needed.
 
@@ -96,7 +96,64 @@ The backend exposes TypedRequest methods through `/typedrequest` and a custom we
 | Pipelines and Logs | Pipeline listing, jobs, retry/cancel, and raw job log fetches |
 | Sync | Sync config CRUD, preview, trigger, status, logs, optional `syncReleases` and `syncContainerImages` artifact mirroring |
 | Jobs | Scheduled job CRUD, trigger, pause/resume, and logs |
-| Webhooks | `POST /webhook/:connectionId` for provider event fan-out |
+| Webhooks | `POST /webhook/:connectionId` for verified provider event fan-out, plus `getWebhookSettings`, `rotateWebhookSecret`, `confirmWebhookSecret` |
+
+## Webhooks
+
+Every connection carries its own webhook secret. It is minted with the connection (32 random
+bytes, hex) and kept in the same secret store as the provider token — never in the connection
+JSON, never in an API response other than the reveal below.
+
+GitOps does not create webhooks through the provider API, so the secret is transferred by hand:
+
+1. Open **Connections → Webhook** for the connection. The dialog shows the payload URL
+   (`https://<gitops host>/webhook/<connectionId>`), the secret, and the header the provider
+   will use.
+2. In Gitea, create the webhook with that payload URL, content type `application/json`, and the
+   secret in the **Secret** field. Gitea signs each delivery with HMAC-SHA256 over the raw body
+   and sends the hex digest in `X-Gitea-Signature`.
+3. In GitLab, create the webhook with that URL and put the secret into **Secret token**. GitLab
+   echoes it verbatim in `X-Gitlab-Token`.
+4. Back in GitOps choose **Mark Configured**. Until then the connection's webhook status is
+   `unverified` and its deliveries are refused.
+
+**Rotate Secret** mints a new secret and sets the status back to `unverified`, so the previous
+secret stops being accepted immediately.
+
+Connections created before webhook verification existed are loaded with a freshly minted secret
+and the status `unverified`: their provider side still holds no secret, so nothing they deliver
+can be trusted until step 2/3/4 has been done for them.
+
+A refused delivery never triggers a broadcast and is answered with the refusal name:
+
+| Refusal | Status | Meaning |
+| --- | --- | --- |
+| `webhook-connection-unknown` | 404 | no connection with that id |
+| `webhook-connection-unverified` | 401 | the secret has not been confirmed at the provider |
+| `webhook-secret-missing` | 401 | the connection has no webhook secret in the secret store |
+| `webhook-secret-unreadable` | 503 | the secret store holds the secret but did not return it |
+| `webhook-length-missing` | 411 | no parsable `Content-Length` on the delivery |
+| `webhook-signature-missing` | 401 | no `X-Gitea-Signature` / `X-Gitlab-Token` header |
+| `webhook-signature-invalid` | 401 | signature or token does not match the connection secret |
+| `webhook-body-too-large` | 413 | delivery body exceeds 1 MiB |
+| `webhook-body-unreadable` | 400 | the request body could not be read |
+
+The signature is computed over the bytes as received; GitOps never re-serializes the payload
+before hashing it.
+
+Delivery bodies are bounded twice. Gitea and GitLab always declare a `Content-Length`, so a
+delivery without a parsable one is refused as `webhook-length-missing` before its body is
+touched — reading it would mean buffering a stream of unknown size from an unauthenticated
+caller. The declared length itself is only a claim, so the body is then read against a running
+1 MiB budget and a delivery that sends more than it declared is refused the moment the budget
+is crossed, with nothing beyond the bound buffered.
+
+`webhook-secret-unreadable` is the one refusal that is not about the caller: the connection's
+secret is in the secret store but a read of it failed (for example the SmartSecret keyring
+quota). GitOps then refuses the connection's deliveries and leaves the stored secret exactly
+as it is — it never mints a replacement over a secret an operator has already configured at
+the provider. Deliveries resume on their own once the secret store answers again; **Rotate
+Secret** replaces the stored secret deliberately if it really is gone.
 
 ## Auto BookStack Documentation
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/gitops',
-  version: '3.1.1',
+  version: '32.1.0',
   description: 'GitOps management app for Gitea and GitLab - manage secrets, browse projects, view CI pipelines, and stream build logs'
 }

package/ts/cache/classes.cachedb.ts

@@ -8,7 +8,7 @@ export interface ICacheDbOptions {
 }
 
 /**
- * Singleton wrapper around LocalTsmDb + SmartdataDb.
+ * Singleton wrapper around SmartMongo's NoSQLDB memory server and SmartData.
  * Provides a managed MongoDB-compatible cache database.
  */
 export class CacheDb {

package/ts/classes/connectionmanager.ts

@@ -9,6 +9,13 @@ const CONNECTIONS_PREFIX = '/connections/';
 const KEYCHAIN_PREFIX = 'keychain:';
 
 const getRegistryTokenSecretId = (connectionId: string): string => `${connectionId}:registry`;
+const getWebhookSecretId = (connectionId: string): string => `${connectionId}:webhook`;
+
+/**
+ * Mints a webhook secret. 32 random bytes as hex: long enough that a delivery carrying
+ * it proves the sender was configured by us, short enough to paste into a provider UI.
+ */
+const mintWebhookSecret = (): string => plugins.crypto.randomBytes(32).toString('hex');
 
 /**
  * Manages provider connections — persists each connection as an
@@ -112,7 +119,26 @@ export class ConnectionManager {
         } else if (conn.registryToken && conn.registryToken !== '***') {
           await this.migrateRegistryTokenToKeychain(conn);
         }
+        if (conn.webhookSecret?.startsWith(KEYCHAIN_PREFIX)) {
+          const webhookSecretId = conn.webhookSecret.substring(KEYCHAIN_PREFIX.length);
+          const realWebhookSecret = await this.smartSecret.getSecret(webhookSecretId);
+          if (realWebhookSecret) {
+            conn.webhookSecret = realWebhookSecret;
+          } else {
+            // The sentinel proves a secret was stored under this id, so an empty read is a
+            // keychain failure, not a missing secret. Minting a replacement here would
+            // overwrite the operator's confirmed secret under the same id and lose it, so
+            // the connection is flagged instead and its deliveries are refused by name.
+            logger.warn(
+              `Webhook secret for connection ${conn.id} is stored but unreadable — deliveries are ` +
+                'refused until the secret store returns it again; the stored secret is left untouched',
+            );
+            conn.webhookSecret = undefined;
+            conn.webhookSecretUnreadable = true;
+          }
+        }
         this.connections.push(conn);
+        await this.backfillWebhookSecret(conn);
       }
     }
     if (this.connections.length > 0) {
@@ -157,6 +183,30 @@ export class ConnectionManager {
     }
   }
 
+  /**
+   * Connections stored before webhook verification existed carry no secret. Nothing in
+   * gitops can create the webhook at the provider (neither provider implementation nor
+   * the Gitea/GitLab clients expose a hooks endpoint), so the secret is minted here and
+   * the connection is marked 'unverified': its deliveries stay refused until an operator
+   * copies the secret into the provider's webhook configuration and confirms it.
+   */
+  private async backfillWebhookSecret(conn: interfaces.data.IProviderConnection): Promise<void> {
+    // A stored-but-unreadable secret is not a missing one. Minting here would write a new
+    // secret over the same keychain id and destroy confirmed operator material because of
+    // a transient read failure, so this connection is left exactly as it is on disk.
+    if (conn.webhookSecretUnreadable) return;
+    if (conn.webhookSecret && conn.webhookStatus) return;
+    if (!conn.webhookSecret) {
+      conn.webhookSecret = mintWebhookSecret();
+    }
+    conn.webhookStatus = 'unverified';
+    await this.persistConnection(conn);
+    logger.warn(
+      `Connection "${conn.name}" had no webhook secret — minted one and marked the webhook unverified. ` +
+        'Webhook deliveries are refused until the secret is set at the provider and confirmed.',
+    );
+  }
+
   private async persistConnection(conn: interfaces.data.IProviderConnection): Promise<void> {
     // Store real token in keychain
     await this.smartSecret.setSecret(conn.id, conn.token);
@@ -165,11 +215,29 @@ export class ConnectionManager {
     } else {
       await this.smartSecret.deleteSecret(getRegistryTokenSecretId(conn.id));
     }
+    // A connection whose secret is stored but unreadable keeps both its keychain entry and
+    // its sentinel: writing would replace material we could not read, deleting would throw
+    // it away. Every other persist path (status updates, health checks) runs through here,
+    // so this is where the stored secret survives a secret-store outage.
+    if (conn.webhookSecretUnreadable) {
+      // nothing to write — the stored secret and sentinel stay as they are
+    } else if (conn.webhookSecret) {
+      await this.smartSecret.setSecret(getWebhookSecretId(conn.id), conn.webhookSecret);
+    } else {
+      await this.smartSecret.deleteSecret(getWebhookSecretId(conn.id));
+    }
     // Save JSON with sentinel value
     const jsonConn = {
       ...conn,
       token: `${KEYCHAIN_PREFIX}${conn.id}`,
       registryToken: conn.registryToken ? `${KEYCHAIN_PREFIX}${getRegistryTokenSecretId(conn.id)}` : undefined,
+      webhookSecret:
+        conn.webhookSecret || conn.webhookSecretUnreadable
+          ? `${KEYCHAIN_PREFIX}${getWebhookSecretId(conn.id)}`
+          : undefined,
+      // Runtime-only flag: it describes this process's view of the secret store, not the
+      // connection, and persisting it would outlive the outage that caused it.
+      webhookSecretUnreadable: undefined,
     };
     await this.storageManager.setJSON(`${CONNECTIONS_PREFIX}${conn.id}.json`, jsonConn);
   }
@@ -177,15 +245,26 @@ export class ConnectionManager {
   private async removeConnection(id: string): Promise<void> {
     await this.smartSecret.deleteSecret(id);
     await this.smartSecret.deleteSecret(getRegistryTokenSecretId(id));
+    await this.smartSecret.deleteSecret(getWebhookSecretId(id));
     await this.storageManager.delete(`${CONNECTIONS_PREFIX}${id}.json`);
   }
 
-  getConnections(): interfaces.data.IProviderConnection[] {
-    return this.connections.map((c) => ({
-      ...c,
+  /**
+   * The shape handed to API callers: every secret is masked, never the real value.
+   */
+  private toPublicConnection(
+    conn: interfaces.data.IProviderConnection,
+  ): interfaces.data.IProviderConnection {
+    return {
+      ...conn,
       token: '***',
-      registryToken: c.registryToken ? '***' : undefined,
-    }));
+      registryToken: conn.registryToken ? '***' : undefined,
+      webhookSecret: conn.webhookSecret ? '***' : undefined,
+    };
+  }
+
+  getConnections(): interfaces.data.IProviderConnection[] {
+    return this.connections.map((c) => this.toPublicConnection(c));
   }
 
   getConnection(id: string): interfaces.data.IProviderConnection | undefined {
@@ -214,11 +293,15 @@ export class ConnectionManager {
       registryUrl: registryUrl || undefined,
       registryUsername: registryUsername || undefined,
       registryToken: registryToken || undefined,
+      // Minted with the connection so the operator can paste it into the provider's
+      // webhook form right away; no earlier provider state can hold a stale secret.
+      webhookSecret: mintWebhookSecret(),
+      webhookStatus: 'active',
     };
     this.connections.push(connection);
     await this.persistConnection(connection);
     logger.success(`Connection created: ${name} (${providerType})`);
-    return { ...connection, token: '***', registryToken: connection.registryToken ? '***' : undefined };
+    return this.toPublicConnection(connection);
   }
 
   async updateConnection(
@@ -238,7 +321,7 @@ export class ConnectionManager {
     if (updates.registryUsername !== undefined) conn.registryUsername = updates.registryUsername || undefined;
     if (updates.registryToken !== undefined) conn.registryToken = updates.registryToken || undefined;
     await this.persistConnection(conn);
-    return { ...conn, token: '***', registryToken: conn.registryToken ? '***' : undefined };
+    return this.toPublicConnection(conn);
   }
 
   async deleteConnection(id: string): Promise<void> {
@@ -255,7 +338,66 @@ export class ConnectionManager {
     conn.status = paused ? 'paused' : 'disconnected';
     await this.persistConnection(conn);
     logger.info(`Connection ${paused ? 'paused' : 'resumed'}: ${conn.name}`);
-    return { ...conn, token: '***', registryToken: conn.registryToken ? '***' : undefined };
+    return this.toPublicConnection(conn);
+  }
+
+  /**
+   * Reveals the webhook secret to an already authenticated caller — the operator has to
+   * transfer it into the provider's webhook configuration by hand, because no provider
+   * API surface in this app creates webhooks.
+   */
+  /**
+   * A stored-but-unreadable secret is reported as such, so an operator sees a secret-store
+   * outage instead of a connection that appears to have lost its secret.
+   */
+  private assertWebhookSecretReadable(conn: interfaces.data.IProviderConnection): void {
+    if (conn.webhookSecretUnreadable) {
+      throw new Error(
+        `Webhook secret for connection ${conn.id} is stored but unreadable — the secret store did not return it`,
+      );
+    }
+  }
+
+  getWebhookSecret(id: string): { secret: string; status: interfaces.data.TWebhookStatus } {
+    const conn = this.connections.find((c) => c.id === id);
+    if (!conn) throw new Error(`Connection not found: ${id}`);
+    this.assertWebhookSecretReadable(conn);
+    if (!conn.webhookSecret) throw new Error(`Connection has no webhook secret: ${id}`);
+    return { secret: conn.webhookSecret, status: conn.webhookStatus ?? 'unverified' };
+  }
+
+  /**
+   * Mints a fresh webhook secret. The provider still holds the previous one, so the
+   * connection goes back to 'unverified' until the new secret is confirmed.
+   */
+  async rotateWebhookSecret(
+    id: string,
+  ): Promise<{ secret: string; status: interfaces.data.TWebhookStatus }> {
+    const conn = this.connections.find((c) => c.id === id);
+    if (!conn) throw new Error(`Connection not found: ${id}`);
+    conn.webhookSecret = mintWebhookSecret();
+    conn.webhookStatus = 'unverified';
+    // Rotation is the operator's explicit decision to replace the stored secret, which is
+    // also the way out of an unreadable one — unlike the automatic backfill.
+    conn.webhookSecretUnreadable = undefined;
+    await this.persistConnection(conn);
+    logger.info(`Webhook secret rotated for connection "${conn.name}" — webhook is unverified again`);
+    return { secret: conn.webhookSecret, status: conn.webhookStatus };
+  }
+
+  /**
+   * Records that the provider side now holds the current secret; deliveries that carry a
+   * valid signature are accepted from here on.
+   */
+  async confirmWebhookSecret(id: string): Promise<{ status: interfaces.data.TWebhookStatus }> {
+    const conn = this.connections.find((c) => c.id === id);
+    if (!conn) throw new Error(`Connection not found: ${id}`);
+    this.assertWebhookSecretReadable(conn);
+    if (!conn.webhookSecret) throw new Error(`Connection has no webhook secret: ${id}`);
+    conn.webhookStatus = 'active';
+    await this.persistConnection(conn);
+    logger.success(`Webhook confirmed for connection "${conn.name}"`);
+    return { status: conn.webhookStatus };
   }
 
   async testConnection(id: string): Promise<{ ok: boolean; error?: string }> {

package/ts/opsserver/handlers/webhook.handler.ts

@@ -2,30 +2,191 @@ import * as plugins from '../../plugins.js';
 import { logger } from '../../logging.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
+import { requireValidIdentity } from '../helpers/guards.js';
+import {
+  checkWebhookConnection,
+  readBoundedWebhookBody,
+  verifyWebhookDelivery,
+  webhookEventHeaderFor,
+  webhookSecretHeaderFor,
+  type TWebhookRefusal,
+} from '../helpers/webhookverification.js';
+
+/** Route pattern of the delivery endpoint. */
+export const webhookRoutePattern = '/webhook/:connectionId';
+
+/** The concrete delivery path an operator configures at the provider. */
+export const webhookDeliveryPath = (connectionIdArg: string): string =>
+  `/webhook/${connectionIdArg}`;
+
+/**
+ * HTTP status per refusal. Everything the caller could fix by presenting the right
+ * secret is a 401; the rest describes the request itself — except
+ * 'webhook-secret-unreadable', which is our own transient fault and is answered 503 so a
+ * provider retries instead of an operator rotating a secret that is still correct.
+ */
+const refusalStatusCodes: Record<TWebhookRefusal, number> = {
+  'webhook-connection-unknown': 404,
+  'webhook-connection-unverified': 401,
+  'webhook-secret-missing': 401,
+  'webhook-secret-unreadable': 503,
+  'webhook-length-missing': 411,
+  'webhook-body-too-large': 413,
+  'webhook-body-unreadable': 400,
+  'webhook-signature-missing': 401,
+  'webhook-signature-invalid': 401,
+};
 
 export class WebhookHandler {
-  constructor(private opsServerRef: OpsServer) {}
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  constructor(private opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  private get connectionManager() {
+    return this.opsServerRef.gitopsAppRef.connectionManager;
+  }
+
+  private get actionLog() {
+    return this.opsServerRef.gitopsAppRef.actionLog;
+  }
+
+  /**
+   * Refuses a delivery. The refusal name is the whole answer — no payload is echoed and
+   * nothing about the presented or expected secret is logged.
+   */
+  private refuse(
+    refusalArg: TWebhookRefusal,
+    connectionIdArg: string,
+    connectionNameArg?: string,
+  ): Response {
+    const target = connectionNameArg
+      ? `connection ${connectionNameArg} (${connectionIdArg})`
+      : `connection ${connectionIdArg}`;
+    logger.warn(`Webhook refused: ${refusalArg} for ${target}`);
+    return new Response(JSON.stringify({ error: refusalArg }), {
+      status: refusalStatusCodes[refusalArg],
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  private webhookSettingsFor(
+    connectionIdArg: string,
+  ): interfaces.data.IWebhookSettings {
+    const connection = this.connectionManager.getConnection(connectionIdArg);
+    if (!connection) {
+      throw new plugins.typedrequest.TypedResponseError(`Connection not found: ${connectionIdArg}`);
+    }
+    const { secret, status } = this.connectionManager.getWebhookSecret(connectionIdArg);
+    return {
+      connectionId: connection.id,
+      providerType: connection.providerType,
+      deliveryPath: webhookDeliveryPath(connection.id),
+      headerName: webhookSecretHeaderFor(connection.providerType),
+      secret,
+      status,
+    };
+  }
+
+  /**
+   * Operator-facing side of the webhook: reveal, rotate and confirm the shared secret.
+   * Neither provider implementation creates webhooks through the API, so the secret is
+   * transferred into the provider's webhook configuration by hand.
+   */
+  private registerHandlers(): void {
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetWebhookSettings>(
+        'getWebhookSettings',
+        async (dataArg) => {
+          await requireValidIdentity(this.opsServerRef.adminHandler, dataArg);
+          return { webhookSettings: this.webhookSettingsFor(dataArg.connectionId) };
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RotateWebhookSecret>(
+        'rotateWebhookSecret',
+        async (dataArg) => {
+          await requireValidIdentity(this.opsServerRef.adminHandler, dataArg);
+          await this.connectionManager.rotateWebhookSecret(dataArg.connectionId);
+          const webhookSettings = this.webhookSettingsFor(dataArg.connectionId);
+          this.actionLog.append({
+            actionType: 'update',
+            entityType: 'connection',
+            entityId: dataArg.connectionId,
+            entityName: this.connectionManager.getConnection(dataArg.connectionId)?.name || dataArg.connectionId,
+            details: 'Rotated webhook secret — webhook is unverified until the new secret is set at the provider',
+            username: dataArg.identity.username,
+          });
+          return { webhookSettings };
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ConfirmWebhookSecret>(
+        'confirmWebhookSecret',
+        async (dataArg) => {
+          await requireValidIdentity(this.opsServerRef.adminHandler, dataArg);
+          const result = await this.connectionManager.confirmWebhookSecret(dataArg.connectionId);
+          this.actionLog.append({
+            actionType: 'update',
+            entityType: 'connection',
+            entityId: dataArg.connectionId,
+            entityName: this.connectionManager.getConnection(dataArg.connectionId)?.name || dataArg.connectionId,
+            details: 'Confirmed the webhook secret is configured at the provider',
+            username: dataArg.identity.username,
+          });
+          return result;
+        },
+      ),
+    );
+  }
 
   public registerRoutes(typedserver: plugins.typedserver.TypedServer): void {
-    typedserver.addRoute('/webhook/:connectionId', 'POST', async (ctx) => {
+    typedserver.addRoute(webhookRoutePattern, 'POST', async (ctx) => {
       const connectionId = ctx.params.connectionId;
 
-      // Validate connection exists
-      const connection = this.opsServerRef.gitopsAppRef.connectionManager.getConnection(connectionId);
+      // The connection carries the secret, so it is resolved before any body work.
+      const connection = this.connectionManager.getConnection(connectionId);
       if (!connection) {
-        return new Response(JSON.stringify({ error: 'Connection not found' }), {
-          status: 404,
-          headers: { 'Content-Type': 'application/json' },
-        });
+        return this.refuse('webhook-connection-unknown', connectionId);
+      }
+
+      // Everything that does not need the body is decided before buffering it.
+      const precondition = checkWebhookConnection(connection);
+      if (precondition) {
+        return this.refuse(precondition, connectionId, connection.name);
+      }
+      // The raw bytes are what the provider signed; parsing and re-serializing would
+      // change key order and whitespace and invalidate every genuine signature. The body
+      // is read through the bounded reader rather than ctx.arrayBuffer(), which buffers
+      // whatever an unauthenticated caller sends.
+      const body = await readBoundedWebhookBody({
+        headers: ctx.headers,
+        body: () => ctx.request.body,
+      });
+      if (!body.ok) {
+        return this.refuse(body.refusal, connectionId, connection.name);
+      }
+
+      const verification = verifyWebhookDelivery({
+        connection,
+        headers: ctx.headers,
+        rawBody: body.rawBody,
+      });
+      if (!verification.ok) {
+        return this.refuse(verification.refusal!, connectionId, connection.name);
       }
 
-      // Parse event type from provider-specific headers
-      const giteaEvent = ctx.headers.get('X-Gitea-Event');
-      const gitlabEvent = ctx.headers.get('X-Gitlab-Event');
-      const event = giteaEvent || gitlabEvent || 'unknown';
-      const provider = giteaEvent ? 'gitea' : gitlabEvent ? 'gitlab' : 'unknown';
+      // The provider is the one we have a connection with, never the one the caller claims.
+      const provider = connection.providerType;
+      const event = ctx.headers.get(webhookEventHeaderFor(provider)) || 'unknown';
 
-      logger.info(`Webhook received: ${provider}/${event} for connection ${connection.name} (${connectionId})`);
+      logger.info(`Webhook accepted: ${provider}/${event} for connection ${connection.name} (${connectionId})`);
 
       // Broadcast to all connected frontends via TypedSocket
       try {