Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

16.6 KB
Raw Blame
import { randomUUID } from "node:crypto";
import { type Context, Hono, type MiddlewareHandler } from "hono";
import { bodyLimit } from "hono/body-limit";
import { z } from "zod";
import type { AppVariables } from "../auth/guards";
import { createOpenTagTransport, type OpenTagTransport } from "./opentag";
import {
  handleOpenTagRun,
  type OpenTagAgentDeps,
  type PairedApprovals,
} from "./opentag-agent";
import { createExpoPushTransport } from "./push";
import type { DeliveryRouter } from "./router";
import type { DeliveryStore } from "./store";
import {
  createTwilioTransport,
  smsOptKeyword,
  type TwilioTransport,
  verifyTwilioRequest,
} from "./twilio";
import {
  DeliveryNotFoundError,
  DeliveryRefusedError,
  type DeliveryScope,
} from "./types";
export type DeliveryScopeResolver = (
  owner: string,
  channelId: string,
  agentId: string,
) => Promise<DeliveryScope | null>;
const targetSchema = z.strictObject({
  channelId: z.string().min(1),
  agentId: z.string().min(1),
});
async function ownedScope(
  resolve: DeliveryScopeResolver,
  owner: string,
  target: { channelId: string; agentId: string },
) {
  const scope = await resolve(owner, target.channelId, target.agentId);
  if (
    !scope ||
    scope.ownerUserId !== owner ||
    scope.channelId !== target.channelId ||
    scope.agentId !== target.agentId
  )
    throw new DeliveryRefusedError(
      "Choose an accessible Bot in your conversation.",
    );
  return scope;
}
function errorRoutes<E extends { Variables: AppVariables }>(routes: Hono<E>) {
  routes.onError((error, context) => {
    if (error instanceof DeliveryNotFoundError)
      return context.json({ error: error.message }, 404);
    if (
      error instanceof DeliveryRefusedError ||
      error instanceof z.ZodError ||
      error instanceof SyntaxError
    )
      return context.json(
        {
          error:
            error instanceof DeliveryRefusedError
              ? error.message
              : "Supply a valid request.",
        },
        400,
      );
    console.error(
      JSON.stringify({ type: "delivery-route-error", errorType: error.name }),
    );
    return context.json({ error: "Delivery is unavailable. Try again." }, 503);
  });
}
export function createDeliveryRoutes(deps: {
  store: DeliveryStore;
  router: Pick<DeliveryRouter, "receiveNative">;
  requireUser: MiddlewareHandler<{ Variables: AppVariables }>;
  scopeFor: DeliveryScopeResolver;
  listConversations(
    owner: string,
    cursor?: string,
  ): Promise<{ channels: unknown[]; nextCursor: string | null }>;
  history(scope: DeliveryScope): Promise<unknown>;
  /** The OpenTag pairing. Named `slack` for the existing assembly; it serves Slack and Teams. */
  slack?: OpenTagTransport;
  twilio?: TwilioTransport;
  pushProjectId?: string;
}) {
  const routes = new Hono<{ Variables: AppVariables }>();
  routes.use("*", deps.requireUser, bodyLimit({ maxSize: 64 * 1024 }));
  errorRoutes(routes);
  routes.get("/", async (c) =>
    c.json({
      bindings: await deps.store.listBindings(c.var.actor.id),
      devices: (await deps.store.devices(c.var.actor.id)).map(
        ({ token: _token, ...device }) => device,
      ),
      deliveries: await deps.store.history(c.var.actor.id),
      available: {
        slack: Boolean(deps.slack),
        teams: Boolean(deps.slack),
        sms: Boolean(deps.twilio),
        push: Boolean(deps.pushProjectId),
      },
    }),
  );
  routes.delete("/bindings/:id", async (c) => {
    await deps.store.removeBinding(c.var.actor.id, c.req.param("id"));
    return c.body(null, 204);
  });
  /**
   * Link a Slack or Teams identity through OpenTag. The one-time code is the challenge id; the person
   * sends `link <code>` to the OpenTag app, and OpenTag's authenticated sender becomes the binding.
   * `/slack/start` is kept as the Slack spelling of the same call.
   */
  const startChatLink = async (
    c: Context<{ Variables: AppVariables }>,
    fixed?: "slack" | "teams",
  ) => {
    if (!deps.slack)
      throw new DeliveryRefusedError(
        "Slack and Teams are not paired with OpenTag on this deployment.",
      );
    const input = targetSchema
      .extend({ platform: z.enum(["slack", "teams"]).optional() })
      .parse(await c.req.json());
    const platform = fixed ?? input.platform ?? "slack";
    const scope = await ownedScope(deps.scopeFor, c.var.actor.id, input);
    const code = await deps.store.challenge(scope, platform, null);
    return c.json({
      platform,
      code,
      command: `link ${code}`,
      expiresInMinutes: 10,
    });
  };
  routes.post("/opentag/start", (c) => startChatLink(c));
  routes.post("/slack/start", (c) => startChatLink(c, "slack"));
  routes.post("/teams/start", (c) => startChatLink(c, "teams"));
  routes.post("/sms/start", async (c) => {
    if (!deps.twilio)
      throw new DeliveryRefusedError(
        "SMS is not configured on this deployment.",
      );
    const target = targetSchema
      .extend({ phone: z.string().regex(/^\+[1-9]\d{7,14}$/) })
      .parse(await c.req.json());
    const scope = await ownedScope(deps.scopeFor, c.var.actor.id, target);
    await deps.twilio.startVerification(target.phone);
    return c.json({
      challengeId: await deps.store.challenge(scope, "sms", target.phone),
    });
  });
  routes.post("/sms/confirm", async (c) => {
    if (!deps.twilio)
      throw new DeliveryRefusedError(
        "SMS is not configured on this deployment.",
      );
    const input = z
      .strictObject({
        challengeId: z.string().uuid(),
        code: z.string().regex(/^\d{4,10}$/),
      })
      .parse(await c.req.json());
    const challenge = await deps.store.readChallenge(
      input.challengeId,
      c.var.actor.id,
    );
    if (challenge?.transport !== "sms" || !challenge.address)
      throw new DeliveryRefusedError(
        "This phone verification expired or was already used.",
      );
    const scope = await ownedScope(deps.scopeFor, c.var.actor.id, challenge);
    if (scope.threadId !== challenge.threadId)
      throw new DeliveryRefusedError(
        "The conversation changed. Start verification again.",
      );
    if (!(await deps.twilio.checkVerification(challenge.address, input.code)))
      throw new DeliveryRefusedError("The verification code was not approved.");
    if (!(await deps.store.consumeChallenge(challenge.id, c.var.actor.id)))
      throw new DeliveryRefusedError(
        "This phone verification was already used.",
      );
    return c.json(
      {
        binding: await deps.store.bind({
          ...scope,
          transport: "sms",
          identity: challenge.address,
          realm: deps.twilio.config.accountSid,
          address: challenge.address,
        }),
      },
      201,
    );
  });
  routes.post("/devices", async (c) => {
    if (!deps.pushProjectId)
      throw new DeliveryRefusedError(
        "Native push is not configured on this deployment.",
      );
    const input = z
      .strictObject({
        id: z.string().uuid(),
        token: z.string().regex(/^(Expo|Exponent)PushToken\[[A-Za-z0-9_-]+\]$/),
        projectId: z.string().uuid(),
        platform: z.enum(["ios", "android"]),
      })
      .parse(await c.req.json());
    if (input.projectId !== deps.pushProjectId)
      throw new DeliveryRefusedError(
        "This device belongs to another push project.",
      );
    const device = await deps.store.registerDevice({
      ...input,
      ownerUserId: c.var.actor.id,
    });
    return c.json(
      { device: { id: device?.id, enabled: device?.enabled } },
      201,
    );
  });
  routes.delete("/devices/:id", async (c) => {
    await deps.store.removeDevice(c.var.actor.id, c.req.param("id"));
    return c.body(null, 204);
  });
  routes.get("/conversations", async (c) => {
    const page = await deps.listConversations(
      c.var.actor.id,
      c.req.query("cursor"),
    );
    return c.json({
      conversations: page.channels,
      nextCursor: page.nextCursor,
    });
  });
  routes.get("/conversations/:id/history", async (c) => {
    const scope = await ownedScope(deps.scopeFor, c.var.actor.id, {
      channelId: c.req.param("id"),
      agentId: z.string().min(1).parse(c.req.query("agentId")),
    });
    return c.json({ history: await deps.history(scope) });
  });
  routes.post("/conversations/:id/messages", async (c) => {
    const input = z
      .strictObject({
        agentId: z.string().min(1),
        text: z.string().trim().min(1).max(16_000),
        externalId: z.string().uuid().default(randomUUID),
      })
      .parse(await c.req.json());
    const scope = await ownedScope(deps.scopeFor, c.var.actor.id, {
      channelId: c.req.param("id"),
      agentId: input.agentId,
    });
    return c.json(
      await deps.router.receiveNative(scope, input.text, input.externalId),
      202,
    );
  });
  return routes;
}
export function createDeliveryWebhookRoutes(deps: {
  router: Pick<DeliveryRouter, "receive" | "converse" | "notify" | "smsOptOut">;
  store: Pick<
    DeliveryStore,
    | "readChallenge"
    | "consumeChallenge"
    | "bind"
    | "updateSmsStatus"
    | "findBinding"
    | "botIdentity"
  >;
  scopeFor: DeliveryScopeResolver;
  /** The OpenTag pairing. Named `slack` for the existing assembly; it serves Slack and Teams. */
  slack?: OpenTagTransport;
  twilio?: TwilioTransport;
  /** Lets a Slack/Teams card decide an approval and a chat reply answer a Bot's question. */
  approvals?: PairedApprovals;
  /** Test seam; production uses the responsibilities lane's `ingestSlackEvent`. */
  ingestSlack?: OpenTagAgentDeps["ingestSlack"];
  /** Redeems OpenBot linked-account codes sent to the Slack app in a DM; cancels one posted in a channel. */
  identity?: OpenTagAgentDeps["identity"];
}) {
  const routes = new Hono<{ Variables: AppVariables }>();
  // A paired chat run carries its conversation's history, so it gets a larger envelope.
  const provider = bodyLimit({ maxSize: 256 * 1024 });
  const agentRun = bodyLimit({ maxSize: 4 * 1024 * 1024 });
  routes.use("*", (c, next) =>
    c.req.path.endsWith("/opentag/agent")
      ? agentRun(c, next)
      : provider(c, next),
  );
  errorRoutes(routes);
  if (deps.slack) {
    const opentag = deps.slack;
    routes.post("/opentag/agent", (c) =>
      handleOpenTagRun(
        {
          opentag,
          router: deps.router,
          store: deps.store,
          scopeFor: deps.scopeFor,
          ...(deps.approvals ? { approvals: deps.approvals } : {}),
          ...(deps.ingestSlack ? { ingestSlack: deps.ingestSlack } : {}),
          ...(deps.identity ? { identity: deps.identity } : {}),
        },
        c.req.raw,
      ),
    );
  }
  if (deps.twilio) {
    const twilio = deps.twilio;
    async function signed(request: Request, url: string) {
      if (
        !request.headers
          .get("content-type")
          ?.startsWith("application/x-www-form-urlencoded")
      )
        throw new DeliveryRefusedError("Twilio must send form data.");
      const params = new URLSearchParams(await request.text());
      return verifyTwilioRequest({
        url,
        params,
        token: twilio.config.authToken,
        signature: request.headers.get("x-twilio-signature"),
      })
        ? params
        : null;
    }
    routes.post("/sms", async (c) => {
      const params = await signed(c.req.raw, twilio.config.webhookUrl);
      if (!params) return c.json({ error: "Invalid Twilio signature." }, 401);
      if (
        params.get("AccountSid") !== twilio.config.accountSid ||
        params.get("To") !== twilio.config.from
      )
        return c.json({ error: "Unrecognised Twilio destination." }, 403);
      const from = params.get("From"),
        id = params.get("MessageSid"),
        text = params.get("Body");
      // Twilio answers these keywords itself and blocks sends after STOP, so OpenBot records the
      // state, runs no turn and sends no second reply (Advanced Opt-Out guidance).
      const keyword = smsOptKeyword(params.get("OptOutType"), text);
      if (from && keyword) {
        if (keyword !== "HELP")
          await deps.router.smsOptOut(
            twilio.config.accountSid,
            from,
            keyword === "STOP",
          );
        return c.body("<Response/>", 200, { "content-type": "text/xml" });
      }
      if (from && id && text)
        await deps.router.receive({
          source: "sms",
          realm: twilio.config.accountSid,
          identity: from,
          externalId: id,
          text,
        });
      return c.body("<Response/>", 200, { "content-type": "text/xml" });
    });
    if (twilio.config.statusUrl)
      routes.post("/sms/status", async (c) => {
        const params = await signed(c.req.raw, twilio.config.statusUrl ?? "");
        if (!params) return c.json({ error: "Invalid Twilio signature." }, 401);
        if (params.get("AccountSid") !== twilio.config.accountSid)
          return c.json({ error: "Unrecognised account." }, 403);
        const id = params.get("MessageSid"),
          status = params.get("MessageStatus");
        if (
          id &&
          (status === "delivered" ||
            status === "sent" ||
            status === "failed" ||
            status === "undelivered")
        )
          await deps.store.updateSmsStatus(
            id,
            status === "undelivered" ? "failed" : status,
            params.get("ErrorCode"),
          );
        return c.body(null, 204);
      });
  }
  return routes;
}

/** Deployment secrets come from its environment/vault injection; never return this object to UI. */
export function configuredDeliveryProviders(
  publicBaseUrl: string,
  env: Record<string, string | undefined> = process.env,
) {
  // Provider signatures (Twilio) are computed over the URL the provider was given, which is the
  // public webhook base (a tunnel or ingress), not necessarily the sign-in origin.
  const webhookBase = env.DELIVERY_PUBLIC_URL?.trim() || publicBaseUrl;
  if (!/^https?:\/\//.test(webhookBase))
    throw new Error("DELIVERY_PUBLIC_URL must be an http(s) URL.");
  const base = new URL(webhookBase).origin;
  function configured(names: string[]) {
    if (!names.some((name) => env[name]?.trim())) return null;
    const missing = names.filter((name) => !env[name]?.trim());
    if (missing.length)
      throw new Error(
        `Delivery configuration is incomplete: ${missing.join(", ")}.`,
      );
    return names.map((name) => env[name]?.trim() ?? "");
  }
  const legacySlack = [
    "SLACK_CLIENT_ID",
    "SLACK_CLIENT_SECRET",
    "SLACK_BOT_TOKEN",
    "SLACK_TEAM_ID",
    "SLACK_SIGNING_SECRET",
  ].filter((name) => env[name]?.trim());
  if (legacySlack.length)
    throw new Error(
      `Direct Slack delivery was replaced by the OpenTag pairing. Unset ${legacySlack.join(", ")} and set OPENTAG_SHARED_SECRET (and OPENTAG_URL for proactive messages).`,
    );
  const opentagSecret = env.OPENTAG_SHARED_SECRET?.trim();
  const opentagUrl = env.OPENTAG_URL?.trim();
  const opentagIcon = env.OPENTAG_BOT_ICON_URL_TEMPLATE?.trim();
  if ((opentagUrl || opentagIcon) && !opentagSecret)
    throw new Error(
      "Delivery configuration is incomplete: OPENTAG_SHARED_SECRET.",
    );
  if (opentagSecret && opentagSecret.length < 32)
    throw new Error("OPENTAG_SHARED_SECRET must be at least 32 characters.");
  if (opentagUrl && !/^https?:\/\//.test(opentagUrl))
    throw new Error("OPENTAG_URL must be an http(s) URL.");
  if (opentagIcon && !opentagIcon.startsWith("https://"))
    throw new Error("OPENTAG_BOT_ICON_URL_TEMPLATE must be an https URL.");
  const opentag = opentagSecret
    ? createOpenTagTransport({
        secret: opentagSecret,
        ...(opentagUrl ? { url: opentagUrl } : {}),
        ...(opentagIcon ? { iconUrlTemplate: opentagIcon } : {}),
      })
    : undefined;
  const smsValues = configured([
    "TWILIO_ACCOUNT_SID",
    "TWILIO_AUTH_TOKEN",
    "TWILIO_VERIFY_SERVICE_SID",
    "TWILIO_FROM_NUMBER",
  ]);
  const pushProjectId = env.EXPO_PROJECT_ID?.trim();
  if (pushProjectId && !z.uuid().safeParse(pushProjectId).success)
    throw new Error(
      "EXPO_PROJECT_ID must be the native app's EAS project UUID.",
    );
  return {
    // Slack and Teams share the OpenTag pairing: inbound turns, cards and proactive delivery.
    slack: opentag,
    teams: opentag,
    sms: smsValues
      ? createTwilioTransport({
          accountSid: smsValues[0] ?? "",
          authToken: smsValues[1] ?? "",
          verifyServiceSid: smsValues[2] ?? "",
          from: smsValues[3] ?? "",
          webhookUrl: `${base}/api/delivery/webhooks/sms`,
          statusUrl: `${base}/api/delivery/webhooks/sms/status`,
        })
      : undefined,
    push: pushProjectId
      ? createExpoPushTransport({
          projectId: pushProjectId,
          accessToken: env.EXPO_ACCESS_TOKEN,
        })
      : undefined,
    pushProjectId,
  };
}