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.

6.5 KB
Raw Blame
import { randomUUID } from "node:crypto";
import { Hono } from "hono";
import { type AuditStore, recordAuditEvent } from "../audit";
import type { AppVariables } from "../auth/guards";
import { type CredentialStore, encryptSecret } from "../credentials";
import { logLinkAuditFailure } from "./audit-failure";
import {
  exchangeGithubCode,
  fetchGithubUser,
  GithubOAuthError,
  githubRedirectUri,
  openGithubState,
} from "./github-oauth";
import { GITHUB_DOTCOM_REALM } from "./providers";
import type { IdentityStore } from "./store";
import { IdentityConflictError } from "./types";

export type GithubCallbackDeps = {
  clientId: string;
  clientSecret: string;
  publicUrl: string;
  appUrl: string | undefined;
  encryptionKey: string;
  personIsActive(userId: string): Promise<boolean>;
  credentials: Pick<CredentialStore, "create" | "revoke">;
  identity: Pick<IdentityStore, "linkVerified">;
  auditStore?: AuditStore;
  fetchImpl?: typeof fetch;
  now?: () => Date;
};

function logRefused(reason: string): void {
  console.warn(
    JSON.stringify({ type: "identity-github-callback-refused", reason }),
  );
}

// Only GithubOAuthError messages are logged: they are fixed sentences. Any other error's message
// could carry vendor or database text, so it contributes its name alone.
function logFailed(stage: string, error: unknown): void {
  console.error(
    JSON.stringify({
      type: "identity-github-callback-failed",
      stage,
      reason: error instanceof Error ? error.name : "unknown",
      ...(error instanceof GithubOAuthError ? { message: error.message } : {}),
    }),
  );
}

/**
 * Finishes linking a GitHub account when GitHub sends the person back.
 *
 * Every exit this router reaches is a redirect to GitHub's page under Connections, `?linked=github`,
 * `?linked=github-taken` (the account is already linked to another person) or `?linked=failed`. A request with no session never gets here: requireUser answers it with a 401
 * first. Each failed exit logs one line saying which refusal or stage it was; nothing the vendor
 * or the request carried (code, tokens, secret, state, account or session ids) is logged or returned.
 */
export function githubCallbackRoutes(
  deps: GithubCallbackDeps,
): Hono<{ Variables: AppVariables }> {
  const routes = new Hono<{ Variables: AppVariables }>();
  const base = `${(deps.appUrl ?? "").replace(/\/+$/, "")}/connections/github?linked=`;
  const now = deps.now ?? (() => new Date());

  routes.get("/", async (context) => {
    const failed = () => context.redirect(`${base}failed`, 302);
    let stage = "state";
    try {
      const code = context.req.query("code");
      if (context.req.query("error")) {
        logRefused("declined");
        return failed();
      }
      if (!code) {
        logRefused("no-code");
        return failed();
      }

      const state = await openGithubState(
        context.req.query("state"),
        deps.encryptionKey,
        now(),
      );
      if (!state) {
        logRefused("state-invalid");
        return failed();
      }

      // The signed-in session must be the person who started the link; otherwise a link started by
      // one person could attach another person's GitHub account to this session (login CSRF).
      const sessionUserId = context.var.actor?.id;
      if (!sessionUserId || sessionUserId !== state.userId) {
        logRefused("session-mismatch");
        return failed();
      }

      stage = "person";
      if (!(await deps.personIsActive(state.userId))) {
        logRefused("inactive-person");
        return failed();
      }

      stage = "exchange";
      const tokens = await exchangeGithubCode(
        {
          clientId: deps.clientId,
          clientSecret: deps.clientSecret,
          code,
          redirectUri: githubRedirectUri(deps.publicUrl),
        },
        deps.fetchImpl,
        now(),
      );
      stage = "user";
      const user = await fetchGithubUser(tokens.accessToken, deps.fetchImpl);

      // Every connection stores its token under a key of its own, so it never collides with the
      // token a reconnect replaces (one live credential per key). Nothing reads this token by key:
      // the link names it by id, and linkVerified revokes the token the link named before in the
      // same transaction that repoints it. That keeps one live token per person and account, and
      // a link write that fails leaves the existing link and its token exactly as they were.
      stage = "store";
      const stored = await deps.credentials.create({
        kind: "connector",
        provider: "github-user-token",
        keyId: `${state.userId}:${user.id}:${randomUUID()}`,
        metadata: { login: user.login },
        encryptedValue: await encryptSecret(
          deps.encryptionKey,
          JSON.stringify(tokens),
        ),
      });

      stage = "link";
      let link: Awaited<ReturnType<IdentityStore["linkVerified"]>>;
      try {
        link = await deps.identity.linkVerified(
          {
            provider: "github",
            realm: GITHUB_DOTCOM_REALM,
            subject: String(user.id),
          },
          state.userId,
          { method: "oauth", handle: user.login, credentialId: stored.id },
        );
      } catch (error) {
        // Only the token this attempt stored; the existing link's token was never touched.
        try {
          await deps.credentials.revoke(stored.id);
        } catch (revokeError) {
          // Already revoked or unreachable: the redirect below is the answer either way.
          logFailed("revoke", revokeError);
        }
        // The account belongs to a different person. Say so, without saying whose: retrying can
        // never work, so `?linked=failed` ("try again") would mislead.
        if (error instanceof IdentityConflictError) {
          logFailed("link", error);
          return context.redirect(`${base}github-taken`, 302);
        }
        throw error;
      }

      // The link and its token are live from here on. A failed audit write is logged and does not
      // turn the redirect into `?linked=failed`, whose notice says nothing was saved.
      if (deps.auditStore) {
        await recordAuditEvent(deps.auditStore, {
          eventType: "identity.linked",
          targetType: "identity_link",
          targetId: link.id,
          actorUserId: state.userId,
          payload: { actor: state.userId, provider: "github" },
        }).catch((error) => logLinkAuditFailure("github", error));
      }
      return context.redirect(`${base}github`, 302);
    } catch (error) {
      logFailed(stage, error);
      return failed();
    }
  });

  return routes;
}