@shipfox/api-integration-gitea 5.0.0 → 7.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-gitea",
   "license": "MIT",
-  "version": "5.0.0",
+  "version": "7.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -23,31 +23,20 @@
   },
   "dependencies": {
     "drizzle-orm": "^0.45.2",
-    "@shipfox/api-auth-context": "5.0.0",
-    "@shipfox/api-integration-core-dto": "5.0.0",
-    "@shipfox/api-integration-gitea-dto": "5.0.0",
+    "@shipfox/api-auth-context": "7.1.0",
+    "@shipfox/api-integration-core-dto": "6.0.0",
+    "@shipfox/api-integration-gitea-dto": "6.0.0",
     "@shipfox/config": "1.2.2",
-    "@shipfox/node-drizzle": "0.3.1",
-    "@shipfox/node-fastify": "0.2.3",
-    "@shipfox/node-opentelemetry": "0.5.2",
+    "@shipfox/node-drizzle": "0.3.2",
+    "@shipfox/node-fastify": "0.3.0",
+    "@shipfox/node-opentelemetry": "0.6.0",
     "@shipfox/node-postgres": "0.4.2"
   },
-  "devDependencies": {
-    "@types/pg": "^8.15.5",
-    "drizzle-kit": "^0.31.10",
-    "fastify": "^5.3.3",
-    "fastify-type-provider-zod": "^6.0.0",
-    "fishery": "^2.4.0",
-    "@shipfox/biome": "1.8.2",
-    "@shipfox/swc": "1.2.6",
-    "@shipfox/ts-config": "1.3.8",
-    "@shipfox/typescript": "1.1.7",
-    "@shipfox/vitest": "1.2.3"
-  },
   "scripts": {
     "build": "shipfox-swc",
     "check": "shipfox-biome-check",
     "check:fix": "shipfox-biome-check --write",
+    "depcruise": "shipfox-depcruise",
     "test": "shipfox-vitest-run",
     "test:watch": "shipfox-vitest-watch",
     "type": "shipfox-tsc-check",

package/src/core/webhook-processor.test.ts

@@ -0,0 +1,83 @@
+import {createHmac, randomUUID} from 'node:crypto';
+import {createStoredWebhookRequest, decodeWebhookBody} from '@shipfox/api-integration-core-dto';
+import {createGiteaWebhookProcessor} from './webhook-processor.js';
+
+const WEBHOOK_SECRET = 'test-webhook-secret';
+
+describe('Gitea webhook processor', () => {
+  it('discards a stored request with an invalid signature before opening a transaction', async () => {
+    const coreDb = vi.fn();
+    const processor = createGiteaWebhookProcessor({
+      coreDb,
+      publishSourcePush: vi.fn(),
+      recordDeliveryOnly: vi.fn(),
+      getIntegrationConnectionById: vi.fn(),
+    });
+    const request = createStoredWebhookRequest({
+      requestId: randomUUID(),
+      routeId: 'gitea',
+      receivedAt: new Date().toISOString(),
+      rawQueryString: '',
+      headers: {
+        'x-gitea-delivery': randomUUID(),
+        'x-gitea-event': 'push',
+        'x-gitea-signature': 'not-a-valid-signature',
+      },
+      body: Buffer.from('{}'),
+    });
+
+    const result = await processor.process(request);
+
+    expect(result).toMatchObject({outcome: 'discarded', reason: 'invalid_signature'});
+    expect(coreDb).not.toHaveBeenCalled();
+  });
+
+  it('discards a stored request missing required provider headers', async () => {
+    const processor = createGiteaWebhookProcessor({
+      coreDb: vi.fn(),
+      publishSourcePush: vi.fn(),
+      recordDeliveryOnly: vi.fn(),
+      getIntegrationConnectionById: vi.fn(),
+    });
+    const request = createStoredWebhookRequest({
+      requestId: randomUUID(),
+      routeId: 'gitea',
+      receivedAt: new Date().toISOString(),
+      rawQueryString: '',
+      headers: {},
+      body: Buffer.from('{}'),
+    });
+
+    const result = await processor.process(request);
+
+    expect(result).toEqual({outcome: 'discarded', reason: 'missing_required_input'});
+  });
+
+  it('preserves the signed raw body from a stored request before reporting malformed JSON', async () => {
+    const rawBody = Buffer.from('{"message":"h\u00e9llo"');
+    const request = createStoredWebhookRequest({
+      requestId: randomUUID(),
+      routeId: 'gitea',
+      receivedAt: new Date().toISOString(),
+      rawQueryString: '',
+      headers: {
+        'x-gitea-delivery': randomUUID(),
+        'x-gitea-event': 'push',
+        'x-gitea-signature': createHmac('sha256', WEBHOOK_SECRET).update(rawBody).digest('hex'),
+      },
+      body: rawBody,
+    });
+    const processor = createGiteaWebhookProcessor({
+      coreDb: () =>
+        ({transaction: (callback: (tx: unknown) => Promise<unknown>) => callback({})}) as never,
+      publishSourcePush: vi.fn(),
+      recordDeliveryOnly: vi.fn(),
+      getIntegrationConnectionById: vi.fn(),
+    });
+
+    const result = await processor.process(request);
+
+    expect(Buffer.from(decodeWebhookBody(request.body))).toEqual(rawBody);
+    expect(result).toMatchObject({outcome: 'discarded', reason: 'malformed_payload'});
+  });
+});

package/src/core/webhook-processor.ts

@@ -0,0 +1,90 @@
+import {Buffer} from 'node:buffer';
+import {
+  decodeWebhookBody,
+  type GetIntegrationConnectionByIdFn,
+  type PublishSourcePushFn,
+  type RecordDeliveryOnlyFn,
+  type StoredWebhookRequest,
+  type WebhookProcessingResult,
+} from '@shipfox/api-integration-core-dto';
+import {verifyHexHmacSignature} from '@shipfox/node-fastify';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {NodePgDatabase} from 'drizzle-orm/node-postgres';
+import {config} from '#config.js';
+import {
+  GiteaWebhookMalformedJsonError,
+  GiteaWebhookMalformedPushPayloadError,
+  handleGiteaWebhook,
+} from '#core/webhook.js';
+
+const DELIVERY_HEADER = 'x-gitea-delivery';
+const EVENT_HEADER = 'x-gitea-event';
+const SIGNATURE_HEADER = 'x-gitea-signature';
+
+export interface CreateGiteaWebhookProcessorOptions {
+  coreDb: () => NodePgDatabase<Record<string, unknown>>;
+  publishSourcePush: PublishSourcePushFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+
+export interface GiteaWebhookProcessor {
+  process(request: StoredWebhookRequest): Promise<WebhookProcessingResult>;
+}
+
+export function createGiteaWebhookProcessor(
+  options: CreateGiteaWebhookProcessorOptions,
+): GiteaWebhookProcessor {
+  return {process: (request) => processGiteaWebhookRequest(options, request)};
+}
+
+async function processGiteaWebhookRequest(
+  options: CreateGiteaWebhookProcessorOptions,
+  request: StoredWebhookRequest,
+): Promise<WebhookProcessingResult> {
+  if (request.route_id !== 'gitea') {
+    throw new Error(`Gitea processor cannot process ${request.route_id} requests`);
+  }
+
+  const deliveryId = request.headers[DELIVERY_HEADER];
+  const event = request.headers[EVENT_HEADER];
+  const signature = request.headers[SIGNATURE_HEADER];
+  if (!deliveryId || !event || !signature) {
+    return {outcome: 'discarded', reason: 'missing_required_input'};
+  }
+
+  const rawBody = Buffer.from(decodeWebhookBody(request.body));
+  if (!verifyHexHmacSignature({rawBody, signature, secret: config.GITEA_WEBHOOK_SECRET})) {
+    return {outcome: 'discarded', reason: 'invalid_signature', deliveryId};
+  }
+
+  try {
+    const result = await options.coreDb().transaction(async (tx) =>
+      handleGiteaWebhook({
+        tx,
+        deliveryId,
+        event,
+        rawBody: rawBody.toString('utf8'),
+        publishSourcePush: options.publishSourcePush,
+        recordDeliveryOnly: options.recordDeliveryOnly,
+        getIntegrationConnectionById: options.getIntegrationConnectionById,
+      }),
+    );
+    return result.outcome === 'duplicate'
+      ? {outcome: 'duplicate', deliveryId}
+      : {outcome: 'processed', deliveryId};
+  } catch (error) {
+    if (error instanceof GiteaWebhookMalformedJsonError) {
+      logger().warn({deliveryId, err: error}, 'gitea webhook payload JSON parse failed');
+      return {outcome: 'discarded', reason: 'malformed_payload', deliveryId};
+    }
+    if (error instanceof GiteaWebhookMalformedPushPayloadError) {
+      logger().warn(
+        {deliveryId, issues: error.issues},
+        'gitea webhook push payload failed schema validation',
+      );
+      return {outcome: 'discarded', reason: 'unsupported_event', deliveryId};
+    }
+    throw error;
+  }
+}

package/src/index.ts

@@ -10,6 +10,7 @@ import {createGiteaApiClient, type GiteaApiClient} from '#api/client.js';
 import type {ConnectGiteaConnectionInput} from '#core/connect.js';
 import {giteaConnectionExternalUrl} from '#core/connection-url.js';
 import {GiteaSourceControlProvider} from '#core/source-control.js';
+import {createGiteaWebhookProcessor} from '#core/webhook-processor.js';
 import {closeDb, db} from '#db/db.js';
 import {migrationsPath} from '#db/migrations.js';
 import {createGiteaConnectionRoutes} from '#presentation/routes/connections.js';
@@ -32,6 +33,11 @@ export {
   GiteaOrganizationNotFoundError,
 } from '#core/errors.js';
 export {GiteaSourceControlProvider} from '#core/source-control.js';
+export type {
+  CreateGiteaWebhookProcessorOptions,
+  GiteaWebhookProcessor,
+} from '#core/webhook-processor.js';
+export {createGiteaWebhookProcessor} from '#core/webhook-processor.js';
 export type {GiteaConnection, UpsertGiteaConnectionParams} from '#db/connections.js';
 export {
   getGiteaConnectionByConnectionId,
@@ -56,6 +62,7 @@ export interface CreateGiteaIntegrationProviderOptions {
 
 export function createGiteaIntegrationProvider(options: CreateGiteaIntegrationProviderOptions) {
   const gitea = options.gitea ?? createGiteaApiClient();
+  const webhookProcessor = createGiteaWebhookProcessor(options);
 
   return {
     provider: giteaProviderKind,
@@ -77,7 +84,9 @@ export function createGiteaIntegrationProvider(options: CreateGiteaIntegrationPr
         publishSourcePush: options.publishSourcePush,
         recordDeliveryOnly: options.recordDeliveryOnly,
         getIntegrationConnectionById: options.getIntegrationConnectionById,
+        processor: webhookProcessor,
       }),
     ],
+    webhookProcessors: [{routeIds: ['gitea'] as const, processor: webhookProcessor}],
   };
 }

package/src/presentation/routes/webhooks.ts

@@ -1,24 +1,24 @@
-import {Buffer} from 'node:buffer';
+import {randomUUID} from 'node:crypto';
 import type {
   GetIntegrationConnectionByIdFn,
   PublishSourcePushFn,
   RecordDeliveryOnlyFn,
+  StoredWebhookRequest,
+  WebhookProcessingResult,
 } from '@shipfox/api-integration-core-dto';
 import {
+  createStoredWebhookRequest,
+  WEBHOOK_MAX_RAW_BODY_BYTES,
+} from '@shipfox/api-integration-core-dto';
+import {
+  ClientError,
   defineRoute,
   type RouteGroup,
   rawBodyPlugin,
-  verifyHexHmacSignature,
   WEBHOOK_BODY_LIMIT,
 } from '@shipfox/node-fastify';
-import {logger} from '@shipfox/node-opentelemetry';
 import type {NodePgDatabase} from 'drizzle-orm/node-postgres';
-import {config} from '#config.js';
-import {
-  GiteaWebhookMalformedJsonError,
-  GiteaWebhookMalformedPushPayloadError,
-  handleGiteaWebhook,
-} from '#core/webhook.js';
+import {createGiteaWebhookProcessor, type GiteaWebhookProcessor} from '#core/webhook-processor.js';
 
 const SIGNATURE_HEADER = 'x-gitea-signature';
 const EVENT_HEADER = 'x-gitea-event';
@@ -29,9 +29,11 @@ export interface CreateGiteaWebhookRoutesOptions {
   publishSourcePush: PublishSourcePushFn;
   recordDeliveryOnly: RecordDeliveryOnlyFn;
   getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+  processor?: GiteaWebhookProcessor | undefined;
 }
 
 export function createGiteaWebhookRoutes(options: CreateGiteaWebhookRoutesOptions): RouteGroup {
+  const processor = options.processor ?? createGiteaWebhookProcessor(options);
   const pushRoute = defineRoute({
     method: 'POST',
     path: '/',
@@ -56,49 +58,18 @@ export function createGiteaWebhookRoutes(options: CreateGiteaWebhookRoutesOption
         return {error: 'missing X-Gitea-Event header'};
       }
 
-      const body = request.body;
-      if (!Buffer.isBuffer(body)) {
+      if (!(request.body instanceof Uint8Array)) {
         reply.code(400);
         return {error: 'expected raw JSON body'};
       }
-      const rawBody = body.toString('utf8');
-
-      if (!verifyHexHmacSignature({rawBody, signature, secret: config.GITEA_WEBHOOK_SECRET})) {
-        reply.code(401);
-        return {error: 'invalid signature'};
-      }
-
-      try {
-        await options.coreDb().transaction(async (tx) => {
-          await handleGiteaWebhook({
-            tx,
-            deliveryId,
-            event,
-            rawBody,
-            publishSourcePush: options.publishSourcePush,
-            recordDeliveryOnly: options.recordDeliveryOnly,
-            getIntegrationConnectionById: options.getIntegrationConnectionById,
-          });
-        });
-      } catch (error) {
-        if (error instanceof GiteaWebhookMalformedJsonError) {
-          logger().warn({deliveryId, err: error}, 'gitea webhook payload JSON parse failed');
-          reply.code(400);
-          return {error: 'malformed JSON'};
-        }
-        if (error instanceof GiteaWebhookMalformedPushPayloadError) {
-          logger().warn(
-            {deliveryId, issues: error.issues},
-            'gitea webhook push payload failed schema validation',
-          );
-          reply.code(400);
-          return {error: 'malformed push payload'};
-        }
-        throw error;
-      }
-
-      reply.code(204);
-      return null;
+      const result = await processor.process(
+        createGiteaStoredWebhookRequest({
+          body: request.body,
+          headers: request.headers,
+          rawQueryString: request.raw.url?.split('?')[1] ?? '',
+        }),
+      );
+      return sendGiteaWebhookResponse(reply, result);
     },
   });
 
@@ -109,3 +80,56 @@ export function createGiteaWebhookRoutes(options: CreateGiteaWebhookRoutesOption
     routes: [pushRoute],
   };
 }
+
+function createGiteaStoredWebhookRequest(input: {
+  body: Uint8Array;
+  headers: Record<string, string | string[] | undefined>;
+  rawQueryString: string;
+}): StoredWebhookRequest {
+  if (input.body.byteLength > WEBHOOK_MAX_RAW_BODY_BYTES) {
+    throw new ClientError('Webhook request body is too large', 'body-too-large', {status: 413});
+  }
+  try {
+    return createStoredWebhookRequest({
+      requestId: randomUUID(),
+      routeId: 'gitea',
+      receivedAt: new Date().toISOString(),
+      rawQueryString: input.rawQueryString,
+      headers: giteaWebhookHeaders(input.headers),
+      body: input.body,
+    });
+  } catch (error) {
+    throw new ClientError('Webhook request metadata is invalid', 'invalid-webhook-request', {
+      cause: error,
+    });
+  }
+}
+
+function giteaWebhookHeaders(headers: Record<string, string | string[] | undefined>) {
+  return Object.fromEntries(
+    ['content-type', DELIVERY_HEADER, EVENT_HEADER, SIGNATURE_HEADER].flatMap((name) => {
+      const value = headers[name];
+      return typeof value === 'string' ? [[name, value]] : [];
+    }),
+  );
+}
+
+function sendGiteaWebhookResponse(
+  reply: {code(statusCode: number): void},
+  result: WebhookProcessingResult,
+) {
+  if (result.outcome === 'discarded' && result.reason === 'invalid_signature') {
+    reply.code(401);
+    return {error: 'invalid signature'};
+  }
+  if (result.outcome === 'discarded' && result.reason === 'malformed_payload') {
+    reply.code(400);
+    return {error: 'malformed JSON'};
+  }
+  if (result.outcome === 'discarded' && result.reason === 'unsupported_event') {
+    reply.code(400);
+    return {error: 'malformed push payload'};
+  }
+  reply.code(204);
+  return null;
+}