@de-otio/trellis 0.4.0

package/dist/worker.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Compatibility shim — re-exports CorsHandler and AuthHandler helpers for
+ * route files that were written against the old Cloudflare Workers entry point.
+ *
+ * In the AWS architecture the entry point is server.ts (Node.js HTTP server).
+ * This file exists solely to avoid touching 17+ route files.
+ */
+import type { Env } from "./env";
+import type { RateLimiter } from "./lib/rate-limit";
+import type { SecurityHeaders } from "./lib/security-headers";
+import type { RequestContext } from "./lib/request-context";
+export declare const addCorsHeaders: (response: Response, request: Request, env: Env, requestContext?: RequestContext) => Promise<Response>;
+export declare const getAllowedOrigin: (request: Request, env: Env) => string | null;
+export declare const getCorsHeaders: (request: Request, env: Env) => Record<string, string>;
+export declare const handleAuthRoutes: (request: Request, env: Env, url: URL, rateLimiter: RateLimiter, securityHeaders: SecurityHeaders, requestContext?: RequestContext) => Promise<Response>;
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,eAAO,MAAM,cAAc,GACzB,UAAU,QAAQ,EAClB,SAAS,OAAO,EAChB,KAAK,GAAG,EACR,iBAAiB,cAAc,sBACsC,CAAC;AACxE,eAAO,MAAM,gBAAgB,GAAI,SAAS,OAAO,EAAE,KAAK,GAAG,kBAA+C,CAAC;AAC3G,eAAO,MAAM,cAAc,GAAI,SAAS,OAAO,EAAE,KAAK,GAAG,2BAA6C,CAAC;AAEvG,eAAO,MAAM,gBAAgB,GAC3B,SAAS,OAAO,EAChB,KAAK,GAAG,EACR,KAAK,GAAG,EACR,aAAa,WAAW,EACxB,iBAAiB,eAAe,EAChC,iBAAiB,cAAc,sBACiE,CAAC"}

package/dist/worker.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Compatibility shim — re-exports CorsHandler and AuthHandler helpers for
+ * route files that were written against the old Cloudflare Workers entry point.
+ *
+ * In the AWS architecture the entry point is server.ts (Node.js HTTP server).
+ * This file exists solely to avoid touching 17+ route files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAuthRoutes = exports.getCorsHeaders = exports.getAllowedOrigin = exports.addCorsHeaders = void 0;
+const auth_handler_1 = require("./lib/auth-handler");
+const cors_handler_1 = require("./lib/cors-handler");
+const addCorsHeaders = (response, request, env, requestContext) => cors_handler_1.CorsHandler.addCorsHeaders(response, request, env, requestContext);
+exports.addCorsHeaders = addCorsHeaders;
+const getAllowedOrigin = (request, env) => cors_handler_1.CorsHandler.getAllowedOrigin(request, env);
+exports.getAllowedOrigin = getAllowedOrigin;
+const getCorsHeaders = (request, env) => cors_handler_1.CorsHandler.getCorsHeaders(request, env);
+exports.getCorsHeaders = getCorsHeaders;
+const handleAuthRoutes = (request, env, url, rateLimiter, securityHeaders, requestContext) => auth_handler_1.AuthHandler.handleAuthRoutes(request, env, url, rateLimiter, securityHeaders, requestContext);
+exports.handleAuthRoutes = handleAuthRoutes;
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,qDAAiD;AACjD,qDAAiD;AAM1C,MAAM,cAAc,GAAG,CAC5B,QAAkB,EAClB,OAAgB,EAChB,GAAQ,EACR,cAA+B,EAC/B,EAAE,CAAC,0BAAW,CAAC,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC;AAL3D,QAAA,cAAc,kBAK6C;AACjE,MAAM,gBAAgB,GAAG,CAAC,OAAgB,EAAE,GAAQ,EAAE,EAAE,CAAC,0BAAW,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AAA9F,QAAA,gBAAgB,oBAA8E;AACpG,MAAM,cAAc,GAAG,CAAC,OAAgB,EAAE,GAAQ,EAAE,EAAE,CAAC,0BAAW,CAAC,cAAc,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AAA1F,QAAA,cAAc,kBAA4E;AAEhG,MAAM,gBAAgB,GAAG,CAC9B,OAAgB,EAChB,GAAQ,EACR,GAAQ,EACR,WAAwB,EACxB,eAAgC,EAChC,cAA+B,EAC/B,EAAE,CAAC,0BAAW,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,CAAC,CAAC;AAPtF,QAAA,gBAAgB,oBAOsE"}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@de-otio/trellis",
+  "version": "0.4.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "prisma",
+    "src/lambda"
+  ],
+  "scripts": {
+    "build": "tsc --build tsconfig.json",
+    "prepack": "node -e \"require('fs').cpSync('../../prisma','./prisma',{recursive:true})\"",
+    "postpack": "node -e \"require('fs').rmSync('./prisma',{recursive:true,force:true})\"",
+    "dev": "tsx watch src/server.ts",
+    "start": "node dist/server.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:graph": "vitest run --config vitest.graph.config.ts",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:e2e:smoke": "E2E_SHARD=smoke vitest run --config vitest.e2e.smoke.config.ts",
+    "test:e2e:crud": "E2E_SHARD=crud E2E_USER_COUNT=2 vitest run --config vitest.e2e.crud.config.ts",
+    "test:e2e:social": "E2E_SHARD=social E2E_USER_COUNT=2 vitest run --config vitest.e2e.social.config.ts",
+    "test:e2e:media": "E2E_SHARD=media E2E_USER_COUNT=1 vitest run --config vitest.e2e.media.config.ts",
+    "test:e2e:security": "E2E_SHARD=security E2E_USER_COUNT=1 vitest run --config vitest.e2e.security.config.ts",
+    "test:e2e:readonly": "E2E_SHARD=readonly E2E_USER_COUNT=1 vitest run --config vitest.e2e.readonly.config.ts",
+    "test:postdeployment": "vitest run --config vitest.postdeployment.config.ts",
+    "test:postdeployment:api": "vitest run --config vitest.postdeployment.api.config.ts",
+    "test:postdeployment:followers": "vitest run --config vitest.postdeployment.followers.config.ts",
+    "lint": "tsc --build --noEmit",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "prisma:generate": "prisma generate",
+    "prisma:migrate:dev": "prisma migrate dev",
+    "prisma:migrate:deploy": "prisma migrate deploy",
+    "seed:feature-toggles": "tsx scripts/seed-feature-toggles.ts"
+  },
+  "dependencies": {
+    "@aws-sdk/client-cloudwatch": "^3.1014.0",
+    "@aws-sdk/client-dynamodb": "^3.0.0",
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/client-secrets-manager": "^3.0.0",
+    "@aws-sdk/client-ses": "^3.0.0",
+    "@aws-sdk/client-sns": "^3.1012.0",
+    "@aws-sdk/client-sqs": "^3.0.0",
+    "@aws-sdk/client-ssm": "^3.0.0",
+    "@aws-sdk/s3-request-presigner": "^3.0.0",
+    "@aws-sdk/util-dynamodb": "^3.0.0",
+    "@fedify/fedify": "^1.0.0",
+    "@prisma/adapter-pg": "^6.0.0",
+    "@prisma/client": "^6.0.0",
+    "@prisma/extension-accelerate": "^1.0.0",
+    "@de-otio/trellis-extension-api": "^0.1.0",
+    "aws-jwt-verify": "^4.0.0",
+    "exifr": "^7.1.3",
+    "isomorphic-dompurify": "^2.18.0",
+    "js-yaml": "^4.1.1",
+    "pg": "^8.13.0",
+    "sharp": "^0.33.0",
+    "zod": "^3.23.8"
+  },
+  "prisma": {
+    "schema": "../../prisma/schema.prisma"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-bedrock-agent-runtime": "^3.0.0",
+    "@aws-sdk/client-cloudwatch-logs": "^3.0.0",
+    "@aws-sdk/client-cognito-identity-provider": "^3.1009.0",
+    "@aws-sdk/client-cost-explorer": "^3.0.0",
+    "@aws-sdk/client-ecs": "^3.0.0",
+    "@aws-sdk/client-lambda": "^3.0.0",
+    "@types/aws-lambda": "^8.10.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.18.0",
+    "@types/sharp": "^0.31.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "@vitest/ui": "^2.0.0",
+    "@aws-lambda-powertools/parameters": "^2.32.0",
+    "esbuild": "^0.27.0",
+    "form-data": "^4.0.1",
+    "mailparser": "^3.9.4",
+    "prettier": "^3.3.3",
+    "prisma": "^6.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/lambda/cleanup-cron.ts

@@ -0,0 +1,37 @@
+import { DynamoDBClient, DeleteItemCommand, QueryCommand } from "@aws-sdk/client-dynamodb";
+import { marshall } from "@aws-sdk/util-dynamodb";
+
+const dynamo = new DynamoDBClient({ region: process.env.AWS_REGION });
+const TABLE = process.env.DYNAMODB_TABLE!;
+
+export const handler = async (): Promise<void> => {
+  const now = Math.floor(Date.now() / 1000);
+
+  // DynamoDB TTL handles most cleanup automatically.
+  // This cron handles cleanup that TTL alone can't do.
+
+  // Acquire cron lock (prevent overlapping executions)
+  try {
+    await dynamo.send({
+      ...new (require("@aws-sdk/client-dynamodb").PutItemCommand)({
+        TableName: TABLE,
+        Item: marshall({
+          pk: "cron:cleanup",
+          sk: "lock",
+          ttl: now + 300, // 5 min TTL
+          lockedAt: now,
+        }),
+        ConditionExpression: "attribute_not_exists(pk) OR #ttl < :now",
+        ExpressionAttributeNames: { "#ttl": "ttl" },
+        ExpressionAttributeValues: marshall({ ":now": now }),
+      }),
+    });
+  } catch {
+    console.log(JSON.stringify({ level: "info", msg: "Cleanup cron already running, skipping" }));
+    return;
+  }
+
+  console.log(JSON.stringify({ level: "info", msg: "Cleanup cron started" }));
+  // Additional cleanup logic goes here
+  console.log(JSON.stringify({ level: "info", msg: "Cleanup cron complete" }));
+};

package/src/lambda/create-auth-challenge.ts

@@ -0,0 +1,112 @@
+import { randomBytes, createHash } from "node:crypto";
+import { DynamoDBClient, PutItemCommand, GetItemCommand, UpdateItemCommand } from "@aws-sdk/client-dynamodb";
+import { SESClient, SendEmailCommand } from "@aws-sdk/client-ses";
+
+const dynamo = new DynamoDBClient({ region: process.env.AWS_REGION });
+const ses = new SESClient({ region: process.env.SES_REGION || process.env.AWS_REGION });
+const TABLE = process.env.DYNAMODB_TABLE!;
+const DOMAIN = process.env.DOMAIN!;
+
+const RATE_LIMIT_MAX = 5;
+const RATE_LIMIT_WINDOW_SECONDS = 900; // 15 minutes
+
+export const handler = async (event: any) => {
+  const email = event.request.userAttributes?.email;
+  if (!email) {
+    throw new Error("Email attribute is required for magic link authentication");
+  }
+  const now = Math.floor(Date.now() / 1000);
+
+  // Bot protection is handled by AWS WAF at the infrastructure layer.
+  // Rate limiting below is defence-in-depth at the application level.
+  const ratePk = `magic-rate:${email}`;
+  try {
+    const rateResult = await dynamo.send(new GetItemCommand({
+      TableName: TABLE,
+      Key: { pk: { S: ratePk }, sk: { S: "v" } },
+    }));
+
+    if (rateResult.Item) {
+      const count = parseInt(rateResult.Item.count?.N || "0", 10);
+      const ttl = parseInt(rateResult.Item.ttl?.N || "0", 10);
+      if (count >= RATE_LIMIT_MAX && ttl > now) {
+        throw new Error("RATE_LIMIT_EXCEEDED: Too many magic link requests. Please wait before trying again.");
+      }
+    }
+
+    // Increment or create rate limit counter
+    await dynamo.send(new UpdateItemCommand({
+      TableName: TABLE,
+      Key: { pk: { S: ratePk }, sk: { S: "v" } },
+      UpdateExpression: "SET #count = if_not_exists(#count, :zero) + :one, #ttl = if_not_exists(#ttl, :ttl)",
+      ExpressionAttributeNames: { "#count": "count", "#ttl": "ttl" },
+      ExpressionAttributeValues: {
+        ":zero": { N: "0" },
+        ":one": { N: "1" },
+        ":ttl": { N: String(now + RATE_LIMIT_WINDOW_SECONDS) },
+      },
+    }));
+  } catch (err: any) {
+    if (err?.message?.startsWith("RATE_LIMIT_EXCEEDED")) {
+      throw err;
+    }
+    console.error("Rate limit check failed, proceeding with token generation", err);
+  }
+
+  const token = randomBytes(32).toString("base64url");
+
+  // S1.1 — Hash the token before storing in DynamoDB
+  const tokenHash = createHash("sha256").update(token).digest("hex");
+
+  // Store hashed token in DynamoDB with 5-minute TTL
+  try {
+    await dynamo.send(new PutItemCommand({
+      TableName: TABLE,
+      Item: {
+        pk: { S: `magic-link:${tokenHash}` },
+        sk: { S: "v" },
+        email: { S: email },
+        createdAt: { N: String(now) },
+        ttl: { N: String(now + 300) },
+      },
+    }));
+  } catch (err) {
+    console.error("Failed to store magic link token", err);
+    throw err;
+  }
+
+  // Send magic link email via SES
+  const magicLink = `https://${DOMAIN}/auth/verify?token=${token}&email=${encodeURIComponent(email)}`;
+  try {
+    await ses.send(new SendEmailCommand({
+      Source: `Trellis <noreply@${DOMAIN}>`,
+      Destination: { ToAddresses: [email] },
+      Message: {
+        Subject: { Data: "Sign in to Trellis" },
+        Body: {
+          Html: {
+            Data: `
+              <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 480px; margin: 0 auto; padding: 32px;">
+                <h2 style="color: #1a1a1a; margin-bottom: 24px;">Sign in to Trellis</h2>
+                <p style="color: #4a4a4a; font-size: 16px; line-height: 1.5;">Click the button below to sign in. This link expires in 5 minutes.</p>
+                <a href="${magicLink}" style="display: inline-block; background: #2563eb; color: #fff; padding: 14px 28px; border-radius: 8px; text-decoration: none; font-weight: 600; font-size: 16px; margin: 24px 0;">Sign in to Trellis</a>
+                <p style="color: #9a9a9a; font-size: 13px; margin-top: 32px;">If you didn't request this, you can safely ignore this email.</p>
+              </div>`,
+          },
+          Text: {
+            Data: `Sign in to Trellis\n\nClick this link to sign in (expires in 5 minutes):\n${magicLink}\n\nIf you didn't request this, ignore this email.`,
+          },
+        },
+      },
+    }));
+  } catch (err) {
+    console.error("Failed to send magic link email", err);
+    throw err;
+  }
+
+  event.response.privateChallengeParameters = { token };
+  event.response.publicChallengeParameters = { email };
+  event.response.challengeMetadata = "MAGIC_LINK";
+
+  return event;
+};

package/src/lambda/custom-message.ts

@@ -0,0 +1,30 @@
+import type { CustomMessageTriggerEvent, CustomMessageTriggerHandler } from "aws-lambda";
+
+const APP_DOMAIN = process.env.APP_DOMAIN || "example.com";
+
+export const handler: CustomMessageTriggerHandler = async (event) => {
+  const { codeParameter, usernameParameter } = event.request;
+
+  switch (event.triggerSource) {
+    case "CustomMessage_SignUp":
+    case "CustomMessage_ResendCode":
+      event.response.emailSubject = "Verify your Trellis account";
+      event.response.emailMessage = `
+        <p>Welcome to Trellis!</p>
+        <p>Your verification code is: <strong>${codeParameter}</strong></p>
+        <p>This code expires in 24 hours.</p>
+      `;
+      break;
+
+    case "CustomMessage_ForgotPassword":
+      event.response.emailSubject = "Reset your Trellis password";
+      event.response.emailMessage = `
+        <p>You requested a password reset.</p>
+        <p>Your reset code is: <strong>${codeParameter}</strong></p>
+        <p>If you didn't request this, you can safely ignore this email.</p>
+      `;
+      break;
+  }
+
+  return event;
+};

package/src/lambda/define-auth-challenge.ts

@@ -0,0 +1,24 @@
+export const handler = async (event: any) => {
+  const session = event.request.session;
+
+  if (session.length === 0) {
+    // No attempts yet — issue a custom challenge
+    event.response.issueTokens = false;
+    event.response.failAuthentication = false;
+    event.response.challengeName = "CUSTOM_CHALLENGE";
+  } else if (
+    session.length === 1 &&
+    session[0].challengeName === "CUSTOM_CHALLENGE" &&
+    session[0].challengeResult === true
+  ) {
+    // Challenge answered correctly — issue tokens
+    event.response.issueTokens = true;
+    event.response.failAuthentication = false;
+  } else {
+    // Unexpected state — fail
+    event.response.issueTokens = false;
+    event.response.failAuthentication = true;
+  }
+
+  return event;
+};

package/src/lambda/delete-account-worker.ts

@@ -0,0 +1,96 @@
+import type { SQSHandler } from "aws-lambda";
+import { PrismaClient } from "@prisma/client";
+import { S3Client, DeleteObjectsCommand, ListObjectsV2Command } from "@aws-sdk/client-s3";
+import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";
+import { CognitoIdentityProviderClient, AdminDeleteUserCommand } from "@aws-sdk/client-cognito-identity-provider";
+
+const s3 = new S3Client({ region: process.env.AWS_REGION });
+const secretsClient = new SecretsManagerClient({ region: process.env.AWS_REGION });
+
+const MAX_PAGES = 100;
+
+let prisma: PrismaClient | null = null;
+
+async function getPrisma(): Promise<PrismaClient> {
+  if (prisma) return prisma;
+  const secret = await secretsClient.send(new GetSecretValueCommand({ SecretId: process.env.DB_SECRET_ARN! }));
+  const { username, password, host, port, dbname } = JSON.parse(secret.SecretString!);
+  prisma = new PrismaClient({
+    datasources: { db: { url: `postgresql://${username}:${encodeURIComponent(password)}@${host}:${port}/${dbname}?connection_limit=1` } },
+  });
+  return prisma;
+}
+
+async function deleteUserMedia(userId: string, mediaBucket: string): Promise<void> {
+  const prefix = `originals/user-${userId}/`;
+  let continuationToken: string | undefined;
+  let pages = 0;
+  do {
+    if (pages >= MAX_PAGES) {
+      console.log(JSON.stringify({ level: "warn", msg: "S3 pagination circuit breaker hit", userId, pages: MAX_PAGES }));
+      break;
+    }
+    const list = await s3.send(new ListObjectsV2Command({
+      Bucket: mediaBucket, Prefix: prefix, ContinuationToken: continuationToken,
+    }));
+    if (list.Contents?.length) {
+      await s3.send(new DeleteObjectsCommand({
+        Bucket: mediaBucket,
+        Delete: { Objects: list.Contents.map((o) => ({ Key: o.Key! })) },
+      }));
+    }
+    continuationToken = list.NextContinuationToken;
+    pages++;
+  } while (continuationToken);
+}
+
+export const handler: SQSHandler = async (event) => {
+  const failedIds: string[] = [];
+  const db = await getPrisma();
+
+  for (const record of event.Records) {
+    try {
+      const { userId } = JSON.parse(record.body) as { userId: string };
+
+      // 1. Look up user email before deleting DB records (needed for Cognito)
+      const user = await db.user.findUnique({
+        where: { id: userId },
+        select: { email: true },
+      });
+
+      if (!user) {
+        console.log(JSON.stringify({ level: "warn", msg: "User not found, may already be deleted", userId }));
+        continue;
+      }
+
+      // 2. Delete all database records
+      const { deleteUserData } = await import("../lib/services/user-data-deletion");
+      const result = await deleteUserData(db, userId);
+
+      // 3. Delete S3 media files
+      await deleteUserMedia(userId, process.env.MEDIA_BUCKET_NAME!);
+
+      // 4. Delete Cognito identity
+      if (process.env.COGNITO_USER_POOL_ID) {
+        try {
+          const cognito = new CognitoIdentityProviderClient({ region: process.env.AWS_REGION });
+          await cognito.send(new AdminDeleteUserCommand({
+            UserPoolId: process.env.COGNITO_USER_POOL_ID,
+            Username: user.email,
+          }));
+        } catch (cognitoErr) {
+          console.warn(JSON.stringify({ level: "warn", msg: "Cognito deletion failed", userId, error: String(cognitoErr) }));
+        }
+      }
+
+      console.log(JSON.stringify({ level: "info", msg: "Account deleted", userId, itemsDeleted: result }));
+    } catch (err) {
+      console.error(JSON.stringify({ level: "error", msg: "Failed to delete account", err, messageId: record.messageId }));
+      failedIds.push(record.messageId);
+    }
+  }
+
+  if (failedIds.length > 0) {
+    return { batchItemFailures: failedIds.map((id) => ({ itemIdentifier: id })) };
+  }
+};

package/src/lambda/diagnostics-proxy.ts

@@ -0,0 +1,139 @@
+import {
+  DynamoDBClient,
+  PutItemCommand,
+  UpdateItemCommand,
+} from "@aws-sdk/client-dynamodb";
+
+const dynamo = new DynamoDBClient({ region: process.env.AWS_REGION });
+const RUNTIME_ID = process.env.RUNTIME_ID!;
+const TABLE = process.env.DYNAMODB_TABLE!;
+const MAX_DAILY = parseInt(process.env.MAX_DAILY_INVOCATIONS ?? "50", 10);
+const COOLDOWN_SECONDS = parseInt(process.env.COOLDOWN_SECONDS ?? "300", 10);
+
+function sanitizeAlarmName(raw: string): string {
+  // Truncate to 256 chars and strip non-printable characters
+  return raw.slice(0, 256).replace(/[^\x20-\x7E]/g, "");
+}
+
+function getDateKey(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+async function checkCooldown(alarmName: string): Promise<boolean> {
+  const now = Math.floor(Date.now() / 1000);
+  try {
+    await dynamo.send(
+      new PutItemCommand({
+        TableName: TABLE,
+        Item: {
+          pk: { S: `diag-cooldown:${alarmName}` },
+          sk: { S: "v" },
+          ttl: { N: String(now + COOLDOWN_SECONDS) },
+          createdAt: { N: String(now) },
+        },
+        ConditionExpression: "attribute_not_exists(pk) OR #t < :now",
+        ExpressionAttributeNames: { "#t": "ttl" },
+        ExpressionAttributeValues: { ":now": { N: String(now) } },
+      }),
+    );
+    return true; // cooldown acquired, OK to proceed
+  } catch (err: any) {
+    if (err.name === "ConditionalCheckFailedException") {
+      return false; // still in cooldown
+    }
+    throw err;
+  }
+}
+
+async function incrementDailyCounter(): Promise<number> {
+  const dateKey = getDateKey();
+  const ttl = Math.floor(Date.now() / 1000) + 86400 * 2; // 2-day TTL for cleanup
+
+  const result = await dynamo.send(
+    new UpdateItemCommand({
+      TableName: TABLE,
+      Key: {
+        pk: { S: `diag-daily:${dateKey}` },
+        sk: { S: "v" },
+      },
+      UpdateExpression: "SET #c = if_not_exists(#c, :zero) + :one, #t = :ttl",
+      ExpressionAttributeNames: { "#c": "count", "#t": "ttl" },
+      ExpressionAttributeValues: {
+        ":zero": { N: "0" },
+        ":one": { N: "1" },
+        ":ttl": { N: String(ttl) },
+      },
+      ReturnValues: "ALL_NEW",
+    }),
+  );
+
+  return parseInt(result.Attributes?.count?.N ?? "1", 10);
+}
+
+export const handler = async (event: { Records: any[] }) => {
+  for (const record of event.Records) {
+    const snsMessage = record.Sns?.Message;
+    if (!snsMessage) continue;
+
+    let alarm: any;
+    try {
+      alarm = JSON.parse(snsMessage);
+    } catch {
+      console.warn("Failed to parse SNS message as JSON, skipping");
+      continue;
+    }
+
+    // Only act on ALARM state transitions
+    if (alarm.NewStateValue !== "ALARM") {
+      console.log(`Skipping non-ALARM state: ${alarm.NewStateValue}`);
+      continue;
+    }
+
+    const rawAlarmName = alarm.AlarmName ?? "unknown";
+    const alarmName = sanitizeAlarmName(rawAlarmName);
+
+    // Per-alarm cooldown
+    const cooldownOk = await checkCooldown(alarmName);
+    if (!cooldownOk) {
+      console.log(`Alarm "${alarmName}" is in cooldown, skipping`);
+      continue;
+    }
+
+    // Daily invocation cap
+    const dailyCount = await incrementDailyCounter();
+    if (dailyCount > MAX_DAILY) {
+      console.warn(`Daily cap reached (${dailyCount}/${MAX_DAILY}), skipping`);
+      continue;
+    }
+
+    // Invoke the Bedrock AgentCore runtime
+    // TODO: Replace with exact SDK call once @aws-sdk/client-bedrock-agentcore is available.
+    // The InvokeAgentRuntime API shape may differ from the placeholder below.
+    try {
+      const { BedrockAgentRuntimeClient, InvokeAgentCommand } = await import(
+        "@aws-sdk/client-bedrock-agent-runtime"
+      );
+      const agentClient = new BedrockAgentRuntimeClient({ region: process.env.AWS_REGION });
+      await agentClient.send(
+        new InvokeAgentCommand({
+          agentId: RUNTIME_ID,
+          agentAliasId: "TSTALIASID",
+          sessionId: `diag-${alarmName}-${Date.now()}`,
+          inputText: JSON.stringify({
+            alarmName,
+            alarmDescription: alarm.AlarmDescription ?? "",
+            newStateReason: alarm.NewStateReason ?? "",
+            stateChangeTime: alarm.StateChangeTime ?? "",
+            trigger: alarm.Trigger ?? {},
+          }),
+        }),
+      );
+      console.log(`Invoked agent for alarm "${alarmName}"`);
+    } catch (err) {
+      console.error(`Failed to invoke agent for alarm "${alarmName}"`, err);
+      throw err;
+    }
+  }
+
+  return { processed: event.Records.length };
+};