Resolve release CodeQL findings (#39)

## What changed

- pin AWS integration credentials to the exact API Gateway ID and Region
returned for the ephemeral CloudFormation stack
- remove response bodies, API key identifiers, and arbitrary error
messages from cleanup logs
- read bounded template files through one `O_NOFOLLOW` file descriptor
for both metadata checks and content reads
- add endpoint-confusion regression tests and release notes

## Why

CodeQL's first scan of the complete v0.1.0 pull request identified three
new flows: a dynamic integration-test destination, clear-text cleanup
logging, and a `stat(path)` / `readFile(path)` race. Even though the
integration destination originates from a dedicated test stack, it
carries a bootstrap credential and should fail closed if the URL differs
from that exact stack. The logging and file race findings are actionable
directly.

## Impact

The AWS integration workflow now independently reads the `HttpApi`
physical ID and the script accepts only its exact commercial API Gateway
HTTPS hostname. Cleanup diagnostics remain useful without retaining
response bodies or key identifiers. Template manifest behavior is
unchanged, but the size/type check and read now operate on the same
opened file.

## Validation

- `npm run check`
- `npm test` — 22 files, 146 tests
- `npm run build`
- endpoint-confusion and bootstrap-key output probes
- `npm audit --omit=dev --audit-level=high` — 0 vulnerabilities
- `cfn-lint==1.53.2 template.yaml`
- Redocly 2.12.5 OpenAPI lint
- `actionlint`
- `gitleaks git --staged`
- signed commit with DCO sign-off

Closes CodeQL findings #3, #4, and #5 on release PR #30.

Signed-off-by: Yusuke Hayashi <yusuke8h@gmail.com>

Author: yhay81

.github/workflows/aws-integration.yml

@@ -121,12 +121,21 @@ jobs:
               --output text
           }
           api_base_url="$(stack_output ApiBaseUrl)"
+          http_api_id="$(
+            aws cloudformation describe-stack-resource \
+              --stack-name "$STACK_NAME" \
+              --logical-resource-id HttpApi \
+              --region "$AWS_REGION" \
+              --query StackResourceDetail.PhysicalResourceId \
+              --output text
+          )"
           bootstrap_secret_arn="$(stack_output BootstrapSecretArn)"
           payload_bucket="$(stack_output PayloadBucketName)"
           data_table="$(stack_output TableName)"
           schedule_group="$(stack_output EmailScheduleGroupName)"
           for value in \
             "$api_base_url" \
+            "$http_api_id" \
             "$bootstrap_secret_arn" \
             "$payload_bucket" \
             "$data_table" \
@@ -138,6 +147,7 @@ jobs:
           done
           {
             echo "API_BASE_URL=$api_base_url"
+            echo "HTTP_API_ID=$http_api_id"
             echo "BOOTSTRAP_SECRET_ARN=$bootstrap_secret_arn"
             echo "PAYLOAD_BUCKET=$payload_bucket"
             echo "DATA_TABLE=$data_table"
@@ -156,6 +166,7 @@ jobs:
           )"
           echo "::add-mask::$bootstrap_key"
           HAYASEND_BASE_URL="$API_BASE_URL" \
+          HAYASEND_EXPECTED_API_ID="$HTTP_API_ID" \
           HAYASEND_BOOTSTRAP_KEY="$bootstrap_key" \
           node scripts/aws-integration.mjs
 

CHANGELOG.md

@@ -20,6 +20,8 @@ No unreleased changes.
   lookup so unauthenticated input cannot turn storage limits into API errors.
 - Preflight every email in a strict batch before persisting or queueing any
   message, preventing partial sends when a template or attachment is invalid.
+- Pin integration credentials to the expected API Gateway endpoint, redact
+  cleanup failures, and read template files through race-safe descriptors.
 - Initial Resend-compatible sending, scheduling, receiving, webhook, and AWS
   deployment foundation.
 - Add Resend-compatible hosted templates with aliases, typed variables,

scripts/aws-integration-safety.d.mts

@@ -0,0 +1,5 @@
+export function normalizeApiGatewayBaseUrl(
+  value: string,
+  expectedApiId: string,
+  region: string,
+): string;

scripts/aws-integration-safety.mjs

@@ -0,0 +1,31 @@
+export function normalizeApiGatewayBaseUrl(value, expectedApiId, region) {
+  if (
+    !/^[a-z0-9]+$/.test(expectedApiId) ||
+    !/^[a-z]{2}(?:-[a-z0-9]+)+-[0-9]+$/.test(region)
+  ) {
+    throw new Error("The expected API Gateway identifier or Region is invalid.");
+  }
+  let endpoint;
+  try {
+    endpoint = new URL(value);
+  } catch {
+    throw new Error("HAYASEND_BASE_URL must be an absolute URL.");
+  }
+  const expectedHostname =
+    `${expectedApiId}.execute-api.${region}.amazonaws.com`;
+  if (
+    endpoint.protocol !== "https:" ||
+    endpoint.hostname !== expectedHostname ||
+    endpoint.port ||
+    endpoint.username ||
+    endpoint.password ||
+    endpoint.pathname !== "/" ||
+    endpoint.search ||
+    endpoint.hash
+  ) {
+    throw new Error(
+      "HAYASEND_BASE_URL must be the expected dedicated API Gateway endpoint.",
+    );
+  }
+  return `https://${expectedHostname}`;
+}

scripts/aws-integration.mjs

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
+import { normalizeApiGatewayBaseUrl } from "./aws-integration-safety.mjs";
 
 function requiredEnvironment(name) {
   const value = process.env[name];
@@ -9,7 +10,11 @@ function requiredEnvironment(name) {
   return value;
 }
 
-const baseUrl = requiredEnvironment("HAYASEND_BASE_URL").replace(/\/$/, "");
+const baseUrl = normalizeApiGatewayBaseUrl(
+  requiredEnvironment("HAYASEND_BASE_URL"),
+  requiredEnvironment("HAYASEND_EXPECTED_API_ID"),
+  requiredEnvironment("AWS_REGION"),
+);
 const bootstrapKey = requiredEnvironment("HAYASEND_BOOTSTRAP_KEY");
 const runId = (process.env.GITHUB_RUN_ID ?? String(Date.now())).replace(
   /[^a-zA-Z0-9-]/g,
@@ -35,7 +40,7 @@ async function api(
   const raw = await response.text();
   if (response.status !== expectedStatus) {
     throw new Error(
-      `${method} ${path} returned ${response.status}, expected ${expectedStatus}: ${raw.slice(0, 1_000)}`,
+      `${method} ${path} returned ${response.status}, expected ${expectedStatus}.`,
     );
   }
   return raw ? JSON.parse(raw) : undefined;
@@ -44,9 +49,8 @@ async function api(
 async function bestEffort(label, operation) {
   try {
     await operation();
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.warn(`Cleanup warning for ${label}: ${message}`);
+  } catch {
+    console.warn(`Cleanup warning: ${label} could not be removed.`);
   }
 }
 
@@ -280,7 +284,7 @@ try {
     );
   }
   for (const apiKeyId of created.apiKeyIds.reverse()) {
-    await bestEffort(`API key ${apiKeyId}`, () =>
+    await bestEffort("an API key", () =>
       api("DELETE", `/api-keys/${apiKeyId}`, bootstrapKey),
     );
   }

src/cli-templates.ts

@@ -1,4 +1,5 @@
-import { readFile, realpath, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { open, realpath } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { z } from "zod";
 import { createTemplateSchema } from "./schemas.js";
@@ -145,18 +146,23 @@ function formatZodError(error: z.ZodError) {
 }
 
 async function readBoundedFile(path: string, maximumBytes: number) {
-  const metadata = await stat(path);
-  if (!metadata.isFile()) {
-    throw new Error(`Expected a regular file: ${path}`);
-  }
-  if (metadata.size > maximumBytes) {
-    throw new Error(`File exceeds the ${maximumBytes}-byte limit: ${path}`);
-  }
-  const content = await readFile(path, "utf8");
-  if (Buffer.byteLength(content, "utf8") > maximumBytes) {
-    throw new Error(`File exceeds the ${maximumBytes}-byte limit: ${path}`);
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const metadata = await file.stat();
+    if (!metadata.isFile()) {
+      throw new Error(`Expected a regular file: ${path}`);
+    }
+    if (metadata.size > maximumBytes) {
+      throw new Error(`File exceeds the ${maximumBytes}-byte limit: ${path}`);
+    }
+    const content = await file.readFile({ encoding: "utf8" });
+    if (Buffer.byteLength(content, "utf8") > maximumBytes) {
+      throw new Error(`File exceeds the ${maximumBytes}-byte limit: ${path}`);
+    }
+    return content;
+  } finally {
+    await file.close();
   }
-  return content;
 }
 
 async function resolveContentFile(
@@ -260,7 +266,8 @@ export async function loadTemplateManifest(
   cwd: string,
   configuredPath = "hayasend.templates.json",
 ) {
-  const manifestPath = resolve(cwd, configuredPath);
+  const configuredManifestPath = resolve(cwd, configuredPath);
+  const manifestPath = await realpath(configuredManifestPath);
   const source = await readBoundedFile(manifestPath, MAX_MANIFEST_BYTES);
   let untrusted: unknown;
   try {
@@ -278,13 +285,13 @@ export async function loadTemplateManifest(
       `Template manifest is invalid: ${formatZodError(parsed.error)}`,
     );
   }
-  const root = await realpath(dirname(manifestPath));
+  const root = dirname(manifestPath);
   const templates = await Promise.all(
     parsed.data.templates.map((template) =>
       loadDesiredTemplate(root, template),
     ),
   );
-  return { path: manifestPath, templates };
+  return { path: configuredManifestPath, templates };
 }
 
 export function parseRemoteTemplate(value: unknown): RemoteTemplate {

tests/aws-integration-safety.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { normalizeApiGatewayBaseUrl } from "../scripts/aws-integration-safety.mjs";
+
+describe("AWS integration network safety", () => {
+  it("accepts only the expected regional API Gateway endpoint", () => {
+    expect(
+      normalizeApiGatewayBaseUrl(
+        "https://abc123def4.execute-api.ap-northeast-1.amazonaws.com/",
+        "abc123def4",
+        "ap-northeast-1",
+      ),
+    ).toBe(
+      "https://abc123def4.execute-api.ap-northeast-1.amazonaws.com",
+    );
+
+    for (const endpoint of [
+      "http://abc123def4.execute-api.ap-northeast-1.amazonaws.com",
+      "https://other12345.execute-api.ap-northeast-1.amazonaws.com",
+      "https://abc123def4.execute-api.us-east-1.amazonaws.com",
+      "https://abc123def4.execute-api.ap-northeast-1.amazonaws.com:444",
+      "https://user:secret@abc123def4.execute-api.ap-northeast-1.amazonaws.com",
+      "https://abc123def4.execute-api.ap-northeast-1.amazonaws.com/stage",
+      "https://abc123def4.execute-api.ap-northeast-1.amazonaws.com?target=other",
+      "https://abc123def4.execute-api.ap-northeast-1.amazonaws.com#fragment",
+      "https://abc123def4.execute-api.ap-northeast-1.amazonaws.com.attacker.example",
+    ]) {
+      expect(() =>
+        normalizeApiGatewayBaseUrl(
+          endpoint,
+          "abc123def4",
+          "ap-northeast-1",
+        ),
+      ).toThrow("expected dedicated API Gateway endpoint");
+    }
+  });
+
+  it("rejects malformed expected deployment identifiers", () => {
+    expect(() =>
+      normalizeApiGatewayBaseUrl(
+        "https://abc123def4.execute-api.ap-northeast-1.amazonaws.com",
+        "abc123def4.example",
+        "ap-northeast-1",
+      ),
+    ).toThrow("identifier or Region is invalid");
+    expect(() =>
+      normalizeApiGatewayBaseUrl(
+        "https://abc123def4.execute-api.ap-northeast-1.amazonaws.com",
+        "abc123def4",
+        "ap-northeast-1.amazonaws.com",
+      ),
+    ).toThrow("identifier or Region is invalid");
+  });
+});