create-feedbax 0.1.0 → 0.2.1

package/template/src/trusted-feedback-handler.test.ts

@@ -0,0 +1,425 @@
+import {
+  createFeedbackModule,
+  createNotionFeedbackModule,
+  type FeedbackPropertyIds,
+} from "@feedbax/feedback";
+import { describe, expect, it, vi } from "vitest";
+
+import { createTrustedFeedbackHandler } from "./trusted-feedback-handler";
+import { createPortalServerEntry } from "./portal-server-entry";
+
+const propertyIds: FeedbackPropertyIds = {
+  title: "title-id",
+  slug: "slug-id",
+  description: "description-id",
+  type: "type-id",
+  status: "status-id",
+  published: "published-id",
+  voteCount: "vote-count-id",
+  teamResponse: "team-response-id",
+  releaseNotesUrl: "release-notes-url-id",
+  submitterName: "submitter-name-id",
+  submitterEmail: "submitter-email-id",
+  source: "source-id",
+  externalId: "external-id",
+  editTokenHash: "edit-token-hash-id",
+  createdAt: "created-at-id",
+  updatedAt: "updated-at-id",
+};
+
+describe("trusted feedback Worker handler", () => {
+  it("redirects equivalent public filter URLs to one canonical cache identity", async () => {
+    const applicationHandler = vi.fn(async () => new Response("public"));
+    const server = createPortalServerEntry({
+      trustedFeedbackHandler: vi.fn(),
+      applicationHandler,
+    });
+
+    const response = await server.fetch(
+      new Request(
+        "https://feedback.example.com/?type=Bug%20Report&status=New&ignored=value",
+      ),
+    );
+
+    expect(response.status).toBe(308);
+    expect(response.headers.get("location")).toBe(
+      "https://feedback.example.com/?types=%5B%22Bug+Report%22%5D&statuses=%5B%22New%22%5D&pageSize=25&sort=top&schema=2",
+    );
+    expect(applicationHandler).not.toHaveBeenCalled();
+  });
+
+  it("serves minimal deployment health without invoking application handlers", async () => {
+    const server = createPortalServerEntry({
+      trustedFeedbackHandler: async () => {
+        throw new Error("Health dispatch reached the trusted handler.");
+      },
+    });
+
+    const response = await server.fetch(
+      new Request("https://feedback.example.com/health"),
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    await expect(response.json()).resolves.toEqual({ status: "ok" });
+  });
+
+  it("serves the trusted POST contract through the production server-entry dispatch", async () => {
+    const server = createPortalServerEntry({
+      trustedFeedbackHandler: createTrustedFeedbackHandler({
+        ...trustedHandlerSecurity("correct-api-key"),
+        feedback: createFeedbackModule(),
+      }),
+    });
+
+    const response = await server.fetch(
+      trustedRequest({}, "product-a:feedback-123"),
+    );
+
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(body).toMatchObject({
+      title: "Keyboard navigation",
+      description: "Let users navigate without a mouse.",
+      type: "Feature Request",
+      status: "New",
+    });
+    expect(body).not.toHaveProperty("published");
+  });
+
+  it("rejects missing and invalid Bearer keys before any Notion request", async () => {
+    const notionRequest = vi.fn<typeof fetch>();
+    const handler = createTrustedFeedbackHandler({
+      ...trustedHandlerSecurity("correct-api-key"),
+      feedback: createNotionFeedbackModule({
+        token: "notion-token",
+        dataSourceId: "feedback-data-source",
+        propertyIds,
+        request: notionRequest,
+      }),
+    });
+    const body = JSON.stringify({
+      title: "Keyboard navigation",
+      description: "Let users navigate without a mouse.",
+      type: "Feature Request",
+    });
+
+    const missing = await handler(
+      new Request("https://feedback.example.com/api/v1/posts", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body,
+      }),
+    );
+    const invalid = await handler(
+      new Request("https://feedback.example.com/api/v1/posts", {
+        method: "POST",
+        headers: {
+          Authorization: "Bearer wrong-api-key",
+          "Content-Type": "application/json",
+        },
+        body,
+      }),
+    );
+
+    expect(missing.status).toBe(401);
+    expect(invalid.status).toBe(401);
+    await expect(missing.json()).resolves.toEqual({
+      error: "Unauthorized trusted submission.",
+    });
+    await expect(invalid.json()).resolves.toEqual({
+      error: "Unauthorized trusted submission.",
+    });
+    expect(notionRequest).not.toHaveBeenCalled();
+  });
+
+  it("requires and honors Idempotency-Key by returning the original Post", async () => {
+    const page = notionPage({
+      title: "Keyboard navigation",
+      description: "Let users navigate without a mouse.",
+      type: "Feature Request",
+      externalId: "product-a:feedback-123",
+    });
+    const notionRequest = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(
+        Response.json({ results: [], has_more: false, next_cursor: null }),
+      )
+      .mockResolvedValueOnce(
+        Response.json({ results: [], has_more: false, next_cursor: null }),
+      )
+      .mockResolvedValueOnce(Response.json(page))
+      .mockResolvedValueOnce(
+        Response.json({ results: [page], has_more: false, next_cursor: null }),
+      );
+    const handler = createTrustedFeedbackHandler({
+      ...trustedHandlerSecurity("correct-api-key"),
+      feedback: createNotionFeedbackModule({
+        token: "notion-token",
+        dataSourceId: "feedback-data-source",
+        propertyIds,
+        request: notionRequest,
+      }),
+    });
+
+    const missingKey = await handler(trustedRequest({}));
+    const first = await handler(trustedRequest({}, "product-a:feedback-123"));
+    const retried = await handler(
+      trustedRequest(
+        {
+          title: "A changed retry must not overwrite the original",
+          type: "Bug Report",
+        },
+        "product-a:feedback-123",
+      ),
+    );
+
+    expect(missingKey.status).toBe(400);
+    await expect(missingKey.json()).resolves.toEqual({
+      error: "Idempotency-Key header is required.",
+    });
+    expect(first.status).toBe(200);
+    expect(retried.status).toBe(200);
+    const firstBody = await first.json();
+    const retriedBody = await retried.json();
+    expect(retriedBody).toEqual(firstBody);
+    expect(firstBody).not.toHaveProperty("published");
+    expect(firstBody).not.toHaveProperty("submitter");
+    expect(notionRequest).toHaveBeenCalledTimes(4);
+    expect(
+      notionRequest.mock.calls.filter(([url]) =>
+        String(url).endsWith("/pages"),
+      ),
+    ).toHaveLength(1);
+    const [lookupUrl, lookupInit] = notionRequest.mock.calls[0]!;
+    expect(String(lookupUrl)).toBe(
+      "https://api.notion.com/v1/data_sources/feedback-data-source/query",
+    );
+    expect(JSON.parse(String(lookupInit?.body))).toEqual({
+      page_size: 1,
+      filter: {
+        property: "external-id",
+        rich_text: { equals: "product-a:feedback-123" },
+      },
+    });
+    const createInit = notionRequest.mock.calls[2]?.[1];
+    const createBody = JSON.parse(String(createInit?.body)) as {
+      properties: Record<string, unknown>;
+    };
+    expect(createBody.properties).toMatchObject({
+      "source-id": { select: { name: "API" } },
+      "external-id": {
+        rich_text: [
+          {
+            type: "text",
+            text: { content: "product-a:feedback-123" },
+          },
+        ],
+      },
+      "edit-token-hash-id": { rich_text: [] },
+    });
+  });
+
+  it("rejects out-of-bounds trusted input before any Notion request", async () => {
+    const notionRequest = vi.fn<typeof fetch>();
+    const handler = createTrustedFeedbackHandler({
+      ...trustedHandlerSecurity("correct-api-key"),
+      feedback: createNotionFeedbackModule({
+        token: "notion-token",
+        dataSourceId: "feedback-data-source",
+        propertyIds,
+        request: notionRequest,
+      }),
+    });
+    const requests = [
+      trustedRequest({ title: "" }, "valid-key"),
+      trustedRequest({ title: "t".repeat(161) }, "valid-key"),
+      trustedRequest({ description: "" }, "valid-key"),
+      trustedRequest({ description: "d".repeat(5_001) }, "valid-key"),
+      trustedRequest({ submitter: { name: "n".repeat(201) } }, "valid-key"),
+      trustedRequest({ submitter: { email: "e".repeat(321) } }, "valid-key"),
+      trustedRequest({}, "k".repeat(201)),
+      trustedRequest({ ignored: "x".repeat(20_000) }, "valid-key"),
+    ];
+
+    const responses = await Promise.all(requests.map(handler));
+
+    expect(responses.map(({ status }) => status)).toEqual(
+      Array(requests.length).fill(400),
+    );
+    for (const response of responses) {
+      await expect(response.json()).resolves.toEqual({
+        error: "Trusted submission exceeds an accepted bound.",
+      });
+    }
+    expect(notionRequest).not.toHaveBeenCalled();
+  });
+
+  it("does not log or serialize API keys and private submission fields on failure", async () => {
+    const notionRequest = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(
+        Response.json(
+          { object: "error", message: "private Notion diagnostic" },
+          { status: 500 },
+        ),
+      );
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const consoleLog = vi.spyOn(console, "log").mockImplementation(() => {});
+    const handler = createTrustedFeedbackHandler({
+      ...trustedHandlerSecurity("plaintext-api-key"),
+      feedback: createNotionFeedbackModule({
+        token: "notion-token",
+        dataSourceId: "feedback-data-source",
+        propertyIds,
+        request: notionRequest,
+      }),
+    });
+    const request = new Request("https://feedback.example.com/api/v1/posts", {
+      method: "POST",
+      headers: {
+        Authorization: "Bearer plaintext-api-key",
+        "Content-Type": "application/json",
+        "Idempotency-Key": "private-external-id",
+      },
+      body: JSON.stringify({
+        title: "private title",
+        description: "private description",
+        type: "General Feedback",
+        submitter: { email: "private@example.com" },
+      }),
+    });
+
+    const response = await handler(request);
+    const serialized = await response.text();
+
+    expect(response.status).toBe(502);
+    expect(serialized).toBe('{"error":"Trusted submission failed."}');
+    expect(serialized).not.toContain("plaintext-api-key");
+    expect(serialized).not.toContain("private title");
+    expect(serialized).not.toContain("private@example.com");
+    expect(consoleError).not.toHaveBeenCalled();
+    expect(consoleLog).not.toHaveBeenCalled();
+    consoleError.mockRestore();
+    consoleLog.mockRestore();
+  });
+
+  it("rate-limits by API-key hash before any Notion request", async () => {
+    const notionRequest = vi.fn<typeof fetch>();
+    const rateLimiter = {
+      limit: vi.fn().mockResolvedValue({ success: false }),
+    };
+    const apiKeyHash = hashApiKey("correct-api-key");
+    const handler = createTrustedFeedbackHandler({
+      apiKeyHash,
+      rateLimiter,
+      limits: { maxTitleLength: 160, maxDescriptionLength: 5_000 },
+      feedback: createNotionFeedbackModule({
+        token: "notion-token",
+        dataSourceId: "feedback-data-source",
+        propertyIds,
+        request: notionRequest,
+      }),
+    });
+
+    const response = await handler(trustedRequest({}, "valid-key"));
+
+    expect(response.status).toBe(429);
+    await expect(response.json()).resolves.toEqual({
+      error: "Trusted submission rate limit exceeded.",
+    });
+    expect(rateLimiter.limit).toHaveBeenCalledWith({ key: apiKeyHash });
+    expect(rateLimiter.limit).not.toHaveBeenCalledWith({
+      key: "correct-api-key",
+    });
+    expect(notionRequest).not.toHaveBeenCalled();
+  });
+});
+
+function trustedHandlerSecurity(apiKey: string) {
+  return {
+    apiKeyHash: hashApiKey(apiKey),
+    rateLimiter: {
+      limit: vi.fn().mockResolvedValue({ success: true }),
+    },
+    limits: { maxTitleLength: 160, maxDescriptionLength: 5_000 },
+  };
+}
+
+function hashApiKey(apiKey: string): string {
+  return createHash("sha256").update(apiKey).digest("base64url");
+}
+
+function trustedRequest(
+  overrides: Record<string, unknown>,
+  idempotencyKey?: string,
+): Request {
+  return new Request("https://feedback.example.com/api/v1/posts", {
+    method: "POST",
+    headers: {
+      Authorization: "Bearer correct-api-key",
+      "Content-Type": "application/json",
+      ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
+    },
+    body: JSON.stringify({
+      title: "Keyboard navigation",
+      description: "Let users navigate without a mouse.",
+      type: "Feature Request",
+      submitter: { name: "Ama", email: "ama@example.com" },
+      ...overrides,
+    }),
+  });
+}
+
+function notionPage({
+  title,
+  description,
+  type,
+  externalId,
+}: {
+  title: string;
+  description: string;
+  type: "Feature Request" | "Bug Report" | "General Feedback";
+  externalId: string;
+}) {
+  return {
+    object: "page",
+    id: "notion-page-id",
+    created_time: "2026-08-20T13:00:00.000Z",
+    last_edited_time: "2026-08-20T13:00:00.000Z",
+    properties: {
+      Title: { id: "title-id", title: [{ plain_text: title }] },
+      Slug: {
+        id: "slug-id",
+        rich_text: [{ plain_text: "keyboard-navigation" }],
+      },
+      Description: {
+        id: "description-id",
+        rich_text: [{ plain_text: description }],
+      },
+      Type: { id: "type-id", select: { name: type } },
+      Status: { id: "status-id", select: { name: "New" } },
+      Published: { id: "published-id", checkbox: false },
+      "Vote Count": { id: "vote-count-id", number: 0 },
+      "Team Response": { id: "team-response-id", rich_text: [] },
+      "Release Notes URL": { id: "release-notes-url-id", url: null },
+      "Submitter Name": {
+        id: "submitter-name-id",
+        rich_text: [{ plain_text: "Ama" }],
+      },
+      "Submitter Email": {
+        id: "submitter-email-id",
+        email: "ama@example.com",
+      },
+      Source: { id: "source-id", select: { name: "API" } },
+      "External ID": {
+        id: "external-id",
+        rich_text: [{ plain_text: externalId }],
+      },
+      "Edit Token Hash": { id: "edit-token-hash-id", rich_text: [] },
+    },
+  };
+}
+import { createHash } from "node:crypto";

package/template/src/trusted-feedback-handler.ts

@@ -0,0 +1,181 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
+import type { FeedbackModule } from "@feedbax/feedback";
+import type { PostType, SubmitTrustedPostInput } from "@feedbax/feedback";
+
+const FIXED_TRUSTED_SUBMISSION_BOUNDS = {
+  submitterName: 200,
+  submitterEmail: 320,
+  idempotencyKey: 200,
+  bodyBytes: 16 * 1_024,
+} as const;
+
+export interface TrustedSubmissionRateLimiter {
+  limit(options: { key: string }): Promise<{ success: boolean }>;
+}
+
+interface TrustedFeedbackHandlerOptions {
+  apiKeyHash: string;
+  feedback: Pick<FeedbackModule, "submitTrustedPost">;
+  rateLimiter: TrustedSubmissionRateLimiter;
+  limits: {
+    maxTitleLength: number;
+    maxDescriptionLength: number;
+  };
+}
+
+export function createTrustedFeedbackHandler({
+  apiKeyHash,
+  feedback,
+  rateLimiter,
+  limits,
+}: TrustedFeedbackHandlerOptions): (request: Request) => Promise<Response> {
+  return async (request) => {
+    if (!hasValidBearerKey(request.headers.get("Authorization"), apiKeyHash)) {
+      return jsonResponse(401, { error: "Unauthorized trusted submission." });
+    }
+
+    try {
+      const { success } = await rateLimiter.limit({ key: apiKeyHash });
+      if (!success) {
+        return jsonResponse(429, {
+          error: "Trusted submission rate limit exceeded.",
+        });
+      }
+    } catch {
+      return jsonResponse(503, { error: "Trusted submission is unavailable." });
+    }
+
+    const idempotencyKey = request.headers.get("Idempotency-Key")?.trim();
+    if (!idempotencyKey) {
+      return jsonResponse(400, {
+        error: "Idempotency-Key header is required.",
+      });
+    }
+    if (
+      idempotencyKey.length > FIXED_TRUSTED_SUBMISSION_BOUNDS.idempotencyKey
+    ) {
+      return boundsError();
+    }
+
+    const input = await readTrustedSubmission(request, idempotencyKey, limits);
+    if (input instanceof Response) return input;
+
+    try {
+      const item = await feedback.submitTrustedPost(input);
+      return jsonResponse(200, item);
+    } catch {
+      return jsonResponse(502, { error: "Trusted submission failed." });
+    }
+  };
+}
+
+async function readTrustedSubmission(
+  request: Request,
+  externalId: string,
+  limits: TrustedFeedbackHandlerOptions["limits"],
+): Promise<SubmitTrustedPostInput | Response> {
+  let body: unknown;
+  try {
+    const text = await request.text();
+    if (
+      new TextEncoder().encode(text).byteLength >
+      FIXED_TRUSTED_SUBMISSION_BOUNDS.bodyBytes
+    ) {
+      return boundsError();
+    }
+    body = JSON.parse(text) as unknown;
+  } catch {
+    return jsonResponse(400, { error: "Request body must be valid JSON." });
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return jsonResponse(400, { error: "Request body is invalid." });
+  }
+  const value = body as Record<string, unknown>;
+  if (
+    typeof value.title !== "string" ||
+    typeof value.description !== "string" ||
+    !isPostType(value.type)
+  ) {
+    return jsonResponse(400, { error: "Request body is invalid." });
+  }
+  if (
+    !hasBoundedRequiredText(value.title, limits.maxTitleLength) ||
+    !hasBoundedRequiredText(value.description, limits.maxDescriptionLength)
+  ) {
+    return boundsError();
+  }
+  const submitter = readSubmitter(value.submitter);
+  if (submitter instanceof Response) return submitter;
+  return {
+    externalId,
+    title: value.title,
+    description: value.description,
+    type: value.type,
+    ...(submitter ? { submitter } : {}),
+  };
+}
+
+function readSubmitter(
+  value: unknown,
+): SubmitTrustedPostInput["submitter"] | Response {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return jsonResponse(400, { error: "Request body is invalid." });
+  }
+  const submitter = value as Record<string, unknown>;
+  if (
+    (submitter.name !== undefined && typeof submitter.name !== "string") ||
+    (submitter.email !== undefined && typeof submitter.email !== "string")
+  ) {
+    return jsonResponse(400, { error: "Request body is invalid." });
+  }
+  if (
+    (typeof submitter.name === "string" &&
+      submitter.name.length > FIXED_TRUSTED_SUBMISSION_BOUNDS.submitterName) ||
+    (typeof submitter.email === "string" &&
+      submitter.email.length > FIXED_TRUSTED_SUBMISSION_BOUNDS.submitterEmail)
+  ) {
+    return boundsError();
+  }
+  return {
+    ...(typeof submitter.name === "string" ? { name: submitter.name } : {}),
+    ...(typeof submitter.email === "string" ? { email: submitter.email } : {}),
+  };
+}
+
+function hasBoundedRequiredText(value: string, maximum: number): boolean {
+  return value.trim().length > 0 && value.length <= maximum;
+}
+
+function boundsError(): Response {
+  return jsonResponse(400, {
+    error: "Trusted submission exceeds an accepted bound.",
+  });
+}
+
+function isPostType(value: unknown): value is PostType {
+  return (
+    value === "Feature Request" ||
+    value === "Bug Report" ||
+    value === "General Feedback"
+  );
+}
+
+function hasValidBearerKey(
+  authorization: string | null,
+  expectedApiKeyHash: string,
+): boolean {
+  if (!authorization?.startsWith("Bearer ")) return false;
+  const presentedApiKey = authorization.slice("Bearer ".length);
+  const expectedHash = Buffer.from(expectedApiKeyHash, "base64url");
+  const presentedHash = createHash("sha256").update(presentedApiKey).digest();
+  return (
+    expectedHash.length === presentedHash.length &&
+    timingSafeEqual(expectedHash, presentedHash)
+  );
+}
+
+function jsonResponse(status: number, body: unknown): Response {
+  return Response.json(body, { status });
+}

package/template/src/trusted-feedback-runtime.ts

@@ -0,0 +1,17 @@
+import { env } from "cloudflare:workers";
+
+import {
+  createConfiguredFeedbackModule,
+  feedbackSubmissionLimits,
+  requiredEnvironmentValue,
+} from "./feedback-runtime";
+import { createTrustedFeedbackHandler } from "./trusted-feedback-handler";
+
+export function createConfiguredTrustedFeedbackHandler() {
+  return createTrustedFeedbackHandler({
+    apiKeyHash: requiredEnvironmentValue("FEEDBAX_API_KEY_HASH"),
+    rateLimiter: env.TRUSTED_SUBMISSIONS_RATE_LIMITER,
+    limits: feedbackSubmissionLimits,
+    feedback: createConfiguredFeedbackModule(),
+  });
+}

package/template/src/turnstile-configuration.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import {
+  configuredTurnstileSecret,
+  configuredTurnstileSiteKey,
+} from "./turnstile-configuration";
+describe("typed Turnstile configuration", () => {
+  it("uses the public typed site key without a Vite environment variable", () => {
+    expect(
+      configuredTurnstileSiteKey({
+        enabled: true,
+        siteKey: "configured-public-key",
+      }),
+    ).toBe("configured-public-key");
+  });
+  it("disables browser widgets and server verification together even when a secret remains", () => {
+    expect(
+      configuredTurnstileSiteKey({ enabled: false, siteKey: "old-key" }),
+    ).toBeUndefined();
+    expect(
+      configuredTurnstileSecret("retained-secret", { enabled: false }),
+    ).toBeUndefined();
+  });
+  it("fails closed when enabled verification lacks its secret", () => {
+    expect(() =>
+      configuredTurnstileSecret(undefined, {
+        enabled: true,
+        siteKey: "public-key",
+      }),
+    ).toThrow("TURNSTILE_SECRET_KEY is missing");
+    expect(
+      configuredTurnstileSecret(" private-secret ", {
+        enabled: true,
+        siteKey: "public-key",
+      }),
+    ).toBe("private-secret");
+  });
+});

package/template/src/turnstile-configuration.ts

@@ -0,0 +1,19 @@
+import type { FeedbaxConfig } from "@feedbax/config";
+import feedbax from "./feedbax";
+type TurnstileConfiguration = FeedbaxConfig["turnstile"];
+export function configuredTurnstileSiteKey(
+  config: TurnstileConfiguration = feedbax.turnstile,
+): string | undefined {
+  return config.enabled ? config.siteKey : undefined;
+}
+export function configuredTurnstileSecret(
+  secret: string | undefined,
+  config: TurnstileConfiguration = feedbax.turnstile,
+): string | undefined {
+  if (!config.enabled) return undefined;
+  if (!secret?.trim())
+    throw new Error(
+      "Turnstile is enabled but TURNSTILE_SECRET_KEY is missing.",
+    );
+  return secret.trim();
+}

package/template/src/use-media-query.ts

@@ -0,0 +1,17 @@
+import { useCallback, useSyncExternalStore } from "react";
+
+export function useMediaQuery(query: string): boolean {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (typeof window.matchMedia !== "function") return () => {};
+      const media = window.matchMedia(query);
+      media.addEventListener("change", onChange);
+      return () => media.removeEventListener("change", onChange);
+    },
+    [query],
+  );
+  const getSnapshot = () =>
+    typeof window.matchMedia === "function" && window.matchMedia(query).matches;
+
+  return useSyncExternalStore(subscribe, getSnapshot, () => false);
+}