@serve.zone/gitops 3.1.1 → 32.1.0

package/ts/opsserver/helpers/webhookverification.ts

@@ -0,0 +1,202 @@
+import * as plugins from '../../plugins.js';
+import type * as interfaces from '../../../ts_interfaces/index.js';
+import { GiteaProvider, GitLabProvider } from '../../providers/index.js';
+
+/**
+ * Largest webhook delivery gitops buffers. Gitea and GitLab push payloads stay far below
+ * this. The bound is enforced while the body is being read (see readBoundedWebhookBody),
+ * so it caps what an unauthenticated caller can make the process hold in memory even when
+ * the delivery declares a smaller Content-Length than it sends.
+ */
+export const webhookMaxBodyBytes = 1024 * 1024;
+
+/**
+ * Stable refusal names. They are returned to the caller and written to the log, so an
+ * operator can tell a stale secret from a missing one without inspecting payloads.
+ */
+export type TWebhookRefusal =
+  | 'webhook-connection-unknown'
+  | 'webhook-connection-unverified'
+  | 'webhook-secret-missing'
+  | 'webhook-secret-unreadable'
+  | 'webhook-length-missing'
+  | 'webhook-body-too-large'
+  | 'webhook-body-unreadable'
+  | 'webhook-signature-missing'
+  | 'webhook-signature-invalid';
+
+export interface IWebhookVerificationResult {
+  ok: boolean;
+  refusal?: TWebhookRefusal;
+}
+
+/** Outcome of reading a delivery body: the raw bytes, or the reason the read was refused. */
+export type TWebhookBodyResult =
+  | { ok: true; rawBody: Uint8Array }
+  | { ok: false; refusal: TWebhookRefusal };
+
+/** Non-negative integer, nothing else — a duplicated or padded header value is not one. */
+const contentLengthPattern = /^\d+$/;
+
+const hexPattern = /^[0-9a-f]+$/;
+
+/**
+ * Compares two strings without leaking their content through timing. Length differs
+ * openly: timingSafeEqual throws on unequal buffer lengths, and the length of a
+ * signature header is observable anyway.
+ */
+const timingSafeEqualStrings = (leftArg: string, rightArg: string): boolean => {
+  const left = plugins.Buffer.from(leftArg, 'utf8');
+  const right = plugins.Buffer.from(rightArg, 'utf8');
+  if (left.length !== right.length) return false;
+  return plugins.crypto.timingSafeEqual(left, right);
+};
+
+/**
+ * The header that names the delivered event for a given provider.
+ */
+export const webhookEventHeaderFor = (
+  providerTypeArg: interfaces.data.TProviderType,
+): string => {
+  return providerTypeArg === 'gitea'
+    ? GiteaProvider.webhookEventHeader
+    : GitLabProvider.webhookEventHeader;
+};
+
+/**
+ * The header a provider uses to prove it holds the webhook secret.
+ */
+export const webhookSecretHeaderFor = (
+  providerTypeArg: interfaces.data.TProviderType,
+): string => {
+  return providerTypeArg === 'gitea'
+    ? GiteaProvider.webhookSignatureHeader
+    : GitLabProvider.webhookTokenHeader;
+};
+
+/**
+ * Checks everything that does not depend on the request body, so an unusable
+ * connection is refused before a single byte is buffered.
+ */
+export const checkWebhookConnection = (
+  connectionArg: interfaces.data.IProviderConnection,
+): TWebhookRefusal | null => {
+  // The secret store holds this connection's secret but would not return it. Nothing can
+  // be verified against it, and it must not be replaced by a fresh one, so deliveries are
+  // refused under their own name until the secret store recovers.
+  if (connectionArg.webhookSecretUnreadable) return 'webhook-secret-unreadable';
+  if (!connectionArg.webhookSecret) return 'webhook-secret-missing';
+  // A connection whose secret was minted by the backfill is not yet known to the
+  // provider, so nothing it delivers can be trusted until the operator confirms it.
+  if (connectionArg.webhookStatus !== 'active') return 'webhook-connection-unverified';
+  return null;
+};
+
+/**
+ * Verifies a delivery against the connection's webhook secret.
+ *
+ * Gitea: HMAC-SHA256 over the raw delivery bytes, hex, in X-Gitea-Signature.
+ * GitLab: the secret token echoed verbatim in X-Gitlab-Token.
+ *
+ * rawBody must be the bytes as received — re-serializing the parsed JSON changes key
+ * order and whitespace and would invalidate every genuine signature.
+ */
+export const verifyWebhookDelivery = (optionsArg: {
+  connection: interfaces.data.IProviderConnection;
+  headers: Headers;
+  rawBody: Uint8Array;
+}): IWebhookVerificationResult => {
+  const precondition = checkWebhookConnection(optionsArg.connection);
+  if (precondition) return { ok: false, refusal: precondition };
+  const secret = optionsArg.connection.webhookSecret!;
+
+  if (optionsArg.connection.providerType === 'gitea') {
+    const signature = optionsArg.headers.get(GiteaProvider.webhookSignatureHeader);
+    if (!signature) return { ok: false, refusal: 'webhook-signature-missing' };
+    const expected = plugins.crypto.createHmac('sha256', secret).update(optionsArg.rawBody).digest();
+    const provided = signature.trim().toLowerCase();
+    // Length and alphabet are checked before decoding: Buffer.from(..., 'hex') silently
+    // truncates malformed input, and timingSafeEqual throws on a length mismatch.
+    if (provided.length !== expected.length * 2 || !hexPattern.test(provided)) {
+      return { ok: false, refusal: 'webhook-signature-invalid' };
+    }
+    const providedBuffer = plugins.Buffer.from(provided, 'hex');
+    if (!plugins.crypto.timingSafeEqual(providedBuffer, expected)) {
+      return { ok: false, refusal: 'webhook-signature-invalid' };
+    }
+    return { ok: true };
+  }
+
+  const token = optionsArg.headers.get(GitLabProvider.webhookTokenHeader);
+  if (!token) return { ok: false, refusal: 'webhook-signature-missing' };
+  if (!timingSafeEqualStrings(token, secret)) {
+    return { ok: false, refusal: 'webhook-signature-invalid' };
+  }
+  return { ok: true };
+};
+
+/**
+ * Reads a delivery body under a hard byte budget.
+ *
+ * Two separate guards, because each covers what the other cannot:
+ *  - Content-Length is required. Gitea and GitLab always declare one; a delivery without a
+ *    parsable length is chunked or headerless, and reading it would mean buffering a stream
+ *    of unknown size from an unauthenticated caller. It is refused as
+ *    'webhook-length-missing' before the body is touched at all.
+ *  - The declared length is the caller's claim, never a fact, so the stream is consumed
+ *    chunk by chunk against a running budget. A forged short Content-Length is refused the
+ *    moment the bound is crossed, with only the bound buffered.
+ */
+export const readBoundedWebhookBody = async (optionsArg: {
+  headers: Headers;
+  /** Lazy on purpose: not called when the delivery is refused on its headers alone. */
+  body: () => ReadableStream<Uint8Array> | null;
+  maxBytes?: number;
+}): Promise<TWebhookBodyResult> => {
+  const maxBytes = optionsArg.maxBytes ?? webhookMaxBodyBytes;
+  const declared = optionsArg.headers.get('content-length');
+  if (declared === null || !contentLengthPattern.test(declared.trim())) {
+    return { ok: false, refusal: 'webhook-length-missing' };
+  }
+  const declaredLength = Number(declared.trim());
+  if (declaredLength > maxBytes) {
+    return { ok: false, refusal: 'webhook-body-too-large' };
+  }
+
+  const stream = optionsArg.body();
+  if (!stream) {
+    // No stream at all is only consistent with a delivery that declared no bytes.
+    return declaredLength === 0
+      ? { ok: true, rawBody: new Uint8Array(0) }
+      : { ok: false, refusal: 'webhook-body-unreadable' };
+  }
+
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let received = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      received += value.byteLength;
+      if (received > maxBytes) {
+        // Stop pulling: the rest of the body is never buffered.
+        await reader.cancel().catch(() => undefined);
+        return { ok: false, refusal: 'webhook-body-too-large' };
+      }
+      chunks.push(value);
+    }
+  } catch {
+    await reader.cancel().catch(() => undefined);
+    return { ok: false, refusal: 'webhook-body-unreadable' };
+  }
+
+  const rawBody = new Uint8Array(received);
+  let offset = 0;
+  for (const chunk of chunks) {
+    rawBody.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return { ok: true, rawBody };
+};

package/ts/plugins.ts

@@ -8,9 +8,10 @@ import * as fs from 'node:fs/promises';
 import * as os from 'node:os';
 import * as nodeUrl from 'node:url';
 import * as childProcess from 'node:child_process';
+import * as crypto from 'node:crypto';
 import { Buffer } from 'node:buffer';
 
-export { path, fs, os, nodeUrl, childProcess, Buffer };
+export { path, fs, os, nodeUrl, childProcess, crypto, Buffer };
 
 // TypedRequest/TypedServer infrastructure
 import * as typedrequest from '@api.global/typedrequest';

package/ts/providers/classes.giteaprovider.ts

@@ -6,6 +6,17 @@ import { BaseProvider, type IReleaseAssetPayload, type IReleaseAssetTransferOpti
  * Gitea API v1 provider implementation
  */
 export class GiteaProvider extends BaseProvider {
+  /**
+   * Gitea signs a webhook delivery by HMAC-SHA256 over the raw request body with the
+   * webhook secret and sends the digest as lowercase hex in this header.
+   *
+   * Spelled the way Gitea documents it: header lookup is case-insensitive, so the same
+   * constant serves the verification and the operator-facing webhook dialog.
+   */
+  public static readonly webhookSignatureHeader = 'X-Gitea-Signature';
+  /** Header naming the delivered event, e.g. 'push'. */
+  public static readonly webhookEventHeader = 'X-Gitea-Event';
+
   private client: plugins.giteaClient.GiteaClient;
 
   constructor(connectionId: string, baseUrl: string, token: string, groupFilterId?: string) {

package/ts/providers/classes.gitlabprovider.ts

@@ -6,6 +6,17 @@ import { BaseProvider, type IReleaseAssetPayload, type IReleaseAssetTransferOpti
  * GitLab API v4 provider implementation
  */
 export class GitLabProvider extends BaseProvider {
+  /**
+   * GitLab does not sign webhook bodies: it echoes the configured secret token
+   * verbatim in this header, so the comparison is against the secret itself.
+   *
+   * Spelled the way GitLab documents it: header lookup is case-insensitive, so the same
+   * constant serves the verification and the operator-facing webhook dialog.
+   */
+  public static readonly webhookTokenHeader = 'X-Gitlab-Token';
+  /** Header naming the delivered event, e.g. 'Push Hook'. */
+  public static readonly webhookEventHeader = 'X-Gitlab-Event';
+
   private client: plugins.gitlabClient.GitLabClient;
 
   constructor(connectionId: string, baseUrl: string, token: string, groupFilterId?: string) {

package/ts_interfaces/data/connection.ts

@@ -1,5 +1,13 @@
 export type TProviderType = 'gitea' | 'gitlab';
 
+/**
+ * Whether the provider side of a connection is known to hold the webhook secret.
+ * 'unverified' connections were created before gitops minted webhook secrets: the
+ * operator still has to copy the minted secret into the provider's webhook config,
+ * so their deliveries are refused until they confirm it.
+ */
+export type TWebhookStatus = 'active' | 'unverified';
+
 export interface IProviderConnection {
   id: string;
   name: string;
@@ -13,4 +21,25 @@ export interface IProviderConnection {
   registryUrl?: string;      // Optional OCI registry host/base URL when it differs from provider baseUrl
   registryUsername?: string; // Optional OCI registry username; provider token is used first when omitted
   registryToken?: string;    // Optional OCI registry token/password; stored in keychain when configured
+  webhookSecret?: string;    // Shared secret for incoming provider webhooks; stored in keychain, masked on read
+  webhookStatus?: TWebhookStatus; // 'active' once the provider side is known to hold the secret
+  /**
+   * Set while the secret store holds this connection's webhook secret but did not return
+   * it. Runtime-only and never persisted: the stored sentinel and status stay valid, so a
+   * failed read must neither mint a replacement nor overwrite the stored material.
+   */
+  webhookSecretUnreadable?: boolean;
+}
+
+/**
+ * Everything an operator needs to configure the webhook at the provider.
+ * Handed out only to an authenticated caller — it carries the real secret.
+ */
+export interface IWebhookSettings {
+  connectionId: string;
+  providerType: TProviderType;
+  deliveryPath: string; // path the provider posts to, e.g. '/webhook/<id>'
+  headerName: string;   // header carrying the signature (Gitea) or the token (GitLab)
+  secret: string;
+  status: TWebhookStatus;
 }

package/ts_interfaces/requests/webhook.ts

@@ -16,3 +16,45 @@ 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/ts_web/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_web/appstate.ts

@@ -205,6 +205,52 @@ export const createConnectionAction = connectionsStatePart.createAction<{
   }
 });
 
+/**
+ * Webhook secrets are fetched on demand and handed straight to the caller — they are
+ * never put into a state part, where every subscriber would see them.
+ */
+export const fetchWebhookSettings = async (
+  connectionIdArg: string,
+): Promise<interfaces.data.IWebhookSettings> => {
+  const context = getActionContext();
+  const typedRequest = new plugins.domtools.plugins.typedrequest.TypedRequest<
+    interfaces.requests.IReq_GetWebhookSettings
+  >('/typedrequest', 'getWebhookSettings');
+  const response = await typedRequest.fire({
+    identity: context.identity!,
+    connectionId: connectionIdArg,
+  });
+  return response.webhookSettings;
+};
+
+export const rotateWebhookSecret = async (
+  connectionIdArg: string,
+): Promise<interfaces.data.IWebhookSettings> => {
+  const context = getActionContext();
+  const typedRequest = new plugins.domtools.plugins.typedrequest.TypedRequest<
+    interfaces.requests.IReq_RotateWebhookSecret
+  >('/typedrequest', 'rotateWebhookSecret');
+  const response = await typedRequest.fire({
+    identity: context.identity!,
+    connectionId: connectionIdArg,
+  });
+  return response.webhookSettings;
+};
+
+export const confirmWebhookSecret = async (
+  connectionIdArg: string,
+): Promise<interfaces.data.TWebhookStatus> => {
+  const context = getActionContext();
+  const typedRequest = new plugins.domtools.plugins.typedrequest.TypedRequest<
+    interfaces.requests.IReq_ConfirmWebhookSecret
+  >('/typedrequest', 'confirmWebhookSecret');
+  const response = await typedRequest.fire({
+    identity: context.identity!,
+    connectionId: connectionIdArg,
+  });
+  return response.status;
+};
+
 export const testConnectionAction = connectionsStatePart.createAction<{
   connectionId: string;
 }>(async (statePartArg, dataArg) => {

package/ts_web/elements/views/connections/index.ts

@@ -1,5 +1,6 @@
 import * as plugins from '../../../plugins.js';
 import * as appstate from '../../../appstate.js';
+import type * as interfaces from '../../../../ts_interfaces/index.js';
 import { viewHostCss } from '../../shared/index.js';
 import {
   DeesElement,
@@ -65,6 +66,7 @@ export class GitopsViewConnections extends DeesElement {
           'Group Filter': item.groupFilter || '-',
           Registry: item.registryUrl || '-',
           'Registry User': item.registryUsername || '-',
+          Webhook: item.webhookStatus || 'unverified',
           Status: item.status,
           Created: new Date(item.createdAt).toLocaleDateString(),
         })}
@@ -86,6 +88,12 @@ export class GitopsViewConnections extends DeesElement {
               );
             },
           },
+          {
+            name: 'Webhook',
+            iconName: 'lucide:webhook',
+            type: ['inRow', 'contextmenu'],
+            actionFunc: async ({ item }: any) => { await this.showWebhookSettings(item); },
+          },
           {
             name: 'Pause/Resume',
             iconName: 'lucide:pauseCircle',
@@ -149,6 +157,87 @@ export class GitopsViewConnections extends DeesElement {
     await appstate.connectionsStatePart.dispatchAction(appstate.fetchConnectionsAction, null);
   }
 
+  /**
+   * Shows the shared secret the provider has to send with every delivery. gitops cannot
+   * create the webhook through the provider API, so the operator pastes the secret into
+   * the provider's webhook form and confirms it here.
+   */
+  private async showWebhookSettings(item: any) {
+    let settings: interfaces.data.IWebhookSettings;
+    try {
+      settings = await appstate.fetchWebhookSettings(item.id);
+    } catch (err) {
+      console.error('Failed to load webhook settings:', err);
+      await plugins.deesCatalog.DeesModal.createAndShow({
+        heading: 'Webhook',
+        content: html`<p style="color: #fff;">Could not load the webhook settings for "${item.name}".</p>`,
+        menuOptions: [{ name: 'Close', action: async (modal: any) => { modal.destroy(); } }],
+      });
+      return;
+    }
+    const deliveryUrl = `${window.location.origin}${settings.deliveryPath}`;
+    const secretLabel = settings.providerType === 'gitea' ? 'Secret' : 'Secret Token';
+    await plugins.deesCatalog.DeesModal.createAndShow({
+      heading: `Webhook — ${item.name}`,
+      content: html`
+        <style>
+          .webhook-row { margin-bottom: 12px; color: #fff; }
+          .webhook-label { font-size: 12px; color: #888; }
+          .webhook-value { font-family: monospace; word-break: break-all; }
+          .webhook-hint { font-size: 13px; color: #888; margin-top: 16px; }
+        </style>
+        <div class="webhook-row">
+          <div class="webhook-label">Payload URL</div>
+          <div class="webhook-value">${deliveryUrl}</div>
+        </div>
+        <div class="webhook-row">
+          <div class="webhook-label">${secretLabel}</div>
+          <div class="webhook-value">${settings.secret}</div>
+        </div>
+        <div class="webhook-row">
+          <div class="webhook-label">Verification header</div>
+          <div class="webhook-value">${settings.headerName}</div>
+        </div>
+        <div class="webhook-row">
+          <div class="webhook-label">Status</div>
+          <div class="webhook-value">${settings.status}</div>
+        </div>
+        <div class="webhook-hint">
+          Set this ${secretLabel.toLowerCase()} on the webhook in ${settings.providerType === 'gitea' ? 'Gitea' : 'GitLab'},
+          then choose "Mark configured". Deliveries are refused while the webhook is unverified or
+          signed with a different secret.
+        </div>
+      `,
+      menuOptions: [
+        { name: 'Close', action: async (modal: any) => { modal.destroy(); } },
+        {
+          name: 'Rotate Secret',
+          action: async (modal: any) => {
+            try {
+              await appstate.rotateWebhookSecret(item.id);
+            } catch (err) {
+              console.error('Failed to rotate webhook secret:', err);
+            }
+            modal.destroy();
+            await this.refresh();
+          },
+        },
+        {
+          name: 'Mark Configured',
+          action: async (modal: any) => {
+            try {
+              await appstate.confirmWebhookSecret(item.id);
+            } catch (err) {
+              console.error('Failed to confirm webhook secret:', err);
+            }
+            modal.destroy();
+            await this.refresh();
+          },
+        },
+      ],
+    });
+  }
+
   private async editConnection(item: any) {
     await plugins.deesCatalog.DeesModal.createAndShow({
       heading: 'Edit Connection',

package/readme.todo.md

@@ -1,3 +0,0 @@
-# GitOps TODOs
-
-- [ ] Webhook HMAC signature verification (X-Gitea-Signature / X-Gitlab-Token) — currently accepts all POSTs