@forwardimpact/libbridge 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libbridge",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Threaded-channel bridge primitives — relay messages between human channels (GitHub Discussions, Microsoft Teams) and the Kata agent team.",
   "keywords": [
     "bridge",
@@ -45,7 +45,8 @@
     "@forwardimpact/libutil": "^0.1.84"
   },
   "devDependencies": {
-    "@forwardimpact/libmock": "^0.1.0"
+    "@forwardimpact/libmock": "^0.1.0",
+    "@forwardimpact/libtelemetry": "^0.1.0"
   },
   "engines": {
     "bun": ">=1.2.0",

package/src/callback-handler.js

@@ -1,5 +1,3 @@
-import { createDefaultClock } from "@forwardimpact/libutil/runtime";
-
 import { validateCallbackPayload } from "./callback-payload.js";
 
 /**
@@ -60,8 +58,9 @@ export function createCallbackHandler({
   loadDiscussionId,
   ackFinishTarget,
   handleReply,
-  clock = createDefaultClock(),
+  clock,
 }) {
+  if (!clock) throw new Error("clock is required");
   if (!channel) throw new Error("channel is required");
   if (!callbacks) throw new Error("callbacks is required");
   if (!ack) throw new Error("ack is required");
@@ -112,7 +111,15 @@ export function createCallbackHandler({
     }
 
     const discussionId = loadDiscussionId(meta);
-    const ctx = await store.loadByChannel(channel, discussionId);
+    // The dispatcher bound the resolved tenant on the callback token's domain
+    // meta (`default` in single-tenant). Thread it into the load so
+    // multi-tenant lookups hit the tenant-scoped key rather than re-resolving
+    // by channel (which the registry cannot do — the channel is not a key).
+    const ctx = await store.loadByChannel(
+      channel,
+      discussionId,
+      meta.meta?.tenant_id,
+    );
     if (!ctx) {
       logger.error?.("callback", "context missing", {
         discussion_id: discussionId,

package/src/callback-payload.js

@@ -1,5 +1,3 @@
-import { createDefaultClock } from "@forwardimpact/libutil/runtime";
-
 export const MAX_FIELD_LENGTH = 2000;
 export const MAX_REPLY_COUNT = 50;
 
@@ -129,8 +127,9 @@ export function newDiscussionContext({
   channel,
   discussionId,
   participant,
-  clock = createDefaultClock(),
+  clock,
 }) {
+  if (!clock) throw new Error("clock is required");
   return {
     id: `${channel}:${discussionId}`,
     channel,

package/src/callback-registry.js

@@ -1,7 +1,5 @@
 import { randomUUID } from "node:crypto";
 
-import { createDefaultClock } from "@forwardimpact/libutil/runtime";
-
 const DEFAULT_TTL_MS = 2 * 60 * 60 * 1000;
 
 /**
@@ -25,7 +23,8 @@ export class CallbackRegistry {
    * @param {number} [options.ttlMs] - Time-to-live in ms (default: 2h)
    * @param {import("@forwardimpact/libutil/runtime").Runtime["clock"]} [options.clock]
    */
-  constructor({ ttlMs = DEFAULT_TTL_MS, clock = createDefaultClock() } = {}) {
+  constructor({ ttlMs = DEFAULT_TTL_MS, clock } = {}) {
+    if (!clock) throw new Error("clock is required");
     this.#ttlMs = ttlMs;
     this.#clock = clock;
   }

package/src/dispatcher.js

@@ -1,7 +1,5 @@
 import { randomUUID } from "node:crypto";
 
-import { createDefaultClock } from "@forwardimpact/libutil/runtime";
-
 import { dispatchWorkflow } from "./dispatch.js";
 
 /** Dispatch dance: resolve per-user token, register callback, ack, fire workflow, flush. */
@@ -37,7 +35,7 @@ export class Dispatcher {
     githubRepo,
     tokenResolver,
     tenantResolver,
-    clock = createDefaultClock(),
+    clock,
   }) {
     if (!callbacks) throw new Error("callbacks is required");
     if (!ack) throw new Error("ack is required");
@@ -46,9 +44,15 @@ export class Dispatcher {
       throw new Error("callbackBaseUrl is required");
     }
     if (!workflowFile) throw new Error("workflowFile is required");
-    if (!githubRepo) throw new Error("githubRepo is required");
+    // A non-empty static repo is required in single-tenant mode; multi-tenant
+    // mode derives the repo per request from the resolved tenant, so an empty
+    // string is accepted (the dispatch falls back to `tenant.repo`).
+    if (typeof githubRepo !== "string") {
+      throw new Error("githubRepo is required");
+    }
     if (!tokenResolver) throw new Error("tokenResolver is required");
     if (!tenantResolver) throw new Error("tenantResolver is required");
+    if (!clock) throw new Error("clock is required");
     this.#callbacks = callbacks;
     this.#ack = ack;
     this.#store = store;
@@ -82,9 +86,11 @@ export class Dispatcher {
     if (typeof prompt !== "string") throw new Error("prompt is required");
     if (typeof requester !== "string") throw new Error("requester is required");
 
-    const auth = await this.#tokenResolver.resolve(ctx.channel, requester);
-    if (auth.kind !== "token") return auth;
-
+    // Resolve the tenant before the dispatch credential. The hosted dispatch
+    // identity is a repo-scoped App installation token (see design § Hosted
+    // dispatch identity), so a token resolver that mints per repo needs the
+    // resolved tenant's `repo`. The third argument is additive — the
+    // self-hosted `TokenResolver` (per-user OAuth) ignores it.
     const tenant = await this.#tenantResolver.resolve({
       channel: ctx.channel,
       key: ctx.channel_tenant_key,
@@ -94,19 +100,33 @@ export class Dispatcher {
     }
     const tenant_id = tenant.tenant_id;
 
+    const auth = await this.#tokenResolver.resolve(
+      ctx.channel,
+      requester,
+      tenant,
+    );
+    if (auth.kind !== "token") return auth;
+
     const correlationId = randomUUID();
     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/${tenant_id}/${token}`;
-    const inboxUrl = `${this.#callbackBaseUrl}/api/inbox/${correlationId}`;
+    const inboxUrl = `${this.#callbackBaseUrl}/api/inbox/${correlationId}?tenant_id=${encodeURIComponent(tenant_id)}`;
+
+    // The workflow_dispatch targets the resolved tenant's repository when the
+    // resolver supplies one (multi-tenant); otherwise the static configured
+    // repo (single-tenant). Both modes fire against the customer's runner.
+    const dispatchRepo = tenant.repo
+      ? `${tenant.repo.owner}/${tenant.repo.name}`
+      : this.#githubRepo;
 
     if (ackTarget !== undefined) await this.#ack.start(token, ackTarget);
     try {
       await dispatchWorkflow({
         workflowFile: this.#workflowFile,
-        repo: this.#githubRepo,
+        repo: dispatchRepo,
         token: auth.token,
         prompt,
         callbackUrl,

package/src/elapsed-scheduler.js

@@ -1,5 +1,3 @@
-import { createDefaultClock } from "@forwardimpact/libutil/runtime";
-
 const CHUNK_CAP_MS = 7 * 24 * 60 * 60 * 1000;
 
 /**
@@ -22,8 +20,9 @@ export class ElapsedScheduler {
    * @param {(err: Error, correlationId: string) => void} [options.onError] - Invoked when `onFire` rejects.
    * @param {import("@forwardimpact/libutil/runtime").Runtime["clock"]} [options.clock]
    */
-  constructor({ onFire, onError = () => {}, clock = createDefaultClock() }) {
+  constructor({ onFire, onError = () => {}, clock }) {
     if (typeof onFire !== "function") throw new Error("onFire is required");
+    if (!clock) throw new Error("clock is required");
     this.#onFire = onFire;
     this.#onError = onError;
     this.#clock = clock;

package/src/ghserver-token-resolver.js

@@ -0,0 +1,62 @@
+/**
+ * Hosted dispatch identity for multi-tenant bridges. The `workflow_dispatch`
+ * credential is a repo-scoped GitHub App installation token minted by
+ * `services/ghserver` for the resolved tenant's repository — not the per-user
+ * OAuth token used by the self-hosted path (see design § Hosted dispatch
+ * identity). Both `services/ghbridge` and `services/msbridge` share this
+ * resolver in multi-tenant mode; the channel-specific reply credential (Bot
+ * Framework for Teams, App installation for GitHub) is unaffected.
+ *
+ * This resolver satisfies the same duck-typed surface the `Dispatcher`
+ * expects from a `TokenResolver`: `resolve(surface, requester, tenant) ->
+ * DispatchAuth`. The `tenant` argument carries the registry row (with its
+ * `repo`) the dispatcher resolved before requesting the credential, so the
+ * mint is scoped to exactly that repository — there is no per-user link step.
+ *
+ * Lives in libbridge (not a channel adapter) because it imports no channel
+ * SDK: it depends only on the duck-typed ghserver client, keeping libbridge's
+ * "no channel SDKs" invariant intact.
+ */
+export class GhServerTokenResolver {
+  #client;
+  #requestedBy;
+
+  /**
+   * @param {object} client - ghserver gRPC client exposing
+   *   `MintInstallationToken({owner, name, requested_by})`.
+   * @param {object} [options]
+   * @param {string} [options.requestedBy] - Audit tag forwarded as
+   *   `requested_by` on the mint; identifies the calling bridge.
+   */
+  constructor(client, { requestedBy = "bridge" } = {}) {
+    if (!client) throw new Error("ghserver client is required");
+    this.#client = client;
+    this.#requestedBy = requestedBy;
+  }
+
+  /**
+   * @param {string} _surface - Unused; the App installation is repo-scoped.
+   * @param {string} _requester - Unused; the App authors the dispatch.
+   * @param {import("./tenant-resolver.js").Tenant} [tenant]
+   * @returns {Promise<{kind: string, token?: string, error?: Error}>}
+   */
+  async resolve(_surface, _requester, tenant) {
+    const repo = tenant?.repo;
+    if (!repo?.owner || !repo?.name) {
+      return {
+        kind: "transient",
+        error: new Error("tenant_repo_unresolved"),
+      };
+    }
+    try {
+      const { installation_token } = await this.#client.MintInstallationToken({
+        owner: repo.owner,
+        name: repo.name,
+        requested_by: this.#requestedBy,
+      });
+      return { kind: "token", token: installation_token };
+    } catch (err) {
+      return { kind: "transient", error: err };
+    }
+  }
+}

package/src/inbox-handler.js

@@ -1,5 +1,4 @@
 import { bridge } from "@forwardimpact/libtype";
-import { createDefaultClock } from "@forwardimpact/libutil/runtime";
 
 /**
  * Long-poll handler for the per-correlation inbox. The run's InboxPoller
@@ -18,11 +17,21 @@ export function createInboxHandler({
   logger,
   pollTimeoutMs = 30_000,
   pollIntervalMs = 1_000,
-  clock = createDefaultClock(),
+  clock,
 }) {
+  if (!clock) throw new Error("clock is required");
   return async (c) => {
     const correlationId = c.req.param("correlationId");
     const sinceSeq = parseInt(c.req.query("since") ?? "0", 10);
+    // The dispatcher embeds the resolved tenant on the inbox URL it hands the
+    // run (single-tenant binds the literal `default`). `services/bridge`
+    // rejects a `DrainInbox` without a `tenant_id`, so a poll that omits it is
+    // a caller error: fail fast rather than leaking a cross-tenant queue.
+    const tenant_id = c.req.query("tenant_id");
+    if (!tenant_id) {
+      logger.error?.("inbox", "missing tenant_id");
+      return c.json({ error: "tenant_id required" }, 400);
+    }
     const deadline = clock.now() + pollTimeoutMs;
 
     while (clock.now() < deadline) {
@@ -31,6 +40,7 @@ export function createInboxHandler({
           bridge.DrainInboxRequest.fromObject({
             correlation_id: correlationId,
             since_seq: sinceSeq,
+            tenant_id,
           }),
         );
         if (result.messages?.length > 0) {

package/src/index.js

@@ -19,7 +19,7 @@
  * @property {() => Promise<void>} flush
  * @property {() => Promise<void>} shutdown
  * @property {(target: object) => Promise<void>} [putPendingDispatch]
- * @property {(linkToken: string) => Promise<object|null>} [resolvePendingDispatch]
+ * @property {(linkToken: string, expectedSurfaceUserId?: string) => Promise<object|null>} [resolvePendingDispatch]
  */
 
 export { createBridgeServer } from "./server.js";
@@ -29,16 +29,14 @@ export { appendHistory } from "./history.js";
 export { RateLimiter } from "./rate-limit.js";
 export { dispatchWorkflow } from "./dispatch.js";
 export { ProgressTicker } from "./progress-ticker.js";
-export {
-  Acknowledgement,
-  DEFAULT_TYPING_VERBS,
-} from "./acknowledgement.js";
+export { Acknowledgement, 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 { GhServerTokenResolver } from "./ghserver-token-resolver.js";
 export {
   CallbackHandlerError,
   createCallbackHandler,

package/src/link-resume.js

@@ -1,25 +1,81 @@
 import { randomUUID } from "node:crypto";
+import { isTrusted } from "@forwardimpact/libutil/trusted-origins";
+import { verifyCompletionTicket } from "@forwardimpact/libutil/completion-ticket";
 import { normalizeBaseUrl } from "./callback-payload.js";
 import { buildPrompt } from "./prompt.js";
 
 /**
- * @param {string} authorizeUrl
- * @param {string} callbackBaseUrl
- * @returns {{ linkToken: string, augmentedUrl: string }}
+ * Prepare a link-resume URL for the IdP authorize step.
+ *
+ * Discriminated return so a missing `catch` cannot become a 5xx oracle in
+ * the caller. The keyword-arg shape makes "forgot to pass trustedOrigins"
+ * a loud boot-time `TypeError` for any future xbridge.
+ *
+ * @param {object} args
+ * @param {string} args.authorizeUrl Upstream IdP authorize URL the bridge
+ *   intends to post into the channel.
+ * @param {string} args.callbackBaseUrl Bridge's own callback base URL; the
+ *   per-bridge `/api/link-complete` is composed from this.
+ * @param {Set<string>} args.trustedOrigins Trusted-origin set produced by
+ *   `loadTrustedIdpOrigins`. Required — a missing or non-Set value throws.
+ * @returns {{linkToken: string, augmentedUrl: string} | {skipped: true, reason: string}}
+ *   On a trusted, parseable URL: `{ linkToken, augmentedUrl }`. On any
+ *   refusal: `{ skipped: true, reason: "untrusted_origin" }`.
  */
-export function prepareLinkResume(authorizeUrl, callbackBaseUrl) {
+export function prepareLinkResume({
+  authorizeUrl,
+  callbackBaseUrl,
+  trustedOrigins,
+}) {
+  if (!(trustedOrigins instanceof Set))
+    throw new TypeError("prepareLinkResume: trustedOrigins must be a Set");
+  let originUrl;
+  try {
+    originUrl = new URL(authorizeUrl);
+  } catch {
+    return { skipped: true, reason: "untrusted_origin" };
+  }
+  if (!isTrusted(originUrl.origin, trustedOrigins))
+    return { skipped: true, reason: "untrusted_origin" };
+
   const linkToken = randomUUID();
-  const url = new URL(authorizeUrl);
-  url.searchParams.set(
+  originUrl.searchParams.set(
     "redirect_uri",
     `${normalizeBaseUrl(callbackBaseUrl)}/api/link-complete`,
   );
-  url.searchParams.set("client_state", linkToken);
-  return { linkToken, augmentedUrl: url.toString() };
+  originUrl.searchParams.set("client_state", linkToken);
+  return { linkToken, augmentedUrl: originUrl.toString() };
 }
 
+const UNABLE_TO_VERIFY_HTML =
+  "<!DOCTYPE html><html><body><h1>Unable to verify completion</h1>" +
+  "<p>The completion request could not be verified. Please try " +
+  "linking again from the conversation.</p></body></html>";
+
 /**
+ * Factory for the `/api/link-complete` GET handler.
+ *
+ * Handler ordering: the ticket is verified **before** any store touch —
+ * an attacker without a valid ticket exits at the verify step and never
+ * sees a present-vs-absent timing oracle on `linkToken`.
+ *
+ * The `surface_user_id` cross-check is performed **server-side** by passing
+ * `verify.claims.surfaceUserId` as `expectedSurfaceUserId` to
+ * `store.resolvePendingDispatch`. The bridge refuses to consume the entry
+ * on mismatch — so an attacker who minted a valid ticket against the
+ * victim's `link_token` (e.g. by driving the IdP round-trip under their
+ * own account with `client_state=victim_link_token`) cannot drain the
+ * auto-resume affordance: the bridge returns `{ unattributable: true }`
+ * and the entry stays available for the legitimate user.
+ *
  * @param {object} options
+ * @param {string} options.channel Channel id (e.g. `"github-discussions"`).
+ * @param {object} options.store
+ * @param {object} options.dispatcher
+ * @param {(ctx: object) => object} options.buildCallbackMeta
+ * @param {Set<string>} options.trustedOrigins Required.
+ * @param {string} options.ticketSecret Required.
+ * @param {{now: () => number}} options.clock Required.
  * @returns {(c: import("hono").Context) => Promise<Response>}
  */
 export function createLinkCompleteHandler({
@@ -27,7 +83,21 @@ export function createLinkCompleteHandler({
   store,
   dispatcher,
   buildCallbackMeta,
+  trustedOrigins,
+  ticketSecret,
+  clock,
 }) {
+  if (!(trustedOrigins instanceof Set))
+    throw new TypeError(
+      "createLinkCompleteHandler: trustedOrigins must be a Set",
+    );
+  if (typeof ticketSecret !== "string" || ticketSecret.length === 0)
+    throw new TypeError(
+      "createLinkCompleteHandler: ticketSecret must be a non-empty string",
+    );
+  if (!clock || typeof clock.now !== "function")
+    throw new TypeError("createLinkCompleteHandler: clock is required");
+
   return async (c) => {
     const linkToken = c.req.query("state");
     if (!linkToken) {
@@ -38,7 +108,22 @@ export function createLinkCompleteHandler({
       );
     }
 
-    const target = await store.resolvePendingDispatch(linkToken);
+    const ticket = c.req.query("ticket");
+    const verify = verifyCompletionTicket({
+      ticket,
+      expected: { linkToken },
+      trustedOrigins,
+      secret: ticketSecret,
+      now: clock.now(),
+    });
+    if (!verify.ok) {
+      return c.html(UNABLE_TO_VERIFY_HTML);
+    }
+
+    const target = await store.resolvePendingDispatch(
+      linkToken,
+      verify.claims.surfaceUserId,
+    );
     if (!target) {
       return c.html(
         "<!DOCTYPE html><html><body><h1>Already processed</h1>" +
@@ -46,6 +131,12 @@ export function createLinkCompleteHandler({
           "</p></body></html>",
       );
     }
+    if (target.unattributable) {
+      // Bridge refused to consume because the ticket's surfaceUserId does
+      // not match the pending row. The pending entry is left intact for
+      // the legitimate user.
+      return c.html(UNABLE_TO_VERIFY_HTML);
+    }
 
     const ctx = await store.loadByChannel(channel, target.discussion_id);
     if (!ctx) {

package/src/rate-limit.js

@@ -1,5 +1,3 @@
-import { createDefaultClock } from "@forwardimpact/libutil/runtime";
-
 /**
  * Sliding-window rate limiter. Operates on a caller-owned `dispatches: number[]`
  * array of timestamps and returns a structured result so callers can both
@@ -16,11 +14,8 @@ export class RateLimiter {
    * @param {number} [options.max] - Max dispatches allowed in the window (default: 5)
    * @param {import("@forwardimpact/libutil/runtime").Runtime["clock"]} [options.clock]
    */
-  constructor({
-    windowMs = 60_000,
-    max = 5,
-    clock = createDefaultClock(),
-  } = {}) {
+  constructor({ windowMs = 60_000, max = 5, clock } = {}) {
+    if (!clock) throw new Error("clock is required");
     this.#windowMs = windowMs;
     this.#max = max;
     this.#clock = clock;

package/src/resume-scheduler.js

@@ -1,5 +1,3 @@
-import { createDefaultClock } from "@forwardimpact/libutil/runtime";
-
 import { ElapsedScheduler } from "./elapsed-scheduler.js";
 import { evaluateTrigger, parseIsoDuration } from "./triggers.js";
 
@@ -36,7 +34,7 @@ export class ResumeScheduler {
     buildCallbackMeta = (ctx) => ({ discussionId: ctx.discussion_id }),
     buildResumeInputs = () => ({}),
     onDeclined = null,
-    clock = createDefaultClock(),
+    clock,
   }) {
     if (!dispatcher) throw new Error("dispatcher is required");
     if (!store) throw new Error("store is required");
@@ -49,6 +47,7 @@ export class ResumeScheduler {
     if (onDeclined != null && typeof onDeclined !== "function") {
       throw new Error("onDeclined must be a function");
     }
+    if (!clock) throw new Error("clock is required");
     this.#dispatcher = dispatcher;
     this.#store = store;
     this.#logger = logger ?? null;