@forwardimpact/libbridge 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libbridge",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Threaded-channel bridge primitives — relay messages between human channels (GitHub Discussions, Microsoft Teams) and the Kata agent team.",
   "keywords": [
     "bridge",
@@ -42,8 +42,8 @@
   "dependencies": {
     "@forwardimpact/libindex": "^0.1.38",
     "@forwardimpact/libstorage": "^0.1.78",
-    "@hono/node-server": "^2.0.3",
-    "hono": "^4.12.22"
+    "@hono/node-server": "^2.0.4",
+    "hono": "^4.12.23"
   },
   "devDependencies": {
     "@forwardimpact/libharness": "^0.1.21"

package/src/callback-handler.js

@@ -134,6 +134,19 @@ async function resolveContext(
   return { token, ctx, meta, payload };
 }
 
+const STATUS_MESSAGES = {
+  400: "Bad request",
+  404: "Not found",
+  410: "Gone",
+  429: "Too many requests",
+  500: "Internal error",
+};
+
+/** Map a CallbackHandlerError status to a safe generic message. */
+function sanitizeErrorMessage(status) {
+  return STATUS_MESSAGES[status] ?? `Error ${status}`;
+}
+
 async function runHandleReply(
   c,
   { ctx, meta, payload, handleReply, store, logger, tracer, spanName },
@@ -154,7 +167,7 @@ async function runHandleReply(
     if (err instanceof CallbackHandlerError) {
       span.addEvent("short_circuit", { status: err.status });
       span.setOk();
-      return c.json({ error: err.message }, err.status);
+      return c.json({ error: sanitizeErrorMessage(err.status) }, err.status);
     }
     logger.error?.("callback", err, {
       correlation_id: meta.correlationId,

package/src/callback-payload.js

@@ -1,4 +1,5 @@
 export const MAX_FIELD_LENGTH = 2000;
+export const MAX_REPLY_COUNT = 50;
 
 /**
  * Validate and sanitize the kata-dispatch callback payload. Lenient by
@@ -23,11 +24,17 @@ export function validateCallbackPayload(body) {
     typeof body.summary === "string"
       ? body.summary.slice(0, MAX_FIELD_LENGTH)
       : "";
-  const replies = Array.isArray(body.replies) ? body.replies : [];
+  const rawReplies = Array.isArray(body.replies) ? body.replies : [];
+  const replies = rawReplies.slice(0, MAX_REPLY_COUNT).map((r) => {
+    if (!r || typeof r !== "object") return r;
+    if (typeof r.body === "string") {
+      return { ...r, body: r.body.slice(0, MAX_FIELD_LENGTH) };
+    }
+    return r;
+  });
   const discussionId =
     typeof body.discussion_id === "string" ? body.discussion_id : undefined;
-  const trigger =
-    body.trigger && typeof body.trigger === "object" ? body.trigger : undefined;
+  const trigger = validateTrigger(body.trigger);
   const runUrl = typeof body.run_url === "string" ? body.run_url : undefined;
 
   return {
@@ -41,6 +48,43 @@ export function validateCallbackPayload(body) {
   };
 }
 
+const ALLOWED_TRIGGER_KINDS = new Set([
+  "missing_input",
+  "escalation_needed",
+  "elapsed",
+]);
+
+const TRIGGER_FIELD_VALIDATORS = {
+  replies: (raw) => {
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+  },
+  elapsed: (raw) => (typeof raw === "string" ? raw : undefined),
+  signal: (raw) => (typeof raw === "string" && raw ? raw : undefined),
+};
+
+/**
+ * Validate and sanitize a trigger object at the payload boundary.
+ * Rejects triggers with unknown `kind` values or invalid field types.
+ *
+ * @param {unknown} raw
+ * @returns {object | undefined}
+ */
+function validateTrigger(raw) {
+  if (!raw || typeof raw !== "object") return undefined;
+  if (typeof raw.kind !== "string" || !ALLOWED_TRIGGER_KINDS.has(raw.kind)) {
+    return undefined;
+  }
+  const trigger = { kind: raw.kind };
+  for (const [field, validate] of Object.entries(TRIGGER_FIELD_VALIDATORS)) {
+    if (raw[field] === undefined) continue;
+    const clean = validate(raw[field]);
+    if (clean === undefined) return undefined;
+    trigger[field] = clean;
+  }
+  return trigger;
+}
+
 /**
  * Strip trailing slashes from a base URL so callback URL composition is
  * deterministic regardless of operator input.

package/src/index.js

@@ -17,6 +17,7 @@ export { appendHistory } from "./history.js";
 export { RateLimiter } from "./rate-limit.js";
 export { dispatchWorkflow } from "./dispatch.js";
 export { DiscussionContextStore } from "./discussion-context.js";
+export { OriginIndex } from "./origin-index.js";
 export { ProgressTicker } from "./progress-ticker.js";
 export {
   Acknowledgement,
@@ -31,6 +32,7 @@ export { ElapsedScheduler } from "./elapsed-scheduler.js";
 export { ResumeScheduler } from "./resume-scheduler.js";
 export {
   MAX_FIELD_LENGTH,
+  MAX_REPLY_COUNT,
   newDiscussionContext,
   normalizeBaseUrl,
   validateCallbackPayload,

package/src/origin-index.js

@@ -0,0 +1,49 @@
+import { BufferedIndex } from "@forwardimpact/libindex";
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Tracks comment IDs posted by the bridge so webhook handlers can skip
+ * dispatching for self-originated events. Wraps `BufferedIndex` with
+ * caller-injected `StorageInterface` per the libbridge invariant.
+ *
+ * Record shape: `{ id: "<comment_node_id>", discussion_id, posted_at }`
+ *
+ * @augments BufferedIndex
+ */
+export class OriginIndex extends BufferedIndex {
+  #ttlMs;
+
+  /**
+   * @param {import("@forwardimpact/libstorage").StorageInterface} storage
+   * @param {object} [options]
+   * @param {string} [options.indexKey]
+   * @param {number} [options.ttlMs] - Eviction window (default 24h)
+   */
+  constructor(
+    storage,
+    { indexKey = "origins.jsonl", ttlMs = DEFAULT_TTL_MS } = {},
+  ) {
+    super(storage, indexKey, {
+      flush_interval: 1_000,
+      max_buffer_size: 100,
+    });
+    this.#ttlMs = ttlMs;
+  }
+
+  /**
+   * Evict records older than `ttlMs`.
+   * @param {number} now
+   * @returns {number} count evicted
+   */
+  sweep(now) {
+    let evicted = 0;
+    for (const [id, record] of this.index) {
+      if (now - (record?.posted_at ?? 0) > this.#ttlMs) {
+        this.index.delete(id);
+        evicted++;
+      }
+    }
+    return evicted;
+  }
+}

package/src/progress-ticker.js

@@ -37,15 +37,17 @@ export class ProgressTicker {
       throw new Error("tick must be a function");
     }
     this.stop(token);
-    const timer = setInterval(async () => {
+    const safeTick = async () => {
       try {
         await tick();
       } catch {
         this.stop(token);
       }
-    }, this.#intervalMs);
+    };
+    const timer = setInterval(safeTick, this.#intervalMs);
     timer.unref?.();
     this.#timers.set(token, timer);
+    safeTick();
   }
 
   /**

package/src/resume-scheduler.js

@@ -119,12 +119,10 @@ export class ResumeScheduler {
       opened_at: openedAt,
       history_index_at_open: ctx.history.length,
     };
-    if (trigger.kind === "elapsed" || trigger.kind === "either") {
-      if (typeof trigger.elapsed === "string") {
-        const dueAt = openedAt + parseIsoDuration(trigger.elapsed);
-        ctx.open_rfcs[correlationId].due_at = dueAt;
-        this.#elapsed.schedule(correlationId, dueAt);
-      }
+    if (trigger.kind === "elapsed" && typeof trigger.elapsed === "string") {
+      const dueAt = openedAt + parseIsoDuration(trigger.elapsed);
+      ctx.open_rfcs[correlationId].due_at = dueAt;
+      this.#elapsed.schedule(correlationId, dueAt);
     }
   }
 
@@ -204,7 +202,7 @@ export class ResumeScheduler {
       const trigger = rfc.trigger;
       if (!trigger) continue;
       const observed = {
-        responses: ctx.history.length - rfc.history_index_at_open,
+        replies: ctx.history.length - rfc.history_index_at_open,
         opened_at: rfc.opened_at,
       };
       if (evaluateTrigger(trigger, observed, Date.now()).fired) {

package/src/server.js

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
 import { serve } from "@hono/node-server";
 
 /**
@@ -44,6 +45,17 @@ export function createBridgeServer({
 
   const app = new Hono();
 
+  // Security headers — standard hardening for a backend service.
+  app.use("*", async (c, next) => {
+    await next();
+    c.header("X-Content-Type-Options", "nosniff");
+    c.header("X-Frame-Options", "DENY");
+    c.header("Cache-Control", "no-store");
+  });
+
+  // Request body size limit — 1 MB is generous for JSON callback payloads.
+  app.use("*", bodyLimit({ maxSize: 1024 * 1024 }));
+
   // Capture the raw POST body once, before downstream handlers parse it.
   // Channel adapters use this buffer to verify HMAC signatures.
   app.use("*", async (c, next) => {

package/src/triggers.js

@@ -1,10 +1,13 @@
 /**
  * @typedef {object} ResumeTrigger
- * @property {"responses"|"elapsed"|"either"} kind
- * @property {number} [responses] - Number of new responses needed.
- *   For `kind: "either"`, optional alongside `elapsed`.
- * @property {string} [elapsed] - ISO-8601 duration, e.g. `"P14D"`, `"PT12H"`,
- *   `"P1DT6H"`. Required for `kind: "elapsed"`; optional for `"either"`.
+ * @property {"missing_input"|"escalation_needed"|"elapsed"} kind
+ * @property {number} [replies] - Required for `kind: "missing_input"`.
+ *   Number of new replies on the dispatching thread needed to fire.
+ * @property {string} [elapsed] - Required for `kind: "elapsed"`.
+ *   ISO-8601 duration, e.g. `"P14D"`, `"PT12H"`, `"P1DT6H"`.
+ * @property {string} [signal] - Required for `kind: "escalation_needed"`.
+ *   Reserved for future use. The bridge throws when evaluating this kind
+ *   until signal-based resume support lands.
  */
 
 const ISO_8601_DURATION =
@@ -42,7 +45,7 @@ export function parseIsoDuration(duration) {
  * Evaluate whether a resume trigger has fired.
  *
  * @param {ResumeTrigger} trigger
- * @param {{responses?: number, opened_at?: number}} observed
+ * @param {{replies?: number, opened_at?: number}} observed
  * @param {number} now - ms epoch (caller-provided for testability)
  * @returns {{fired: boolean, due_at?: number}}
  */
@@ -56,37 +59,27 @@ export function evaluateTrigger(trigger, observed, now) {
   observed ??= {};
 
   switch (trigger.kind) {
-    case "responses":
-      return evaluateResponses(trigger, observed);
+    case "missing_input":
+      return evaluateMissingInput(trigger, observed);
     case "elapsed":
       return evaluateElapsed(trigger, observed, now);
-    case "either": {
-      const r =
-        trigger.responses !== undefined
-          ? evaluateResponses(trigger, observed)
-          : { fired: false };
-      const e =
-        trigger.elapsed !== undefined
-          ? evaluateElapsed(trigger, observed, now)
-          : { fired: false };
-      if (r.fired || e.fired) return { fired: true };
-      return e.due_at !== undefined
-        ? { fired: false, due_at: e.due_at }
-        : { fired: false };
-    }
+    case "escalation_needed":
+      throw new Error(
+        "escalation_needed is reserved for future use. See the follow-up spec for signal-based resume.",
+      );
     default:
       throw new Error(`Unsupported trigger kind: ${trigger.kind}`);
   }
 }
 
-function evaluateResponses(trigger, observed) {
-  if (typeof trigger.responses !== "number" || trigger.responses < 1) {
+function evaluateMissingInput(trigger, observed) {
+  if (typeof trigger.replies !== "number" || trigger.replies < 1) {
     throw new Error(
-      'trigger.responses must be a positive number for kind "responses"',
+      'trigger.replies must be a positive number for kind "missing_input"',
     );
   }
-  const seen = observed.responses ?? 0;
-  return { fired: seen >= trigger.responses };
+  const seen = observed.replies ?? 0;
+  return { fired: seen >= trigger.replies };
 }
 
 function evaluateElapsed(trigger, observed, now) {