create-feedbax 0.2.0 → 0.2.1

package/template/src/feedbax/feedback/connected.ts

@@ -0,0 +1,215 @@
+import type { D1Database } from "@cloudflare/workers-types";
+import { and, count, eq, gt, inArray } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/d1";
+import {
+  integer,
+  primaryKey,
+  sqliteTable,
+  text,
+} from "drizzle-orm/sqlite-core";
+
+export type ConnectedDatabase = D1Database;
+export interface VerifiedParticipant {
+  subject: string;
+  displayName: string;
+}
+const participants = sqliteTable("participants", {
+  subject: text("subject").primaryKey(),
+  displayName: text("display_name").notNull(),
+});
+const contacts = sqliteTable("participant_contacts", {
+  subject: text("subject").primaryKey(),
+  email: text("email"),
+  emailEnabled: integer("email_enabled").notNull().default(0),
+});
+const nonces = sqliteTable("identity_nonces", {
+  nonce: text("nonce").primaryKey(),
+  expiresAt: integer("expires_at").notNull(),
+});
+const sessions = sqliteTable("participant_sessions", {
+  tokenHash: text("token_hash").primaryKey(),
+  subject: text("subject")
+    .notNull()
+    .references(() => participants.subject),
+  expiresAt: integer("expires_at").notNull(),
+});
+const votes = sqliteTable(
+  "participant_votes",
+  {
+    postSlug: text("post_slug").notNull(),
+    subject: text("subject")
+      .notNull()
+      .references(() => participants.subject),
+  },
+  (t) => [primaryKey({ columns: [t.postSlug, t.subject] })],
+);
+const attribution = sqliteTable("comment_attribution", {
+  commentId: text("comment_id").primaryKey(),
+  subject: text("subject")
+    .notNull()
+    .references(() => participants.subject),
+  displayName: text("display_name").notNull(),
+});
+
+export function createConnectedStore(binding: D1Database) {
+  // Without read-replication sessions, D1 routes these queries to its primary.
+  const db = drizzle(binding);
+  return {
+    async acceptIdentity(
+      input: VerifiedParticipant & {
+        email?: string;
+        nonce: string;
+        challenge?: string;
+        sessionHash: string;
+        expiresAt: number;
+      },
+    ) {
+      // A nonce collision rolls the entire D1 batch back, including session creation.
+      await db.batch([
+        db.insert(nonces).values([
+          { nonce: `token:${input.nonce}`, expiresAt: input.expiresAt },
+          ...(input.challenge
+            ? [
+                {
+                  nonce: `browser:${input.challenge}`,
+                  expiresAt: input.expiresAt,
+                },
+              ]
+            : []),
+        ]),
+        db
+          .insert(participants)
+          .values({ subject: input.subject, displayName: input.displayName })
+          .onConflictDoUpdate({
+            target: participants.subject,
+            set: { displayName: input.displayName },
+          }),
+        db
+          .insert(contacts)
+          .values({ subject: input.subject, email: input.email ?? null })
+          .onConflictDoUpdate({
+            target: contacts.subject,
+            set: { email: input.email ?? null },
+          }),
+        db.insert(sessions).values({
+          tokenHash: input.sessionHash,
+          subject: input.subject,
+          expiresAt: input.expiresAt,
+        }),
+      ]);
+    },
+    async session(
+      tokenHash: string,
+      now = Date.now(),
+    ): Promise<VerifiedParticipant | undefined> {
+      return db
+        .select({
+          subject: participants.subject,
+          displayName: participants.displayName,
+        })
+        .from(sessions)
+        .innerJoin(participants, eq(participants.subject, sessions.subject))
+        .where(
+          and(eq(sessions.tokenHash, tokenHash), gt(sessions.expiresAt, now)),
+        )
+        .get();
+    },
+    async logout(tokenHash: string) {
+      await db.delete(sessions).where(eq(sessions.tokenHash, tokenHash));
+    },
+    async setVote(postSlug: string, subject: string, voted: boolean) {
+      if (voted)
+        await db
+          .insert(votes)
+          .values({ postSlug, subject })
+          .onConflictDoNothing();
+      else
+        await db
+          .delete(votes)
+          .where(and(eq(votes.postSlug, postSlug), eq(votes.subject, subject)));
+    },
+    async voteState(postSlug: string, subject?: string) {
+      const [total, own] = await db.batch([
+        db
+          .select({ value: count() })
+          .from(votes)
+          .where(eq(votes.postSlug, postSlug)),
+        db
+          .select({ subject: votes.subject })
+          .from(votes)
+          .where(
+            and(eq(votes.postSlug, postSlug), eq(votes.subject, subject ?? "")),
+          )
+          .limit(1),
+      ]);
+      return { voteCount: total[0]?.value ?? 0, voted: own.length > 0 };
+    },
+    async voteCounts(slugs: string[]) {
+      const result = new Map<string, number>();
+      for (let offset = 0; offset < slugs.length; offset += 80) {
+        const rows = await db
+          .select({ slug: votes.postSlug, total: count() })
+          .from(votes)
+          .where(inArray(votes.postSlug, slugs.slice(offset, offset + 80)))
+          .groupBy(votes.postSlug);
+        for (const row of rows) result.set(row.slug, row.total);
+      }
+      return result;
+    },
+    async commentSubject(commentId: string) {
+      return (
+        await db
+          .select({ subject: attribution.subject })
+          .from(attribution)
+          .where(eq(attribution.commentId, commentId))
+          .get()
+      )?.subject;
+    },
+    async attributeComment(
+      commentId: string,
+      participant: VerifiedParticipant,
+    ) {
+      await db.insert(attribution).values({
+        commentId,
+        subject: participant.subject,
+        displayName: participant.displayName,
+      });
+    },
+    async commentAuthors(ids: string[]) {
+      const result = new Map<
+        string,
+        { kind: "participant"; displayName: string; verified: true }
+      >();
+      for (let offset = 0; offset < ids.length; offset += 80) {
+        const rows = await db
+          .select()
+          .from(attribution)
+          .where(
+            inArray(attribution.commentId, ids.slice(offset, offset + 80)),
+          );
+        for (const row of rows)
+          result.set(row.commentId, {
+            kind: "participant",
+            displayName: row.displayName,
+            verified: true,
+          });
+      }
+      return result;
+    },
+    async commentAuthor(commentId: string) {
+      const row = await db
+        .select({ displayName: attribution.displayName })
+        .from(attribution)
+        .where(eq(attribution.commentId, commentId))
+        .get();
+      return row
+        ? {
+            kind: "participant" as const,
+            displayName: row.displayName,
+            verified: true as const,
+          }
+        : undefined;
+    },
+  };
+}
+export type ConnectedStore = ReturnType<typeof createConnectedStore>;

package/template/src/feedbax/feedback/email-delivery.test.ts

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import { expect, it } from "vitest";
+import { createFetchMock, Miniflare } from "miniflare";
+import ts from "typescript";
+
+it.each([200, 302])(
+  "sends email inside the actual Workers fetch runtime and rejects provider redirects (%s)",
+  async (status) => {
+    const source = await readFile(
+      new URL("./email-delivery.ts", import.meta.url),
+      "utf8",
+    );
+    const sender = ts.transpileModule(source, {
+      compilerOptions: {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.ESNext,
+      },
+    }).outputText;
+    const network = createFetchMock();
+    network.disableNetConnect();
+    network
+      .get("https://api.resend.com")
+      .intercept({ path: "/emails", method: "POST" })
+      .reply(status, "{}", {
+        headers:
+          status === 302 ? { location: "https://unexpected.example/leak" } : {},
+      });
+    let redirected = 0;
+    network
+      .get("https://unexpected.example")
+      .intercept({ path: "/leak", method: "GET" })
+      .reply(() => {
+        redirected++;
+        return { statusCode: 200, data: "{}" };
+      });
+    const runtime = new Miniflare({
+      compatibilityDate: "2026-07-30",
+      modulesRoot: "/email-worker",
+      fetchMock: network,
+      modules: [
+        {
+          type: "ESModule",
+          path: "/email-worker/entry.mjs",
+          contents: `import {createEmailSender} from './sender.mjs'; export default {async fetch(){ try {await createEmailSender({provider:'resend',token:'test-provider-key'})({from:'updates@example.com',to:['recipient@example.com'],subject:'Update',text:'A Post changed.',headers:{}},'test-stable-key');return new Response('accepted');}catch(error){return new Response(error.message,{status:502});}}};`,
+        },
+        {
+          type: "ESModule",
+          path: "/email-worker/sender.mjs",
+          contents: sender,
+        },
+      ],
+    });
+    try {
+      const response = await runtime.dispatchFetch(
+        "https://worker.example/send",
+      );
+      expect(await response.text()).not.toContain("test-provider-key");
+      expect(response.status).toBe(status === 200 ? 200 : 502);
+      expect(redirected).toBe(0);
+    } finally {
+      await runtime.dispose();
+      await network.close();
+    }
+  },
+);

package/template/src/feedbax/feedback/email-delivery.ts

@@ -0,0 +1,66 @@
+export interface NotificationEmail {
+  from: string;
+  to: string[];
+  subject: string;
+  text: string;
+  headers: Record<string, string>;
+}
+export type EmailSender = (
+  message: NotificationEmail,
+  deliveryKey: string,
+) => Promise<void>;
+export type CloudflareEmailBinding = {
+  send(message: NotificationEmail): Promise<unknown>;
+};
+
+/** The custom endpoint accepts the same JSON message as Resend and must honor Idempotency-Key. */
+export function createEmailSender(
+  options:
+    | { provider: "cloudflare"; binding: CloudflareEmailBinding }
+    | { provider: "resend"; token: string; request?: typeof fetch }
+    | {
+        provider: "custom";
+        url: string;
+        token: string;
+        request?: typeof fetch;
+      },
+): EmailSender {
+  if (options.provider === "cloudflare")
+    return async (message) => {
+      await options.binding.send(message);
+    };
+  const url =
+    options.provider === "resend"
+      ? "https://api.resend.com/emails"
+      : options.url;
+  const parsed = new URL(url);
+  if (
+    parsed.protocol !== "https:" ||
+    parsed.username ||
+    parsed.password ||
+    parsed.hash
+  )
+    throw new Error(
+      "Email sender requires an HTTPS endpoint without credentials or fragments.",
+    );
+  if (!options.token.trim()) throw new Error("Email sender secret is missing.");
+  return async (message, deliveryKey) => {
+    const response = await (options.request ?? fetch)(url, {
+      method: "POST",
+      // Workers supports manual/follow; manual also prevents forwarding credentials.
+      redirect: "manual",
+      signal: AbortSignal.timeout(10000),
+      headers: {
+        Authorization: `Bearer ${options.token}`,
+        "Content-Type": "application/json",
+        "Idempotency-Key": deliveryKey,
+      },
+      body: JSON.stringify(message),
+    });
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new Error("Email provider did not accept this delivery.");
+    }
+    await response.body?.cancel();
+  };
+}

package/template/src/feedbax/feedback/identity-handoff.test.ts

@@ -0,0 +1,81 @@
+import { expect, it } from "vitest";
+import { signIdentityHandoff, verifyIdentityHandoff } from "./identity-handoff";
+const secret = "test-secret-for-identity-handoff-32-bytes";
+const claims = {
+  subject: "alice",
+  displayName: "Alice",
+  audience: "https://feedback.example",
+  issuer: "https://app.example",
+  state: "browser-state",
+  nonce: "unique-nonce",
+  issuedAt: 1000,
+  expiresAt: 1100,
+};
+it("accepts only a signed identity bound to this Installation, browser and time", () => {
+  const token = signIdentityHandoff(claims, secret);
+  expect(
+    verifyIdentityHandoff(token, secret, {
+      audience: claims.audience,
+      issuer: claims.issuer,
+      state: claims.state,
+      now: 1020,
+    }),
+  ).toEqual(claims);
+  expect(() =>
+    verifyIdentityHandoff(token, secret, {
+      audience: "https://other.example",
+      issuer: claims.issuer,
+      state: claims.state,
+      now: 1020,
+    }),
+  ).toThrow();
+  expect(() =>
+    verifyIdentityHandoff(token, secret, {
+      audience: claims.audience,
+      issuer: claims.issuer,
+      state: "different-browser",
+      now: 1020,
+    }),
+  ).toThrow();
+  expect(() =>
+    verifyIdentityHandoff(token, secret, {
+      audience: claims.audience,
+      issuer: claims.issuer,
+      state: claims.state,
+      now: 1101,
+    }),
+  ).toThrow();
+  expect(() =>
+    verifyIdentityHandoff(token + "x", secret, {
+      audience: claims.audience,
+      issuer: claims.issuer,
+      state: claims.state,
+      now: 1020,
+    }),
+  ).toThrow();
+});
+
+it("accepts email delivery addresses only when the trusted application signs a verified assertion", () => {
+  const expected = {
+    audience: claims.audience,
+    issuer: claims.issuer,
+    state: claims.state,
+    now: 1020,
+  };
+  const verify = (value: Parameters<typeof signIdentityHandoff>[0]) =>
+    verifyIdentityHandoff(signIdentityHandoff(value, secret), secret, expected);
+  expect(
+    verify({ ...claims, email: "private@example.com" }),
+  ).not.toHaveProperty("email");
+  expect(
+    verify({ ...claims, email: "private@example.com", emailVerified: true }),
+  ).toMatchObject({ email: "private@example.com", emailVerified: true });
+  expect(() => verify({ ...claims, emailVerified: true })).toThrow();
+  expect(() =>
+    verify({
+      ...claims,
+      email: "bad\r\naddress@example.com",
+      emailVerified: true,
+    }),
+  ).toThrow();
+});

package/template/src/feedbax/feedback/identity-handoff.ts

@@ -0,0 +1,119 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export interface IdentityHandoff {
+  email?: string;
+  emailVerified?: boolean;
+  subject: string;
+  displayName: string;
+  issuer: string;
+  audience: string;
+  state: string;
+  nonce: string;
+  issuedAt: number;
+  expiresAt: number;
+}
+export function signIdentityHandoff(
+  claims: IdentityHandoff,
+  secret: string,
+): string {
+  requireSecret(secret);
+  const payload = Buffer.from(
+    JSON.stringify({ purpose: "feedbax-identity-v1", ...claims }),
+  ).toString("base64url");
+  return `${payload}.${signature(payload, secret)}`;
+}
+export function verifyIdentityHandoff(
+  token: string,
+  secret: string,
+  expected: { audience: string; issuer: string; state: string; now: number },
+): IdentityHandoff {
+  requireSecret(secret);
+  if (token.length > 8192) throw invalid();
+  const [payload, mac, extra] = token.split(".");
+  if (!payload || !mac || extra) throw invalid();
+  const received = Buffer.from(mac);
+  const wanted = Buffer.from(signature(payload, secret));
+  if (wanted.length !== received.length || !timingSafeEqual(wanted, received))
+    throw invalid();
+  let value: Record<string, unknown>;
+  try {
+    value = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+  } catch {
+    throw invalid();
+  }
+  if (!value || value.purpose !== "feedbax-identity-v1") throw invalid();
+  for (const key of [
+    "subject",
+    "displayName",
+    "issuer",
+    "audience",
+    "state",
+    "nonce",
+  ])
+    if (
+      typeof value[key] !== "string" ||
+      !value[key].trim() ||
+      value[key].length > 512
+    )
+      throw invalid();
+  if (
+    value.audience !== expected.audience ||
+    value.issuer !== expected.issuer ||
+    value.state !== expected.state ||
+    !expected.state ||
+    !Number.isSafeInteger(value.issuedAt) ||
+    !Number.isSafeInteger(value.expiresAt)
+  )
+    throw invalid();
+  const issuedAt = Number(value.issuedAt),
+    expiresAt = Number(value.expiresAt);
+  if (
+    issuedAt > expected.now + 30 ||
+    expiresAt <= expected.now ||
+    expiresAt <= issuedAt ||
+    expiresAt - issuedAt > 120
+  )
+    throw invalid();
+  if (
+    value.emailVerified !== undefined &&
+    typeof value.emailVerified !== "boolean"
+  )
+    throw invalid();
+  if (
+    value.email !== undefined &&
+    (typeof value.email !== "string" ||
+      value.email.length > 254 ||
+      !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.email))
+  )
+    throw invalid();
+  if (value.emailVerified === true && !value.email) throw invalid();
+  return {
+    ...(value.emailVerified === true
+      ? { email: String(value.email), emailVerified: true }
+      : {}),
+    subject: String(value.subject),
+    displayName: String(value.displayName),
+    issuer: String(value.issuer),
+    audience: String(value.audience),
+    state: String(value.state),
+    nonce: String(value.nonce),
+    issuedAt,
+    expiresAt,
+  };
+}
+function signature(payload: string, secret: string) {
+  return createHmac("sha256", secret)
+    .update(`feedbax-identity-v1:${payload}`)
+    .digest("base64url");
+}
+function requireSecret(secret: string) {
+  if (secret.length < 32)
+    throw new Error(
+      "Identity handoff secret must contain at least 32 characters.",
+    );
+}
+function invalid() {
+  return new Error(
+    "Identity handoff is invalid or expired. Start sign-in again.",
+  );
+}

package/template/src/feedbax/feedback/image-feedback.ts

@@ -0,0 +1,101 @@
+import type { FeedbackModule, CreateCommentInput } from "./index";
+import type { createImageModule, ImageAttachment } from "./images";
+
+export function createImageFeedbackModule(
+  base: FeedbackModule,
+  images: ReturnType<typeof createImageModule>,
+  writeReview?: (postId: string, images: ImageAttachment[]) => Promise<void>,
+): FeedbackModule {
+  const create = async (
+    input: CreateCommentInput & { discussionId?: string },
+  ) => {
+    const ids = input.imageIds ?? [];
+    await images.validatePending(ids);
+    const comment = input.discussionId
+      ? await base.replyToCommentThread({
+          ...input,
+          discussionId: input.discussionId,
+        })
+      : await base.createComment(input);
+    if (!ids.length) return comment;
+    try {
+      return {
+        ...comment,
+        images: await images.attachComment({
+          ids,
+          slug: input.slug,
+          commentId: comment.id,
+        }),
+      };
+    } catch (error) {
+      try {
+        await base.deleteComment({ commentId: comment.id });
+        await images.discardAttached(input.slug, comment.id);
+      } catch {
+        /* External cleanup remains best effort; never expose an unpublished attachment. */
+      }
+      throw error;
+    }
+  };
+  return {
+    ...base,
+    async submitPost(input) {
+      const ids = input.imageIds ?? [];
+      await images.validatePending(ids);
+      const post = await base.submitPost(input);
+      if (!ids.length) return post;
+      try {
+        const attached = await images.attachPost({
+          ids,
+          id: post.id,
+          browserCapability: post.browserCapability,
+        });
+        await writeReview?.(post.id, attached);
+        return { ...post, images: attached };
+      } catch (error) {
+        try {
+          await base.withdrawDraftPost({
+            id: post.id,
+            browserCapability: post.browserCapability,
+          });
+          await images.discardAttached(post.slug);
+        } catch {
+          /* Preserve the private record for failed external cleanup. */
+        }
+        throw error;
+      }
+    },
+    async getPublicPost(slug) {
+      const post = await base.getPublicPost(slug);
+      if (!post) return;
+      const attached = await images.forPost(slug);
+      return attached.length ? { ...post, images: attached } : post;
+    },
+    async getDraftPost(input) {
+      const post = await base.getDraftPost(input);
+      const attached = await images.forPost(post.slug);
+      return attached.length ? { ...post, images: attached } : post;
+    },
+    createComment: create,
+    replyToCommentThread: create,
+    async listCommentThreads(input) {
+      const page = await base.listCommentThreads(input);
+      const attachments = await images.forComments(
+        input.slug,
+        page.items.flatMap((thread) =>
+          thread.comments.map((comment) => comment.id),
+        ),
+      );
+      return {
+        ...page,
+        items: page.items.map((thread) => ({
+          ...thread,
+          comments: thread.comments.map((comment) => {
+            const attached = attachments.get(comment.id) ?? [];
+            return attached.length ? { ...comment, images: attached } : comment;
+          }),
+        })),
+      };
+    },
+  };
+}