chore: implement twilio-external-task Lambda [CHI-3955]

.github/workflows/config/lambda-environment-region-map.json

@@ -1,6 +1,7 @@
 {
   "account-scoped": { "development": ["us-east-1"], "staging": ["us-east-1", "eu-west-1"], "production": ["us-east-1", "eu-west-1", "ca-central-1"] },
   "scheduled-jobs-processor": { "development": ["us-east-1"], "staging": ["us-east-1", "eu-west-1"], "production": ["us-east-1", "eu-west-1", "ca-central-1"] },
+  "external-task": { "development": ["us-east-1"], "staging": ["us-east-1", "eu-west-1"], "production": ["us-east-1", "eu-west-1", "ca-central-1"] },
   "facebookCallback": { "development": ["us-east-1"], "staging": [], "production": ["us-east-1"] },
   "facebookSignin": { "development": ["us-east-1"], "staging": [], "production": ["us-east-1"] },
   "instagramWebhook": { "development": ["us-east-1"], "staging": [], "production": ["us-east-1"] },

.github/workflows/global-production-release-tag.yml

@@ -75,6 +75,7 @@ jobs:
         lambda_path:
           - account-scoped
           - scheduled-jobs-processor
+          - external-task
           - facebookCallback
           - facebookSignin
           - instagramWebhook

.github/workflows/global-qa-release-tag.yml

@@ -117,6 +117,7 @@ jobs:
         lambda_path:
           - account-scoped
           - scheduled-jobs-processor
+          - external-task
           - facebookCallback
           - facebookSignin
           - instagramWebhook

.github/workflows/twilio-lambda-ci.yml

@@ -76,6 +76,7 @@ jobs:
         lambda_path:
           - account-scoped
           - scheduled-jobs-processor
+          - external-task
           - facebookCallback
           - facebookSignin
           - instagramWebhook

.github/workflows/twilio-lambda-deploy-all.yml

@@ -55,6 +55,7 @@ jobs:
         lambda_path:
           - account-scoped
           - scheduled-jobs-processor
+          - external-task
           - facebookCallback
           - facebookSignin
           - instagramWebhook

.github/workflows/twilio-lambda-deploy.yml

@@ -32,6 +32,7 @@ on:
         options:
           - account-scoped
           - scheduled-jobs-processor
+          - external-task
           - facebookCallback
           - facebookSignin
           - instagramWebhook

lambdas/external-task/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@tech-matters/twilio-external-task",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test:e2e": "jest tests/e2e",
+    "docker:build": "docker build -t external-task --build-arg lambda_name=external-task --build-arg lambda_dir=. -f ../Dockerfile ../"
+  },
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@tsconfig/node22": "^22.0.0",
+    "@types/aws-lambda": "^8.10.108",
+    "@types/node": "^22.13.11",
+    "ts-node": "^10.9.1"
+  },
+  "dependencies": {
+    "@tech-matters/result-type": "^1.0.0",
+    "@tech-matters/ssm-cache": "^1.0.0",
+    "@tech-matters/twilio-configuration": "^1.0.0",
+    "@tech-matters/twilio-types": "^1.0.0",
+    "twilio": "^6.1.0"
+  }
+}

lambdas/external-task/src/index.ts

@@ -0,0 +1,193 @@
+/**
+ * Copyright (C) 2021-2025 Technology Matters
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see https://www.gnu.org/licenses/.
+ */
+
+import type { ALBEvent, ALBResult } from 'aws-lambda';
+import type { DocumentInstance } from 'twilio/lib/rest/sync/v1/service/document';
+import { isErr } from '@tech-matters/result-type';
+import {
+  getMasterWorkflowSid,
+  getSyncServiceSid,
+  getTwilioClient,
+  getWorkspaceSid,
+} from '@tech-matters/twilio-configuration';
+import { channelTypes } from '@tech-matters/twilio-types';
+import { authenticateWithExternalApiKey } from './requestValidator';
+
+const headers = {
+  'Content-Type': 'application/json',
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'POST,OPTIONS',
+  'Access-Control-Allow-Headers':
+    'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token',
+};
+
+const handleError = (message: string, error?: Error, statusCode = 500): ALBResult => {
+  if (error) {
+    console.error(message, error);
+  } else {
+    console.error(message);
+  }
+  return {
+    statusCode,
+    headers,
+    body: JSON.stringify({ message, error: error?.message }),
+  };
+};
+
+// TODO: factor out to share with account-scoped lambda?
+const parseBody = ({
+  body,
+  contentTypeHeader,
+  isBase64Encoded,
+}: {
+  contentTypeHeader: string | null;
+  body: string | null;
+  isBase64Encoded: boolean;
+}) => {
+  if (!body || !contentTypeHeader) {
+    return body;
+  }
+
+  // if (contentTypeHeader.includes('application/x-www-form-urlencoded')) {
+  //   if (isBase64Encoded) {
+  //     const data = Buffer.from(body, 'base64').toString();
+  //     return qs.parse(data);
+  //   }
+
+  //   return qs.parse(body);
+  // }
+
+  if (contentTypeHeader === 'application/json') {
+    if (isBase64Encoded) {
+      const data = Buffer.from(body, 'base64').toString();
+      return JSON.parse(data);
+    }
+
+    return JSON.parse(body || 'null');
+  }
+};
+
+export const handler = async (event: ALBEvent): Promise<ALBResult> => {
+  try {
+    console.debug('[SENSITIVE] triggered with event', event);
+
+    // TODO: validate API key
+    const validationResult = await authenticateWithExternalApiKey({ event });
+
+    if (isErr(validationResult)) {
+      return handleError(
+        validationResult.message,
+        validationResult.error.cause,
+        validationResult.error.statusCode,
+      );
+    }
+
+    const { accountSid } = validationResult.data;
+
+    if (event.httpMethod === 'POST') {
+      if (!event.body) {
+        return handleError('Event body is null or undefined', undefined, 400);
+      }
+
+      let dedupDocument: DocumentInstance | null = null;
+      const twilioClient = await getTwilioClient(accountSid);
+      const syncService = await getSyncServiceSid(accountSid);
+
+      try {
+        const body = parseBody({
+          body: event.body,
+          contentTypeHeader: event.headers?.['content-type'] || null,
+          isBase64Encoded: event.isBase64Encoded,
+        });
+        const externalId = body.externalId;
+        if (!externalId) {
+          const message = 'No externalId property found on payload';
+          return handleError(message, undefined, 400);
+        }
+
+        const dedupDocumentName = `external-task-${externalId}`;
+
+        console.debug(`Creating dedupDocument with name ${dedupDocumentName}`);
+        dedupDocument = await twilioClient.sync.v1
+          .services(syncService)
+          .documents.create({
+            ttl: 86400, // one day
+            uniqueName: dedupDocumentName,
+          });
+
+        const workspaceSid = await getWorkspaceSid(accountSid);
+        const workflowSid = await getMasterWorkflowSid(accountSid);
+        const createdTask = await twilioClient.taskrouter.v1
+          .workspaces(workspaceSid)
+          .tasks.create({
+            taskChannel: channelTypes.EXTERNAL_TASK,
+            workflowSid,
+            attributes: JSON.stringify({
+              external_task_attributes: { externalId },
+              from: 'Placeholder',
+              name: 'Placeholder',
+              channelType: channelTypes.EXTERNAL_TASK,
+              customChannelType: channelTypes.EXTERNAL_TASK,
+              ignoreAgent: '',
+              transferTargetType: '',
+            }),
+          });
+
+        console.debug('[SENSITIVE] Created external task', createdTask);
+
+        return {
+          statusCode: 200,
+          headers,
+          body: JSON.stringify({ taskSid: createdTask.sid }),
+        };
+      } catch (error) {
+        if (dedupDocument) {
+          try {
+            console.debug(`Removing dedupDocument ${JSON.stringify(dedupDocument)}`);
+            await twilioClient.sync.v1
+              .services(syncService)
+              .documents(dedupDocument.sid)
+              .remove();
+          } catch (err) {
+            console.error(`Failed removing dedupDocument`);
+          }
+        }
+
+        // bubble up
+        throw error;
+      }
+    }
+
+    if (event.httpMethod === 'OPTIONS') {
+      // Handle preflight CORS requests
+      return {
+        statusCode: 200,
+        headers,
+        body: '',
+      };
+    }
+
+    // Handle unsupported HTTP methods
+    return {
+      statusCode: 405,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ message: 'Error: Method Not Allowed' }),
+    };
+  } catch (error) {
+    const message = 'Error handling request';
+    return handleError(message, error as Error);
+  }
+};

lambdas/external-task/src/requestValidator.ts

@@ -0,0 +1,113 @@
+/**
+ * Copyright (C) 2021-2025 Technology Matters
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see https://www.gnu.org/licenses/.
+ */
+
+import { timingSafeEqual } from 'crypto';
+import { ALBEvent } from 'aws-lambda';
+import { isErr, newErr, newOk, Result } from '@tech-matters/result-type';
+import { getSsmParameter } from '@tech-matters/ssm-cache';
+import { getAccountSid } from '@tech-matters/twilio-configuration';
+import { AccountSID } from '@tech-matters/twilio-types';
+
+export type HttpError = {
+  statusCode: number;
+  cause?: Error;
+};
+export const ROUTE_PREFIX = '/lambda/twilio/external-task/';
+const getAccountSidFromPath = async (event: ALBEvent) => {
+  try {
+    if (event.path.startsWith(ROUTE_PREFIX)) {
+      const path = event.path.substring(ROUTE_PREFIX.length);
+      const [accountShortCode] = path.split('/'); // ignore anothing after account short code
+
+      if (!accountShortCode) {
+        const message = 'Missing account short code';
+        return newErr<HttpError>({
+          message,
+          error: { statusCode: 400 },
+        });
+      }
+
+      const accountSid = await getAccountSid(accountShortCode);
+      return newOk({ accountSid, accountShortCode });
+    }
+
+    const message = 'Invalid route prefix';
+    return newErr<HttpError>({
+      message,
+      error: { statusCode: 400 },
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return newErr<HttpError>({
+      message,
+      error: { statusCode: 500 },
+    });
+  }
+};
+
+export const authenticateWithExternalApiKey = async ({
+  event,
+}: {
+  event: ALBEvent;
+}): Promise<Result<HttpError, { accountSid: AccountSID; accountShortCode: string }>> => {
+  if (!event.headers) {
+    const message = 'Missing headers in request';
+    return newErr({ message, error: { statusCode: 400 } });
+  }
+
+  const {
+    headers: { authorization },
+  } = event;
+
+  if (!authorization || !authorization.startsWith('Basic')) {
+    const message = 'Invalid authorization header';
+    return newErr({ message, error: { statusCode: 400 } });
+  }
+
+  const result = await getAccountSidFromPath(event);
+
+  if (isErr(result)) {
+    return result;
+  }
+
+  const { accountSid } = result.data;
+  const externalTaskApiKeyParam = `/${process.env.NODE_ENV}/twilio/${accountSid}/external_task_api_key`;
+
+  try {
+    console.debug(`Authenticating against key ${externalTaskApiKeyParam} `);
+    const requestSecret = authorization.replace('Basic ', '');
+    const externalTaskApiKey = await getSsmParameter(externalTaskApiKeyParam);
+
+    const isStaticSecretValid =
+      externalTaskApiKey &&
+      requestSecret &&
+      timingSafeEqual(Buffer.from(requestSecret), Buffer.from(externalTaskApiKey));
+
+    if (isStaticSecretValid) {
+      console.debug(
+        `Successfully authenticated against static key ${externalTaskApiKeyParam}`,
+      );
+
+      return newOk(result.data);
+    }
+  } catch (err) {
+    const message = `Static key authentication failed for ${externalTaskApiKeyParam}`;
+    return newErr({ message, error: { statusCode: 403 } });
+  }
+
+  const message = 'Invalid state reached';
+  return newErr({ message, error: { statusCode: 500 } });
+};

lambdas/external-task/tsconfig.build.json

@@ -0,0 +1,12 @@
+// This file is copied to the lambda root at build time, so all paths are relative to the root
+{
+  "extends": "./tsconfig.base.json",
+  "files": [],
+  "references": [
+    { "path": "packages/result-type" },
+    { "path": "packages/ssm-cache" },
+    { "path": "packages/twilio-types" },
+    { "path": "packages/twilio-configuration" },
+    { "path": "external-task" }
+  ]
+}