@forwardimpact/libbridge 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libbridge",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Threaded-channel bridge primitives — relay messages between human channels (GitHub Discussions, Microsoft Teams) and the Kata agent team.",
   "keywords": [
     "bridge",
@@ -40,10 +40,9 @@
     "test": "bun test test/*.test.js"
   },
   "dependencies": {
+    "@forwardimpact/libhttp": "^0.1.0",
     "@forwardimpact/libtype": "^0.1.0",
-    "@forwardimpact/libutil": "^0.1.84",
-    "@hono/node-server": "^2.0.4",
-    "hono": "^4.12.23"
+    "@forwardimpact/libutil": "^0.1.84"
   },
   "devDependencies": {
     "@forwardimpact/libmock": "^0.1.0"

package/src/callback-handler.js

@@ -88,8 +88,14 @@ export function createCallbackHandler({
     if (!payload) return c.json({ error: "Invalid payload" }, 400);
 
     const token = c.req.param("token");
+    const tenant_id = c.req.param("tenant_id");
+    if (!tenant_id) {
+      return c.json({ error: "Unknown callback token" }, 404);
+    }
     const isTerminal = payload.kind === "terminal";
-    const meta = isTerminal ? callbacks.consume(token) : callbacks.peek(token);
+    const meta = isTerminal
+      ? callbacks.consume(token, { tenant_id })
+      : callbacks.peek(token, { tenant_id });
     if (!meta) {
       logger.debug?.("callback", "unknown token");
       return c.json({ error: "Unknown callback token" }, 404);

package/src/callback-registry.js

@@ -9,6 +9,11 @@ const DEFAULT_TTL_MS = 2 * 60 * 60 * 1000;
  * the (token, correlationId) pairs via the discussion store so the registry
  * can be rehydrated after a restart; this class only owns the live token →
  * metadata mapping and TTL sweep.
+ *
+ * Every entry is tenant-bound. `register` requires `meta.tenant_id` (single
+ * tenant deployments pass `"default"`); `consume` and `peek` require the
+ * caller's `tenant_id` and return `null` when the stored value does not
+ * match — the same null shape callers already handle for unknown tokens.
  */
 export class CallbackRegistry {
   #ttlMs;
@@ -32,13 +37,16 @@ export class CallbackRegistry {
 
   /**
    * @param {string} correlationId
-   * @param {object} [meta] - Caller-defined metadata stored alongside the token
+   * @param {object} meta - Caller-defined metadata; `meta.tenant_id` is required
    * @returns {string} The newly issued callback token
    */
-  register(correlationId, meta = {}) {
+  register(correlationId, meta) {
     if (typeof correlationId !== "string" || !correlationId) {
       throw new Error("correlationId is required");
     }
+    if (!meta || typeof meta.tenant_id !== "string" || !meta.tenant_id) {
+      throw new Error("meta.tenant_id is required");
+    }
     const token = randomUUID();
     this.#entries.set(token, {
       correlationId,
@@ -49,28 +57,38 @@ export class CallbackRegistry {
   }
 
   /**
-   * Atomic lookup + delete. Returns null if the token is unknown.
+   * Atomic lookup + delete. Returns null when the token is unknown or when
+   * the supplied `tenant_id` does not match the stored binding.
    * @param {string} token
+   * @param {{tenant_id: string}} bind
    * @returns {{correlationId: string, meta: object, createdAt: number} | null}
    */
-  consume(token) {
+  consume(token, bind) {
+    if (!bind || typeof bind.tenant_id !== "string" || !bind.tenant_id) {
+      throw new Error("tenant_id is required");
+    }
     const entry = this.#entries.get(token);
     if (!entry) return null;
+    if (entry.meta.tenant_id !== bind.tenant_id) return null;
     this.#entries.delete(token);
     return entry;
   }
 
   /**
    * Returns a shallow clone of the stored metadata for a token without
-   * consuming it. Cloning prevents callers from corrupting internal state
-   * via the returned reference; diagnostic code paths that need to read
-   * `correlationId`, `meta`, or `createdAt` work unchanged.
+   * consuming it. Returns null on unknown token or `tenant_id` mismatch —
+   * matching `consume`'s shape so callers handle one missing case.
    * @param {string} token
+   * @param {{tenant_id: string}} bind
    * @returns {{correlationId: string, meta: object, createdAt: number} | null}
    */
-  peek(token) {
+  peek(token, bind) {
+    if (!bind || typeof bind.tenant_id !== "string" || !bind.tenant_id) {
+      throw new Error("tenant_id is required");
+    }
     const entry = this.#entries.get(token);
     if (!entry) return null;
+    if (entry.meta.tenant_id !== bind.tenant_id) return null;
     return { ...entry };
   }
 

package/src/dispatcher.js

@@ -13,6 +13,7 @@ export class Dispatcher {
   #workflowFile;
   #githubRepo;
   #tokenResolver;
+  #tenantResolver;
   #clock;
 
   /**
@@ -24,6 +25,7 @@ export class Dispatcher {
    * @param {string} options.workflowFile
    * @param {string} options.githubRepo
    * @param {import("./token-resolver.js").TokenResolver} options.tokenResolver
+   * @param {import("./tenant-resolver.js").TenantResolver} options.tenantResolver
    * @param {import("@forwardimpact/libutil/runtime").Runtime["clock"]} [options.clock]
    */
   constructor({
@@ -34,6 +36,7 @@ export class Dispatcher {
     workflowFile,
     githubRepo,
     tokenResolver,
+    tenantResolver,
     clock = createDefaultClock(),
   }) {
     if (!callbacks) throw new Error("callbacks is required");
@@ -45,6 +48,7 @@ export class Dispatcher {
     if (!workflowFile) throw new Error("workflowFile is required");
     if (!githubRepo) throw new Error("githubRepo is required");
     if (!tokenResolver) throw new Error("tokenResolver is required");
+    if (!tenantResolver) throw new Error("tenantResolver is required");
     this.#callbacks = callbacks;
     this.#ack = ack;
     this.#store = store;
@@ -52,6 +56,7 @@ export class Dispatcher {
     this.#workflowFile = workflowFile;
     this.#githubRepo = githubRepo;
     this.#tokenResolver = tokenResolver;
+    this.#tenantResolver = tenantResolver;
     this.#clock = clock;
   }
 
@@ -80,12 +85,21 @@ export class Dispatcher {
     const auth = await this.#tokenResolver.resolve(ctx.channel, requester);
     if (auth.kind !== "token") return auth;
 
+    const tenant = await this.#tenantResolver.resolve({
+      channel: ctx.channel,
+      key: ctx.channel_tenant_key,
+    });
+    if (!tenant) {
+      return { kind: "transient", error: new Error("tenant_unresolved") };
+    }
+    const tenant_id = tenant.tenant_id;
+
     const correlationId = randomUUID();
-    const mergedMeta = { ...(callbackMeta ?? {}), requester };
+    const mergedMeta = { ...(callbackMeta ?? {}), requester, tenant_id };
     const token = this.#callbacks.register(correlationId, mergedMeta);
     ctx.pending_callbacks[token] = correlationId;
     ctx.active_requester = requester;
-    const callbackUrl = `${this.#callbackBaseUrl}/api/callback/${token}`;
+    const callbackUrl = `${this.#callbackBaseUrl}/api/callback/${tenant_id}/${token}`;
     const inboxUrl = `${this.#callbackBaseUrl}/api/inbox/${correlationId}`;
 
     if (ackTarget !== undefined) await this.#ack.start(token, ackTarget);
@@ -107,7 +121,7 @@ export class Dispatcher {
       return { kind: "dispatched", token, correlationId };
     } catch (err) {
       if (ackTarget !== undefined) await this.#ack.finish(token, ackTarget);
-      this.#callbacks.consume(token);
+      this.#callbacks.consume(token, { tenant_id });
       delete ctx.pending_callbacks[token];
       ctx.active_requester = null;
       throw err;

package/src/index.js

@@ -34,6 +34,10 @@ export {
   DEFAULT_TYPING_VERBS,
 } from "./acknowledgement.js";
 export { Dispatcher } from "./dispatcher.js";
+export {
+  DefaultTenantResolver,
+  RegistryTenantResolver,
+} from "./tenant-resolver.js";
 export { TokenResolver } from "./token-resolver.js";
 export {
   CallbackHandlerError,

package/src/server.js

@@ -1,13 +1,13 @@
-import { Hono } from "hono";
-import { bodyLimit } from "hono/body-limit";
-import { serve } from "@hono/node-server";
+import { createHttpService } from "@forwardimpact/libhttp";
 
 /**
  * Create the channel-agnostic HTTP server that bridges (ghbridge, msbridge)
  * share. The server mounts two routes:
  *   - `OPTIONS|POST <webhookPath>` — channel-specific intake. The raw POST
  *     body is captured on `c.get("rawBody")` for signature verification.
- *   - `POST /api/callback/:token` — workflow → bridge reply intake.
+ *   - `POST /api/callback/:tenant_id/:token` — workflow → bridge reply
+ *     intake. Single-tenant deployments hit the same route with the literal
+ *     `default` segment; multi-tenant deployments with the resolved tenant.
  *
  * Handlers receive Hono's context `c` (matching the monorepo standard) and
  * return a `Response` (or use `c.json` / `c.text` / `c.body`). The caller
@@ -30,7 +30,7 @@ import { serve } from "@hono/node-server";
 export function createBridgeServer({
   config,
   logger,
-  tracer: _tracer,
+  tracer,
   webhookPath,
   onWebhook,
   onCallback,
@@ -47,97 +47,66 @@ export function createBridgeServer({
     throw new Error("onCallback is required");
   }
 
-  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) => {
-    if (c.req.method === "POST") {
-      const buf = Buffer.from(await c.req.raw.clone().arrayBuffer());
-      c.set("rawBody", buf);
-    }
-    await next();
-  });
-
-  app.options(webhookPath, (c) => c.body(null, 200));
+  // Lifecycle, security headers, body limit, and the health route are owned by
+  // `@forwardimpact/libhttp`. This factory only mounts the bridge routes (and
+  // the raw-body capture they depend on) through the `configure` callback.
+  return createHttpService({
+    name: "bridge",
+    config,
+    logger,
+    tracer,
+    configure(app) {
+      // 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) => {
+        if (c.req.method === "POST") {
+          const buf = Buffer.from(await c.req.raw.clone().arrayBuffer());
+          c.set("rawBody", buf);
+        }
+        await next();
+      });
 
-  app.post(webhookPath, async (c) => {
-    try {
-      return await onWebhook(c);
-    } catch (err) {
-      logger.error("bridge.webhook", err);
-      return c.json({ error: "Webhook failure" }, 500);
-    }
-  });
+      app.options(webhookPath, (c) => c.body(null, 200));
 
-  app.post("/api/callback/:token", async (c) => {
-    try {
-      return await onCallback(c);
-    } catch (err) {
-      logger.error("bridge.callback", err);
-      return c.json({ error: "Callback failure" }, 500);
-    }
-  });
+      app.post(webhookPath, async (c) => {
+        try {
+          return await onWebhook(c);
+        } catch (err) {
+          logger.error("bridge.webhook", err);
+          return c.json({ error: "Webhook failure" }, 500);
+        }
+      });
 
-  if (onLinkComplete) {
-    app.get("/api/link-complete", async (c) => {
-      try {
-        return await onLinkComplete(c);
-      } catch (err) {
-        logger.error("bridge.link-complete", err);
-        return c.json({ error: "Link completion failure" }, 500);
-      }
-    });
-  }
+      app.post("/api/callback/:tenant_id/:token", async (c) => {
+        try {
+          return await onCallback(c);
+        } catch (err) {
+          logger.error("bridge.callback", err);
+          return c.json({ error: "Callback failure" }, 500);
+        }
+      });
 
-  if (onInbox) {
-    app.get("/api/inbox/:correlationId", async (c) => {
-      try {
-        return await onInbox(c);
-      } catch (err) {
-        logger.error("bridge.inbox", err);
-        return c.json({ error: "Inbox failure" }, 500);
+      if (onLinkComplete) {
+        app.get("/api/link-complete", async (c) => {
+          try {
+            return await onLinkComplete(c);
+          } catch (err) {
+            logger.error("bridge.link-complete", err);
+            return c.json({ error: "Link completion failure" }, 500);
+          }
+        });
       }
-    });
-  }
-
-  let server = null;
 
-  return {
-    app,
-    address() {
-      if (!server || typeof server.address !== "function") return null;
-      const addr = server.address();
-      if (!addr || typeof addr === "string") return null;
-      return { port: addr.port };
-    },
-    async start() {
-      const { host, port } = config;
-      await new Promise((resolve) => {
-        server = serve({ fetch: app.fetch, port, hostname: host }, (info) => {
-          logger.info("bridge.server", "listening", {
-            host,
-            port: info?.port ?? port,
-          });
-          resolve();
+      if (onInbox) {
+        app.get("/api/inbox/:correlationId", async (c) => {
+          try {
+            return await onInbox(c);
+          } catch (err) {
+            logger.error("bridge.inbox", err);
+            return c.json({ error: "Inbox failure" }, 500);
+          }
         });
-      });
-    },
-    async stop() {
-      if (!server) return;
-      await new Promise((resolve) => server.close(() => resolve()));
-      server = null;
+      }
     },
-  };
+  });
 }

package/src/tenant-resolver.js

@@ -0,0 +1,102 @@
+/**
+ * Channel-agnostic tenant resolution.
+ *
+ * Bridges supply a resolver to libbridge primitives (`Dispatcher`,
+ * `CallbackRegistry`, callback handlers). The two implementations share a
+ * duck-typed surface — `resolve`, `resolveByRepo`, `resolveByTenantId` —
+ * so libbridge depends on the shape, not the implementation.
+ *
+ * @typedef {object} Tenant
+ * @property {string} tenant_id
+ * @property {string} channel
+ * @property {string} channel_tenant_key
+ * @property {{owner: string, name: string}} [repo]
+ * @property {"pending_consent" | "active" | "revoked"} state
+ *
+ * @typedef {object} TenantResolver
+ * @property {(key: {channel: string, key: string}) => Promise<Tenant | null>} resolve
+ * @property {(repo: {owner: string, name: string}) => Promise<Tenant | null>} resolveByRepo
+ * @property {(key: {tenant_id: string}) => Promise<Tenant | null>} resolveByTenantId
+ */
+
+/**
+ * Single-tenant resolver. Returns one fixed `default` tenant for every
+ * resolution call. Used in single-tenant deployments where the bridge does
+ * not reach `services/tenancy`.
+ */
+export class DefaultTenantResolver {
+  #default;
+
+  /**
+   * @param {object} options
+   * @param {string} options.channel
+   * @param {string} [options.channel_tenant_key]
+   * @param {{owner: string, name: string}} [options.repo]
+   */
+  constructor({ channel, channel_tenant_key = "default", repo }) {
+    if (!channel) throw new Error("channel is required");
+    this.#default = {
+      tenant_id: "default",
+      channel,
+      channel_tenant_key,
+      repo,
+      state: "active",
+    };
+  }
+
+  /** @returns {Promise<Tenant>} */
+  async resolve(_key) {
+    return this.#default;
+  }
+
+  /** @returns {Promise<Tenant>} */
+  async resolveByRepo(_repo) {
+    return this.#default;
+  }
+
+  /** @returns {Promise<Tenant | null>} */
+  async resolveByTenantId({ tenant_id }) {
+    return tenant_id === "default" ? this.#default : null;
+  }
+}
+
+/**
+ * Multi-tenant resolver. Wraps a `services/tenancy` gRPC client; returns
+ * only `active` tenants from `resolve` and `resolveByRepo` (callers must
+ * treat a `null` return as "no active tenant"). `resolveByTenantId` returns
+ * the registry row regardless of state so callback verification can compare
+ * the URL's tenant id against any known tenant.
+ */
+export class RegistryTenantResolver {
+  #client;
+
+  /**
+   * @param {object} options
+   * @param {{
+   *   ResolveByChannelKey: (req: {channel: string, key: string}) => Promise<Tenant | null>,
+   *   ResolveByRepo: (req: {owner: string, name: string}) => Promise<Tenant | null>,
+   *   ResolveByTenantId: (req: {tenant_id: string}) => Promise<Tenant | null>,
+   * }} options.client - Duck-typed tenancy client (typed at construction)
+   */
+  constructor({ client }) {
+    if (!client) throw new Error("client is required");
+    this.#client = client;
+  }
+
+  /** @returns {Promise<Tenant | null>} */
+  async resolve({ channel, key }) {
+    const t = await this.#client.ResolveByChannelKey({ channel, key });
+    return t?.state === "active" ? t : null;
+  }
+
+  /** @returns {Promise<Tenant | null>} */
+  async resolveByRepo({ owner, name }) {
+    const t = await this.#client.ResolveByRepo({ owner, name });
+    return t?.state === "active" ? t : null;
+  }
+
+  /** @returns {Promise<Tenant | null>} */
+  async resolveByTenantId({ tenant_id }) {
+    return this.#client.ResolveByTenantId({ tenant_id });
+  }
+}