create-feedbax 0.2.1 → 0.2.2

package/template/src/feedbax/feedback/github-service-client.ts

@@ -0,0 +1,56 @@
+import type { GitHubConfiguration } from "@feedbax/config";
+import { signIntegrationRequest } from "./integration-auth";
+
+export function createGitHubServiceAccess(options: {
+  config: GitHubConfiguration;
+  secret?: string;
+  getSecret?: () => Promise<string>;
+  request?: typeof fetch;
+}) {
+  let cached: { token: string; expires: number; secret: string } | undefined;
+  return async () => {
+    const secret = options.getSecret
+      ? await options.getSecret()
+      : (options.secret ?? "");
+    if (
+      cached &&
+      cached.secret === secret &&
+      cached.expires > Date.now() + 60_000
+    )
+      return cached.token;
+    const response = await (options.request ?? fetch)(
+      signIntegrationRequest({
+        url: `${options.config.serviceUrl}/v1/token`,
+        installationId: options.config.installationId,
+        secret,
+        body: "{}",
+      }),
+    );
+    if (!response.ok) {
+      cached = undefined;
+      throw new Error(
+        "GitHub Portal Binding is unavailable. Run feedbax doctor or pair the Installation again.",
+      );
+    }
+    const value = (await response.json()) as {
+      token?: unknown;
+      expiresAt?: unknown;
+      repositoryId?: unknown;
+      botUserId?: unknown;
+    };
+    const expires =
+      typeof value.expiresAt === "string" ? Date.parse(value.expiresAt) : NaN;
+    if (
+      typeof value.token !== "string" ||
+      !value.token ||
+      !Number.isFinite(expires) ||
+      expires <= Date.now() ||
+      value.repositoryId !== options.config.repository.id ||
+      value.botUserId !== options.config.botUserId
+    )
+      throw new Error("GitHub integration returned mismatched access.");
+    // Cache only within one request factory and recheck local revocation/rotation on every use.
+    cached = { token: value.token, expires, secret };
+    return cached.token;
+  };
+}

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

@@ -1,4 +1,8 @@
-import type { FeedbackModule, CreateCommentInput } from "./index";
+import {
+  recoverableComment,
+  type FeedbackModule,
+  type CreateCommentInput,
+} from "./index";
 import type { createImageModule, ImageAttachment } from "./images";
 
 export function createImageFeedbackModule(
@@ -10,15 +14,23 @@ export function createImageFeedbackModule(
     input: CreateCommentInput & { discussionId?: string },
   ) => {
     const ids = input.imageIds ?? [];
-    await images.validatePending(ids);
+    const attachedComment = input.submissionKey
+      ? await images.validateCommentImages(ids, input.slug)
+      : (await images.validatePending(ids), undefined);
+    const command = {
+      ...input,
+      ...(attachedComment ? { recoveryCommentId: attachedComment } : {}),
+    };
     const comment = input.discussionId
       ? await base.replyToCommentThread({
-          ...input,
+          ...command,
           discussionId: input.discussionId,
         })
-      : await base.createComment(input);
+      : await base.createComment(command);
     if (!ids.length) return comment;
     try {
+      if (attachedComment && attachedComment !== comment.id)
+        throw new Error("Images belong to another Comment.");
       return {
         ...comment,
         images: await images.attachComment({
@@ -28,12 +40,13 @@ export function createImageFeedbackModule(
         }),
       };
     } 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. */
-      }
+      if (!comment[recoverableComment])
+        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;
     }
   };

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

@@ -93,6 +93,32 @@ export function createImageModule(options: {
       );
   };
   return {
+    async validateCommentImages(ids: string[], slug: string) {
+      if (!ids.length) return;
+      const person = identity();
+      if (ids.length > 4 || new Set(ids).size !== ids.length)
+        throw new ImageAttachmentError("Choose up to four images.");
+      let attachedComment: string | undefined;
+      for (const id of ids) {
+        const image = await row(id);
+        if (
+          !image ||
+          image.subject !== person.subject ||
+          image.deleting ||
+          (image.post_slug === null
+            ? image.created_at <= now() - 86400000
+            : image.post_slug !== slug ||
+              !image.comment_id ||
+              (attachedComment !== undefined &&
+                attachedComment !== image.comment_id))
+        )
+          throw new ImageAttachmentError(
+            "One or more images are unavailable. Upload them again.",
+          );
+        if (image.comment_id) attachedComment = image.comment_id;
+      }
+      return attachedComment;
+    },
     async validatePending(ids: string[]) {
       if (!ids.length) return;
       const person = identity();

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

@@ -1,3 +1,4 @@
+import type { PostOwnership } from "./ownership";
 import {
   createHash,
   randomBytes,
@@ -9,16 +10,18 @@ import {
   createNotionFeedbackStorage,
   type NotionFeedbackStorageOptions,
 } from "./notion-feedback";
+import {
+  createGitHubFeedbackStorage,
+  type GitHubFeedbackOptions,
+} from "./github-feedback";
+import { createGitHubCommentStorage } from "./github-comments";
+import type { CommentStorage, StoredComment } from "./comment-storage";
 import type {
   FeedbackStorage,
   NewStoredPost,
   StoredPost,
 } from "./feedback-storage";
-import {
-  createNotionCommentStorage,
-  type CommentStorage,
-  type StoredComment,
-} from "./notion-comments";
+import { createNotionCommentStorage } from "./notion-comments";
 
 export {
   createNotionFeedbackDataSource,
@@ -35,6 +38,7 @@ export type PostStatus =
   "New" | "Reviewing" | "Planned" | "In Progress" | "Shipped" | "Closed";
 
 export interface SubmitPostInput {
+  submissionKey?: string;
   imageIds?: string[];
   title: string;
   description: string;
@@ -137,7 +141,7 @@ export type TrustedSubmittedPost = Omit<Post, "published" | "submitter">;
 
 export interface EditDraftPostInput {
   id: string;
-  browserCapability: BrowserCapability;
+  browserCapability?: BrowserCapability;
   title?: string;
   description?: string;
   type?: PostType;
@@ -145,7 +149,7 @@ export interface EditDraftPostInput {
 
 export interface WithdrawDraftPostInput {
   id: string;
-  browserCapability: BrowserCapability;
+  browserCapability?: BrowserCapability;
 }
 
 export type GetDraftPostInput = WithdrawDraftPostInput;
@@ -193,6 +197,9 @@ export interface ListCommentThreadsInput {
 }
 
 export interface CreateCommentInput {
+  submissionKey?: string;
+  /** Internal recovery precondition; it never grants Comment authority. */
+  recoveryCommentId?: string;
   imageIds?: string[];
   slug: string;
   body: string;
@@ -203,7 +210,9 @@ export interface ReplyToCommentThreadInput extends CreateCommentInput {
   discussionId: string;
 }
 
+export const recoverableComment = Symbol("recoverable-comment");
 export interface CreatedComment extends Comment {
+  [recoverableComment]?: boolean;
   discussionId: string;
 }
 
@@ -360,7 +369,24 @@ class InMemoryFeedbackStorage implements FeedbackStorage {
   }
 }
 
+export type ParticipantPost = Pick<
+  Post,
+  | "id"
+  | "slug"
+  | "title"
+  | "description"
+  | "type"
+  | "status"
+  | "published"
+  | "createdAt"
+  | "updatedAt"
+> & { editable: boolean };
+
 export interface FeedbackModule {
+  getParticipantPost(id: string): Promise<ParticipantPost | undefined>;
+  claimDraftPost(
+    input: GetDraftPostInput,
+  ): Promise<ParticipantPost | undefined>;
   getAttachmentPostState(
     slug: string,
   ): Promise<"published" | "draft" | "private" | undefined>;
@@ -393,6 +419,7 @@ export type FeedbackMutationModule = Pick<
 >;
 
 interface CreateFeedbackModuleOptions {
+  ownership?: PostOwnership;
   initialItems?: StoredPost[];
   storage?: FeedbackStorage;
   votingEnabled?: boolean;
@@ -412,10 +439,39 @@ export function createFeedbackModule(
     options.commentStorage ??
     createInMemoryCommentStorage(options.initialComments);
   const voteQueues = new Map<string, Promise<void>>();
+  const authorizedDraft = async (
+    item: StoredPost | undefined,
+    capability?: BrowserCapability,
+  ): Promise<boolean> =>
+    Boolean(
+      item &&
+      isEditableDraft(item) &&
+      (authorizesDraft(item, capability) ||
+        (await options.ownership?.owns(item.id))),
+    );
+  const participantPost = async (
+    id: string,
+  ): Promise<ParticipantPost | undefined> => {
+    if (!(await options.ownership?.owns(id))) return;
+    const item = await storage.find(id);
+    if (!item) return;
+    return {
+      id: item.id,
+      slug: item.slug,
+      title: item.title,
+      description: item.description,
+      type: item.type,
+      status: item.status,
+      published: item.published,
+      createdAt: item.createdAt,
+      updatedAt: item.updatedAt,
+      editable: isEditableDraft(item),
+    };
+  };
   const editStoredDraft = async (input: EditDraftPostInput) => {
     const item = await storage.find(input.id);
 
-    if (!authorizesDraft(item, input.browserCapability)) {
+    if (!item || !(await authorizedDraft(item, input.browserCapability))) {
       throw new BrowserCapabilityAuthorizationError();
     }
 
@@ -441,17 +497,29 @@ export function createFeedbackModule(
   };
 
   return {
+    getParticipantPost: participantPost,
+    async claimDraftPost(input) {
+      const item = await storage.find(input.id);
+      if (!options.ownership || !authorizesDraft(item, input.browserCapability))
+        throw new BrowserCapabilityAuthorizationError();
+      await options.ownership.register(toPost(item));
+      return participantPost(item.id);
+    },
     async getAttachmentPostState(slug) {
       const post = await storage.findBySlug(slug);
       return !post
         ? undefined
         : post.published
           ? "published"
-          : post.status === "New"
+          : post.status === "New" && post.draftEditable !== false
             ? "draft"
             : "private";
     },
     async createComment(input) {
+      if (input.recoveryCommentId && !commentStorage.supportsIntentRecovery)
+        throw new CommentValidationError(
+          "Attached Comment recovery is unavailable.",
+        );
       const { post, body, displayName } = await validateCommentCreation(
         input,
         storage,
@@ -459,12 +527,22 @@ export function createFeedbackModule(
       return toCreatedComment(
         await commentStorage.createPageComment({
           postId: post.id,
+          ...(input.recoveryCommentId
+            ? { recoveryCommentId: input.recoveryCommentId }
+            : {}),
+          ...(input.submissionKey
+            ? { submissionKey: input.submissionKey }
+            : {}),
           body,
           displayName,
         }),
       );
     },
     async replyToCommentThread(input) {
+      if (input.recoveryCommentId && !commentStorage.supportsIntentRecovery)
+        throw new CommentValidationError(
+          "Attached Comment recovery is unavailable.",
+        );
       const { post, body, displayName } = await validateCommentCreation(
         input,
         storage,
@@ -491,6 +569,12 @@ export function createFeedbackModule(
         await commentStorage.createDiscussionReply({
           postId: post.id,
           discussionId: input.discussionId,
+          ...(input.recoveryCommentId
+            ? { recoveryCommentId: input.recoveryCommentId }
+            : {}),
+          ...(input.submissionKey
+            ? { submissionKey: input.submissionKey }
+            : {}),
           body,
           displayName,
         }),
@@ -555,10 +639,29 @@ export function createFeedbackModule(
     submitPost(input) {
       const submission = postCreationQueue.then(async () => {
         const now = new Date();
-        const browserCapability = createBrowserCapability();
+        const { submissionKey, ...content } = input;
+        if (
+          submissionKey !== undefined &&
+          !/^[A-Za-z0-9_-]{43}$/.test(submissionKey)
+        )
+          throw new Error("Submission intent is invalid.");
+        const browserCapability = submissionKey
+          ? (submissionKey as BrowserCapability)
+          : createBrowserCapability();
+        const externalId = submissionKey
+          ? `portal:${hashBrowserCapability(browserCapability)}`
+          : undefined;
+        if (externalId) {
+          const previous = await storage.findByExternalId(externalId);
+          if (previous) {
+            await options.ownership?.register(toPost(previous));
+            return { ...toPost(previous), browserCapability };
+          }
+        }
         const slug = await createUniqueSlug(input.title, storage);
         const item = await storage.create({
-          ...input,
+          ...content,
+          ...(externalId ? { externalId } : {}),
           slug,
           status: "New",
           published: false,
@@ -568,6 +671,7 @@ export function createFeedbackModule(
           voteCount: 0,
         });
 
+        await options.ownership?.register(toPost(item));
         return {
           ...toPost(item),
           browserCapability,
@@ -590,7 +694,7 @@ export function createFeedbackModule(
     },
     async getDraftPost(input) {
       const item = await storage.find(input.id);
-      if (!authorizesDraft(item, input.browserCapability)) {
+      if (!item || !(await authorizedDraft(item, input.browserCapability))) {
         throw new BrowserCapabilityAuthorizationError();
       }
       return toDraftPost(toPost(item));
@@ -638,11 +742,12 @@ export function createFeedbackModule(
     async withdrawDraftPost(input) {
       const item = await storage.find(input.id);
 
-      if (!authorizesDraft(item, input.browserCapability)) {
+      if (!item || !(await authorizedDraft(item, input.browserCapability))) {
         throw new BrowserCapabilityAuthorizationError();
       }
 
       await storage.remove(item.id);
+      await options.ownership?.withdrawn(item.id);
     },
     async getPublicPostRoadmap() {
       const pages = await Promise.all(
@@ -659,9 +764,11 @@ export function createNotionFeedbackModule(
   options: NotionFeedbackStorageOptions & {
     votingEnabled?: boolean;
     commentsEnabled?: boolean;
+    ownership?: PostOwnership;
   },
 ): FeedbackModule {
   return createFeedbackModule({
+    ownership: options.ownership,
     storage: createNotionFeedbackStorage(options),
     commentStorage: createNotionCommentStorage(options),
     votingEnabled: options.votingEnabled,
@@ -669,6 +776,21 @@ export function createNotionFeedbackModule(
   });
 }
 
+export function createGitHubFeedbackModule(
+  options: GitHubFeedbackOptions & { ownership?: PostOwnership },
+): FeedbackModule {
+  const storage = createGitHubFeedbackStorage(options);
+  return createFeedbackModule({
+    storage,
+    ownership: options.ownership,
+    commentStorage: createGitHubCommentStorage(options, storage),
+    votingEnabled: options.votingEnabled,
+    commentsEnabled: options.commentsEnabled,
+  });
+}
+
+export type { GitHubFeedbackOptions } from "./github-feedback";
+
 function createInMemoryCommentStorage(
   initialComments: StoredComment[] = [],
 ): CommentStorage {
@@ -762,13 +884,16 @@ async function validateCommentCreation(
 }
 
 function toCreatedComment(comment: StoredComment): CreatedComment {
-  return {
+  const result: CreatedComment = {
     id: comment.id,
     discussionId: comment.discussionId,
     body: comment.body,
     author: comment.author,
     createdAt: comment.createdAt,
   };
+  if (comment.recoverable)
+    Object.defineProperty(result, recoverableComment, { value: true });
+  return result;
 }
 
 function encodePublicPostCursor(
@@ -934,9 +1059,15 @@ function hashBrowserCapability(browserCapability: BrowserCapability): string {
 
 function authorizesDraft(
   item: StoredPost | undefined,
-  browserCapability: BrowserCapability,
+  browserCapability: BrowserCapability | undefined,
 ): item is StoredPost & { browserCapabilityHash: string } {
-  if (!item?.browserCapabilityHash || item.status !== "New" || item.published) {
+  if (
+    !browserCapability ||
+    !item?.browserCapabilityHash ||
+    item.status !== "New" ||
+    item.published ||
+    item.draftEditable === false
+  ) {
     return false;
   }
 
@@ -994,3 +1125,28 @@ export {
 
 export { createImageFeedbackModule } from "./image-feedback";
 export { createNotionImageReviewWriter } from "./notion-image-review";
+
+export { createGitHubServiceAccess } from "./github-service-client";
+export {
+  createObservedHistoryModule,
+  type ObservedHistoryEvent,
+  type ObservedHistoryPage,
+} from "./observed-history";
+export {
+  boundedBody,
+  signIntegrationRequest,
+  verifyIntegrationRequest,
+} from "./integration-auth";
+
+function isEditableDraft(item: StoredPost) {
+  return (
+    item.status === "New" && !item.published && item.draftEditable !== false
+  );
+}
+export {
+  createPostOwnership,
+  createMyFeedbackModule,
+  type MyFeedbackFilter,
+  type MyFeedbackItem,
+  type MyFeedbackPage,
+} from "./ownership";

package/template/src/feedbax/feedback/integration-auth.ts

@@ -0,0 +1,138 @@
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+
+export function integrationSecret(
+  master: string,
+  installationId: string,
+  direction: "portal" | "service",
+  version: number,
+) {
+  if (master.length < 32)
+    throw new Error(
+      "Integration signing secret must have at least 32 characters.",
+    );
+  return createHmac("sha256", master)
+    .update(
+      JSON.stringify([
+        "feedbax-integration-v1",
+        installationId,
+        direction,
+        version,
+      ]),
+    )
+    .digest("base64url");
+}
+
+export function signIntegrationRequest(input: {
+  url: string;
+  installationId: string;
+  secret: string;
+  body?: string;
+  method?: string;
+  now?: number;
+  nonce?: string;
+}) {
+  const method = input.method ?? "POST";
+  const time = String(Math.floor((input.now ?? Date.now()) / 1000));
+  const nonce = input.nonce ?? randomUUID();
+  const body = input.body ?? "";
+  const signature = mac(
+    input.secret,
+    method,
+    input.url,
+    input.installationId,
+    time,
+    nonce,
+    body,
+  );
+  return new Request(input.url, {
+    method,
+    redirect: "manual",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Feedbax-Installation": input.installationId,
+      "X-Feedbax-Time": time,
+      "X-Feedbax-Nonce": nonce,
+      "X-Feedbax-Signature": signature,
+    },
+    ...(method === "GET" ? {} : { body }),
+  });
+}
+
+export function verifyIntegrationRequest(
+  request: Request,
+  body: string,
+  secret: string,
+  now = Date.now(),
+) {
+  const installationId = request.headers.get("X-Feedbax-Installation") ?? "";
+  const time = request.headers.get("X-Feedbax-Time") ?? "";
+  const nonce = request.headers.get("X-Feedbax-Nonce") ?? "";
+  const signature = request.headers.get("X-Feedbax-Signature") ?? "";
+  if (
+    secret.length < 32 ||
+    !/^[A-Za-z0-9_-]{1,128}$/.test(installationId) ||
+    !/^\d{10}$/.test(time) ||
+    Math.abs(now - Number(time) * 1000) > 300_000 ||
+    !/^[A-Za-z0-9_-]{16,128}$/.test(nonce)
+  )
+    return false;
+  return equalSignature(
+    signature,
+    mac(secret, request.method, request.url, installationId, time, nonce, body),
+  );
+}
+
+export function equalSignature(actual: string, expected: string) {
+  const a = Buffer.from(actual);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function mac(
+  secret: string,
+  method: string,
+  url: string,
+  installation: string,
+  time: string,
+  nonce: string,
+  body: string,
+) {
+  return createHmac("sha256", secret)
+    .update(
+      JSON.stringify([
+        "feedbax-integration-v1",
+        method,
+        url,
+        installation,
+        time,
+        nonce,
+        body,
+      ]),
+    )
+    .digest("hex");
+}
+
+export async function boundedBody(request: Request, maximum: number) {
+  if (Number(request.headers.get("Content-Length")) > maximum)
+    throw new Error("Request body limit exceeded.");
+  const reader = request.body?.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  if (reader)
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maximum) {
+        await reader.cancel();
+        throw new Error("Request body limit exceeded.");
+      }
+      chunks.push(value);
+    }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}

package/template/src/feedbax/feedback/notion-comments.ts

@@ -1,44 +1,11 @@
-import type { CommentAuthor } from "./index";
+import type { CommentStorage, StoredComment } from "./comment-storage";
+export type { CommentStorage, StoredComment } from "./comment-storage";
 import type { NotionFeedbackStorageOptions } from "./notion-feedback";
 import { requestNotion } from "./notion-request";
 
 const NOTION_API_URL = "https://api.notion.com/v1";
 const NOTION_API_VERSION = "2026-03-11";
 
-export interface StoredComment {
-  id: string;
-  postId: string;
-  discussionId: string;
-  body: string;
-  author: CommentAuthor;
-  createdAt: Date;
-  resolved: boolean;
-  scope?: "page" | "block";
-}
-
-export interface CommentStorage {
-  createPageComment(input: {
-    postId: string;
-    body: string;
-    displayName: string;
-  }): Promise<StoredComment>;
-  createDiscussionReply(input: {
-    postId: string;
-    discussionId: string;
-    body: string;
-    displayName: string;
-  }): Promise<StoredComment>;
-  listPageComments(
-    postId: string,
-    cursor?: string,
-  ): Promise<{
-    items: StoredComment[];
-    nextCursor?: string;
-  }>;
-  updateComment(commentId: string, body: string): Promise<StoredComment>;
-  deleteComment(commentId: string): Promise<void>;
-}
-
 export function createNotionCommentStorage({
   token,
   request = fetch,