feat(caretaker): implement Cloud Run webhook ingestion service

tools/caretaker-agent/cloudrun/ingestion-service/.dockerignore

@@ -0,0 +1,12 @@
+node_modules
+dist
+npm-debug.log
+.git
+.gitignore
+*.py
+*.pyc
+__pycache__
+requirements.txt
+project.toml
+**/*.test.ts
+

tools/caretaker-agent/cloudrun/ingestion-service/Dockerfile

@@ -0,0 +1,9 @@
+FROM node:20-slim
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+EXPOSE 8080
+CMD ["node", "dist/server.js"]
+

tools/caretaker-agent/cloudrun/ingestion-service/app.ts

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import express from 'express';
+import { PubSub } from '@google-cloud/pubsub';
+import dotenv from 'dotenv';
+import { Firestore } from '@google-cloud/firestore';
+import { verifyGithubSignature } from './auth/github.js';
+import { IssuesStore } from './db/issuesStore.js';
+
+interface GitHubWebhookPayload {
+  action?: string;
+  issue?: {
+    body?: string;
+    number?: number;
+    title?: string;
+  };
+  repository?: {
+    full_name?: string;
+  };
+  sender?: {
+    login?: string;
+  };
+}
+
+dotenv.config();
+
+const app = express();
+
+const projectId = process.env.PROJECT_ID;
+const topicId = process.env.TOPIC_ID;
+const githubWebhookSecret = process.env.GITHUB_WEBHOOK_SECRET;
+const databaseId = process.env.FIRESTORE_DATABASE;
+const collectionName = process.env.FIRESTORE_COLLECTION;
+
+if (
+  !projectId ||
+  !topicId ||
+  !githubWebhookSecret ||
+  !databaseId ||
+  !collectionName
+) {
+  throw new Error('Missing required environment variables');
+}
+
+const pubSubClient = new PubSub({ projectId });
+const topic = pubSubClient.topic(topicId);
+
+const db = new Firestore({ projectId, databaseId });
+const issuesStore = new IssuesStore(db, collectionName);
+
+// Middleware: read incoming JSON payloads as raw Buffer bytes
+app.use(express.raw({ type: 'application/json', limit: '1mb' }));
+
+app.get('/', (req, res) => {
+  res.send('Hello World!');
+});
+
+app.post('/webhook', async (req, res) => {
+  const header = req.headers['x-hub-signature-256'];
+  const signature = Array.isArray(header) ? header[0] : header;
+
+  // Github Authentication
+  if (
+    !req.body ||
+    !verifyGithubSignature(req.body, signature, githubWebhookSecret)
+  ) {
+    console.error('Unauthorized: HMAC signature mismatch.');
+    return res
+      .status(401)
+      .json({ status: 'error', message: 'Invalid Signature' });
+  }
+
+  // Parse JSON payload
+  let payload: GitHubWebhookPayload;
+  try {
+    const parsed = JSON.parse(req.body.toString());
+    if (typeof parsed !== 'object' || parsed === null) {
+      throw new Error('Payload is not an object');
+    }
+    payload = parsed as GitHubWebhookPayload;
+  } catch {
+    return res
+      .status(400)
+      .json({ status: 'error', message: 'Invalid JSON payload' });
+  }
+
+  const eventType = req.headers['x-github-event'];
+  const action = payload.action;
+
+  // Only process issues.opened events
+  if (eventType !== 'issues' || action !== 'opened') {
+    return res.status(200).json({
+      status: 'ignored',
+      reason: `unsupported event/action combo: ${eventType}.${action}`,
+    });
+  }
+
+  const issueNumber = payload.issue?.number;
+  const repository = payload.repository?.full_name;
+
+  if (!issueNumber || !repository) {
+    return res
+      .status(400)
+      .json({ status: 'error', message: 'Missing issue number or repository' });
+  }
+
+  // Payload preprocessing
+  const rawBody = payload.issue?.body || '';
+  const escapedBody = rawBody.replace(
+    /<\/untrusted_context>/g,
+    '\\</untrusted_context>',
+  );
+  const sanitizedBody = `<untrusted_context>\n${escapedBody}\n</untrusted_context>`;
+
+  const processedData = {
+    issue_number: issueNumber,
+    repository: repository,
+    sender: payload.sender?.login,
+    body: sanitizedBody,
+    title: payload.issue?.title,
+  };
+
+  const [owner, repo] = repository.split('/');
+  const title = processedData.title || '';
+
+  try {
+    const created = await issuesStore.createIssue(
+      owner,
+      repo,
+      issueNumber,
+      title,
+    );
+
+    if (!created) {
+      // If the Firestore document already exists, check its status.
+      // If it is 'UNTRIAGED', we continue to publish to Pub/Sub
+      // to recover from previous publish failures.
+      const issueRef = issuesStore.getIssueRef(owner, repo, issueNumber);
+      const snapshot = await issueRef.get();
+      const status = snapshot.exists ? snapshot.data()?.status : null;
+      if (status !== 'UNTRIAGED') {
+        return res.status(200).json({
+          status: 'ignored',
+          reason: `issue already exists: ${repository}#${issueNumber}`,
+        });
+      }
+    }
+
+    // Publish to Pub/Sub
+    const dataBuffer = Buffer.from(JSON.stringify(processedData));
+    const messageId = await topic.publishMessage({ data: dataBuffer });
+
+    return res.status(202).json({ status: 'accepted', message_id: messageId });
+  } catch (error) {
+    console.error('Error processing webhook:', error);
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    return res.status(500).json({ status: 'error', message });
+  }
+});
+
+export { app };

tools/caretaker-agent/cloudrun/ingestion-service/auth/github.test.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { verifyGithubSignature } from './github.js';
+import * as crypto from 'node:crypto';
+
+describe('verifyGithubSignature', () => {
+  const secret = 'my-secret';
+  const payload = '{"test":true}';
+
+  it('should return true for a valid signature', () => {
+    const hmac = crypto.createHmac('sha256', secret);
+    hmac.update(payload);
+    const validSignature = 'sha256=' + hmac.digest('hex');
+
+    const result = verifyGithubSignature(payload, validSignature, secret);
+    expect(result).toBe(true);
+  });
+
+  it('should return false if signatureHeader is missing', () => {
+    const result = verifyGithubSignature(payload, undefined, secret);
+    expect(result).toBe(false);
+  });
+
+  it('should return false for an invalid signature', () => {
+    const result = verifyGithubSignature(
+      payload,
+      'sha256=invalid-signature',
+      secret,
+    );
+    expect(result).toBe(false);
+  });
+});

tools/caretaker-agent/cloudrun/ingestion-service/auth/github.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as crypto from 'node:crypto';
+
+/**
+ * Verify that the payload was sent from GitHub using HMAC SHA256.
+ *
+ * @param payloadBody - The raw body of the request (Buffer or string).
+ * @param signatureHeader - The value of the X-Hub-Signature-256 header.
+ * @param secret - The GitHub Webhook secret.
+ * @returns True if the signature is valid, false otherwise.
+ */
+export function verifyGithubSignature(
+  payloadBody: Buffer | string,
+  signatureHeader: string | undefined,
+  secret: string,
+): boolean {
+  if (!signatureHeader || signatureHeader.length !== 71) {
+    return false;
+  }
+
+  if (!Buffer.isBuffer(payloadBody) && typeof payloadBody !== 'string') {
+    return false;
+  }
+
+  const hmac = crypto.createHmac('sha256', secret);
+  hmac.update(payloadBody);
+  const expectedSignature = 'sha256=' + hmac.digest('hex');
+
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(expectedSignature),
+      Buffer.from(signatureHeader),
+    );
+  } catch {
+    return false;
+  }
+}

tools/caretaker-agent/cloudrun/ingestion-service/db/issuesStore.test.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { Mock } from 'vitest';
+import { IssuesStore } from './issuesStore.js';
+import { Firestore, Transaction } from '@google-cloud/firestore';
+
+describe('IssuesStore', () => {
+  let mockTransaction: {
+    get: Mock;
+    set: Mock;
+  };
+  let mockDb: Firestore;
+  let store: IssuesStore;
+
+  beforeEach(() => {
+    // Assign mock read/write methods for transaction
+    mockTransaction = {
+      get: vi.fn(),
+      set: vi.fn(),
+    };
+
+    // Mock Firestore client
+    mockDb = {
+      collection: vi.fn().mockReturnThis(),
+      doc: vi.fn().mockReturnValue({}),
+      runTransaction: vi
+        .fn()
+        .mockImplementation(
+          (callback: (tx: Transaction) => Promise<unknown>) => {
+            return callback(mockTransaction as unknown as Transaction);
+          },
+        ),
+    } as unknown as Firestore;
+
+    store = new IssuesStore(mockDb, 'issues-collection');
+  });
+
+  it('should initialize a new issue if it does not exist', async () => {
+    // The transaction should mock that the document does not exist
+    mockTransaction.get.mockResolvedValue({ exists: false });
+
+    const result = await store.createIssue(
+      'google',
+      'gemini-cli',
+      123,
+      'Test Title',
+    );
+
+    expect(result).toBe(true);
+    expect(mockTransaction.get).toHaveBeenCalled();
+    expect(mockTransaction.set).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        status: 'UNTRIAGED',
+        github_metadata: expect.objectContaining({
+          owner: 'google',
+          repo: 'gemini-cli',
+          issue_number: 123,
+          title: 'Test Title',
+        }),
+      }),
+    );
+  });
+
+  it('should return false and skip creation if the issue already exists', async () => {
+    // The transaction should mock that the document already exists
+    mockTransaction.get.mockResolvedValue({ exists: true });
+
+    const result = await store.createIssue(
+      'google',
+      'gemini-cli',
+      123,
+      'Test Title',
+    );
+
+    expect(result).toBe(false);
+    expect(mockTransaction.get).toHaveBeenCalled();
+    expect(mockTransaction.set).not.toHaveBeenCalled();
+  });
+});