@oneuptime/common 13.0.0 → 13.0.1

package/Server/Utils/CodeRepository/GitHub/GitHubCommandAuthorizer.ts

@@ -0,0 +1,274 @@
+import logger from "../../Logger";
+import CodeRepositoryType from "../../../../Types/CodeRepository/CodeRepositoryType";
+import SortOrder from "../../../../Types/BaseDatabase/SortOrder";
+import CodeRepository from "../../../../Models/DatabaseModels/CodeRepository";
+import ObjectID from "../../../../Types/ObjectID";
+import Project from "../../../../Models/DatabaseModels/Project";
+import CodeRepositoryService from "../../../Services/CodeRepositoryService";
+import ProjectService from "../../../Services/ProjectService";
+import GitHubInstallationBinding from "./GitHubInstallationBinding";
+import GitHubConversation, {
+  GitHubRepositoryPermission,
+} from "./GitHubConversation";
+import CaptureSpan from "../../Telemetry/CaptureSpan";
+
+/*
+ * Whether a GitHub command may run, and — just as important — whether the app
+ * should say anything about it.
+ *
+ * The threat this exists for: a connected repository's issue tracker is open
+ * to anyone with a GitHub account, and a mention costs nothing to write. So
+ * every command arrives as a request from an untrusted party, and there are
+ * two distinct failure modes to keep apart.
+ *
+ *   - A command the app cannot carry out (feature switched off, repository not
+ *     connected) is answered, because the person asking is a collaborator who
+ *     would otherwise think the integration is broken.
+ *
+ *   - A command from someone WITHOUT write access is not answered in the
+ *     thread at all. Replying would make the app a comment-poster that any
+ *     GitHub account can drive: one mention, one guaranteed comment, repeat.
+ *     It gets a single reaction on the offending comment instead — visible to
+ *     the author, idempotent, and useless as an amplifier.
+ */
+
+export enum GitHubAuthorizationOutcome {
+  // The command may proceed.
+  Allowed = "Allowed",
+  /*
+   * Not a command from a human this app should ever answer: a bot, or a
+   * repository this OneUptime instance has no connection to. Silence.
+   */
+  Ignore = "Ignore",
+  /*
+   * A real person without write access to the repository. React, do not
+   * reply — see the note above.
+   */
+  InsufficientPermission = "InsufficientPermission",
+  /*
+   * A collaborator asked, but the repository has GitHub commands switched
+   * off. Reply, so they know where the switch is.
+   */
+  CommandsDisabled = "CommandsDisabled",
+}
+
+export interface GitHubAuthorizationResult {
+  outcome: GitHubAuthorizationOutcome;
+  codeRepository?: CodeRepository | undefined;
+  /*
+   * The OneUptime project the app is acting for. Named in the acknowledgement
+   * comment: a repository can be connected to more than one project, and a
+   * team should never have to guess whose AI budget a command just spent.
+   */
+  projectName?: string | undefined;
+  // Filled for the outcomes that are answered in the thread.
+  reason?: string | undefined;
+}
+
+/*
+ * How many connected-repository rows to consider for one webhook. The same
+ * repository can be imported by several projects, and the app acts for exactly
+ * one of them — the oldest bound connection. This bounds the query; hitting it
+ * is logged rather than silently truncated.
+ */
+const MAX_CONNECTED_REPOSITORY_CANDIDATES: number = 10;
+
+export default class GitHubCommandAuthorizer {
+  /*
+   * The CodeRepository row a webhook's repository belongs to.
+   *
+   * Matched on organization + name + installation, then re-derived from the
+   * project: the row's installation ID is a value stored on a record, and the
+   * question "may this installation act for this project?" is only ever
+   * answered by GitHubInstallationBinding, never by the row itself. Same rule
+   * the repository-token endpoint applies before it mints a token.
+   *
+   * More than one project may have imported the same repository. Acting for
+   * all of them would mean one comment producing several pull requests, so the
+   * OLDEST connection wins — deterministic, and stable across redeliveries of
+   * the same webhook.
+   */
+  @CaptureSpan()
+  public static async resolveConnectedRepository(data: {
+    organizationName: string;
+    repositoryName: string;
+    installationId: string;
+  }): Promise<CodeRepository | null> {
+    const candidates: Array<CodeRepository> =
+      await CodeRepositoryService.findBy({
+        query: {
+          organizationName: data.organizationName,
+          repositoryName: data.repositoryName,
+          repositoryHostedAt: CodeRepositoryType.GitHub,
+          gitHubAppInstallationId: data.installationId,
+        },
+        select: {
+          _id: true,
+          projectId: true,
+          organizationName: true,
+          repositoryName: true,
+          mainBranchName: true,
+          gitHubAppInstallationId: true,
+          isGitHubCommandsEnabled: true,
+          gitHubTriggerLabel: true,
+        },
+        sort: { createdAt: SortOrder.Ascending },
+        limit: MAX_CONNECTED_REPOSITORY_CANDIDATES,
+        skip: 0,
+        props: { isRoot: true },
+      });
+
+    /*
+     * At the cap, a legitimate connection past the tenth is invisible — and
+     * would otherwise be indistinguishable from "not connected at all". Say so
+     * once, so an operator chasing a silently ignored command has something to
+     * find.
+     */
+    if (candidates.length === MAX_CONNECTED_REPOSITORY_CANDIDATES) {
+      logger.warn(
+        `${data.organizationName}/${data.repositoryName} matched the maximum of ${MAX_CONNECTED_REPOSITORY_CANDIDATES} connected repository rows for installation ${data.installationId}; any connection beyond that is not being considered.`,
+      );
+    }
+
+    for (const candidate of candidates) {
+      if (!candidate.projectId || !candidate.gitHubAppInstallationId) {
+        continue;
+      }
+
+      const isBound: boolean =
+        await GitHubInstallationBinding.isInstallationBoundToProject({
+          projectId: candidate.projectId,
+          installationId: candidate.gitHubAppInstallationId,
+        });
+
+      if (!isBound) {
+        logger.warn(
+          `Ignoring a GitHub command for ${data.organizationName}/${data.repositoryName}: installation ${data.installationId} is not bound to project ${candidate.projectId.toString()}.`,
+        );
+        continue;
+      }
+
+      if (candidates.length > 1) {
+        logger.info(
+          `${data.organizationName}/${data.repositoryName} is connected to ${candidates.length} OneUptime projects; acting for the oldest connection (project ${candidate.projectId.toString()}).`,
+        );
+      }
+
+      return candidate;
+    }
+
+    return null;
+  }
+
+  /*
+   * Whether this repository answers GitHub commands at all.
+   *
+   * A null column means enabled. The switch was added after the repositories
+   * were, and defaulting existing rows to "off" would mean the feature does
+   * nothing anywhere until every repository is visited by hand. Nothing
+   * happens until somebody deliberately types the mention regardless, so the
+   * safe default is also the useful one.
+   */
+  public static areCommandsEnabled(codeRepository: CodeRepository): boolean {
+    return codeRepository.isGitHubCommandsEnabled !== false;
+  }
+
+  @CaptureSpan()
+  public static async authorize(data: {
+    organizationName: string;
+    repositoryName: string;
+    installationId: string;
+    senderLogin: string;
+    // GitHub's own "is this a bot" signal from the webhook's sender object.
+    senderType: string | undefined;
+  }): Promise<GitHubAuthorizationResult> {
+    if (
+      !data.senderLogin ||
+      data.senderType?.toLowerCase() === "bot" ||
+      GitHubConversation.isBotLogin(data.senderLogin)
+    ) {
+      /*
+       * The loop guard. The app's own comments arrive here as webhooks, and so
+       * do every other bot's — neither is a human asking for work.
+       */
+      return { outcome: GitHubAuthorizationOutcome.Ignore };
+    }
+
+    const codeRepository: CodeRepository | null =
+      await GitHubCommandAuthorizer.resolveConnectedRepository({
+        organizationName: data.organizationName,
+        repositoryName: data.repositoryName,
+        installationId: data.installationId,
+      });
+
+    if (!codeRepository) {
+      /*
+       * The app is installed on a repository this instance has not connected
+       * to a project. It has no project to bill, no budget to check and no
+       * agent to run — and no standing to comment in someone's repository.
+       */
+      return { outcome: GitHubAuthorizationOutcome.Ignore };
+    }
+
+    if (!GitHubCommandAuthorizer.areCommandsEnabled(codeRepository)) {
+      return {
+        outcome: GitHubAuthorizationOutcome.CommandsDisabled,
+        codeRepository: codeRepository,
+        reason:
+          "GitHub commands are switched off for this repository. A project admin can turn them back on in OneUptime under Code Repositories → this repository → Settings.",
+      };
+    }
+
+    const permission: GitHubRepositoryPermission =
+      await GitHubConversation.getUserRepositoryPermission({
+        installationId: data.installationId,
+        organizationName: data.organizationName,
+        repositoryName: data.repositoryName,
+        username: data.senderLogin,
+      });
+
+    if (!GitHubConversation.canCommandApp(permission)) {
+      logger.info(
+        `Refusing a GitHub command from ${data.senderLogin} on ${data.organizationName}/${data.repositoryName}: repository permission is "${permission}".`,
+      );
+
+      return {
+        outcome: GitHubAuthorizationOutcome.InsufficientPermission,
+        codeRepository: codeRepository,
+      };
+    }
+
+    return {
+      outcome: GitHubAuthorizationOutcome.Allowed,
+      codeRepository: codeRepository,
+      projectName: await GitHubCommandAuthorizer.getProjectName(
+        codeRepository.projectId,
+      ),
+    };
+  }
+
+  /*
+   * The project's display name, for attribution in the thread. Never fails the
+   * command: a name is a nicety, and losing it is not a reason to refuse work.
+   */
+  private static async getProjectName(
+    projectId: ObjectID | undefined,
+  ): Promise<string | undefined> {
+    if (!projectId) {
+      return undefined;
+    }
+
+    try {
+      const project: Project | null = await ProjectService.findOneById({
+        id: projectId,
+        select: { _id: true, name: true },
+        props: { isRoot: true },
+      });
+
+      return project?.name || undefined;
+    } catch (error) {
+      logger.debug(`Could not read the project name for attribution: ${error}`);
+      return undefined;
+    }
+  }
+}

package/Server/Utils/CodeRepository/GitHub/GitHubCommandParser.ts

@@ -0,0 +1,375 @@
+import GitHubCommandType, {
+  GitHubCommand,
+  GitHubCommandSurface,
+} from "../../../../Types/CodeRepository/GitHubCommand";
+
+/*
+ * Named rather than inlined at the call sites: eslint's wrap-regex wants a
+ * regex literal that is the receiver of a method call wrapped in parentheses,
+ * and prettier removes those parentheses again — a fix loop with no fixed
+ * point. A named constant satisfies both, and reads better anyway.
+ */
+// A markdown blockquote line, including GitHub's nested "> >" quote-replies.
+const BLOCKQUOTE_LINE: RegExp = /^[ \t]*>/;
+// What may follow a verb for it to count as the whole verb.
+const VERB_TERMINATOR: RegExp = /^[\s:,.!?]/;
+// Whether an instruction contains a word at all.
+const ALPHANUMERIC: RegExp = /[A-Za-z0-9]/;
+
+/*
+ * One comment, in two index-aligned forms: `original` as the author wrote it
+ * (minus quotes and fenced blocks), and `searchable` with inline code blanked
+ * out to the same width. Mentions are found in `searchable`; the instruction
+ * is sliced out of `original`.
+ */
+interface StrippedBody {
+  original: string;
+  searchable: string;
+}
+
+interface VerbPhraseGroup {
+  phrases: Array<string>;
+  commandType: GitHubCommandType;
+}
+
+/*
+ * Turns the body of a GitHub issue / pull request comment into a command for
+ * the OneUptime app, or into null when the app was not addressed at all.
+ *
+ * Everything here is a PURE function of (body, appSlug, surface): no IO, no
+ * environment reads. That is deliberate — this is the gate that decides
+ * whether arbitrary text from a repository is allowed to start a paid agent
+ * run, so it has to be exhaustively testable on its own.
+ *
+ * Three properties matter more than richness of grammar:
+ *
+ *   1. A mention inside a QUOTE or a CODE BLOCK is not a command. GitHub's
+ *      "Quote reply" button copies the parent comment into a `>` block, so
+ *      without this every reply to one of the app's own comments would
+ *      re-trigger it — a comment loop that spends the project's fix budget.
+ *
+ *   2. A mention must be a whole word. `@oneuptime-staging` and
+ *      `support@oneuptime.com` are not mentions of `@oneuptime`.
+ *
+ *   3. An unrecognized verb is NOT an error. "@oneuptime the retry loop here
+ *      looks wrong" is the most natural way to ask for a revision, so the
+ *      surface decides the default: pull request -> Revise, issue ->
+ *      Implement. Only an EMPTY mention falls back to Help.
+ */
+export default class GitHubCommandParser {
+  /*
+   * Remove every region a mention must not count in, in the order they nest:
+   * fenced code blocks (which may themselves contain `>` lines and backticks),
+   * then inline code spans, then blockquotes.
+   *
+   * Fences are scanned line by line rather than with one regex: an UNCLOSED
+   * fence has to swallow the rest of the comment, and expressing that with a
+   * lazy quantifier and an end-of-input alternative is exactly the kind of
+   * subtlety that silently stops working.
+   */
+  private static stripNonCommandRegions(body: string): StrippedBody {
+    const lines: Array<string> = body.split("\n");
+    const original: Array<string> = [];
+    const searchable: Array<string> = [];
+
+    let openFence: string | null = null;
+
+    for (const line of lines) {
+      const fence: RegExpMatchArray | null = line.match(/^[ \t]*(```+|~~~+)/);
+
+      if (openFence) {
+        /*
+         * Inside a fence: only a closing fence of the SAME character and AT
+         * LEAST the same length ends it (CommonMark). Comparing only the
+         * character would let a ``` line inside a ```` block close it, and
+         * everything after would be read as live text — the loop guard
+         * failing open on exactly the comment most likely to contain a
+         * mention: one showing someone how to use the app.
+         */
+        if (
+          fence &&
+          fence[1] &&
+          fence[1][0] === openFence[0] &&
+          fence[1].length >= openFence.length
+        ) {
+          openFence = null;
+        }
+        continue;
+      }
+
+      if (fence && fence[1]) {
+        openFence = fence[1];
+        continue;
+      }
+
+      // Blockquotes, including the nested `> >` GitHub writes for quote-replies.
+      if (BLOCKQUOTE_LINE.test(line)) {
+        continue;
+      }
+
+      original.push(line);
+
+      /*
+       * Inline code is BLANKED, not removed — replaced by the same number of
+       * spaces. Removing it would shift every index after it, and the
+       * instruction is sliced out of the ORIGINAL text so that a request like
+       * "revise this to use \`Array<T>\`" reaches the agent with the code the
+       * person actually typed. Blanking keeps the two strings the same length,
+       * so one index means the same place in both.
+       */
+      searchable.push(
+        line.replace(/`[^`\n]*`/g, (match: string): string => {
+          return " ".repeat(match.length);
+        }),
+      );
+    }
+
+    return {
+      original: original.join("\n"),
+      searchable: searchable.join("\n"),
+    };
+  }
+
+  // Escape a GitHub App slug for safe embedding in a RegExp.
+  private static escapeForRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+
+  /*
+   * Matches `@slug` and `@slug[bot]` where a person actually addressed the app.
+   *
+   * Both guards are allow-lists rather than deny-lists, because the deny-list
+   * versions were wrong in ways that cost real money:
+   *
+   *   - LEADING. A negated ASCII class let "café@oneuptime.com" through — the
+   *     "é" is not an ASCII word character, so the address parsed as a mention
+   *     and started a paid run. An address's local part can end in any letter
+   *     in any script, so the only sound rule is to name what MAY precede a
+   *     mention: nothing (start of text), whitespace, or the punctuation
+   *     people actually wrap a mention in.
+   *
+   *   - TRAILING. `\b` sits happily between "oneuptime" and the "-" of
+   *     "@oneuptime-staging", a different account. And a plain
+   *     "not a letter or digit" lookahead let "@oneuptime.com is our site"
+   *     through. So a following "." is refused only when it starts something
+   *     domain-shaped; "thanks @oneuptime." at the end of a sentence is still
+   *     a mention.
+   */
+  private static buildMentionRegExp(appSlug: string): RegExp {
+    const slug: string = GitHubCommandParser.escapeForRegExp(appSlug.trim());
+
+    return new RegExp(
+      `(^|[\\s(\\[{*_~"'\`])@${slug}(\\[bot\\])?(?![A-Za-z0-9_-])(?!\\.[A-Za-z0-9])`,
+      "gi",
+    );
+  }
+
+  /*
+   * Explicit verbs that OVERRIDE the surface default. Longest phrases first so
+   * "code review" is not shadowed by "review".
+   *
+   * Deliberately small. Every phrase here is one a user could not plausibly
+   * mean any other way; anything ambiguous ("fix this", "sort this out") is
+   * better served by the surface default than by a guess.
+   */
+  private static readonly verbPhrases: Array<VerbPhraseGroup> = [
+    {
+      phrases: [
+        "code review",
+        "please review",
+        "can you review",
+        "review this",
+        "review",
+      ],
+      commandType: GitHubCommandType.Review,
+    },
+    {
+      phrases: [
+        "please revise",
+        "revise this",
+        "revise",
+        "rework this",
+        "rework",
+        "redo this",
+        "redo",
+      ],
+      commandType: GitHubCommandType.Revise,
+    },
+    {
+      phrases: [
+        "please implement",
+        "implement this",
+        "implement",
+        "work on this",
+        "work on it",
+        "pick this up",
+        "take this",
+      ],
+      commandType: GitHubCommandType.Implement,
+    },
+    {
+      phrases: ["what can you do", "commands", "usage", "help"],
+      commandType: GitHubCommandType.Help,
+    },
+    {
+      phrases: ["status", "progress"],
+      commandType: GitHubCommandType.Status,
+    },
+    {
+      phrases: ["cancel", "stop", "abort"],
+      commandType: GitHubCommandType.Cancel,
+    },
+  ];
+
+  /*
+   * The verb is only recognized at the START of the instruction. "@oneuptime
+   * the reviewer asked for X" must not be read as a Review command just
+   * because the word appears somewhere in it.
+   */
+  private static matchVerb(instruction: string): GitHubCommandType | null {
+    const normalized: string = instruction
+      .toLowerCase()
+      .replace(/^[\s:,.!?-]+/, "");
+
+    for (const entry of GitHubCommandParser.verbPhrases) {
+      for (const phrase of entry.phrases) {
+        if (normalized === phrase) {
+          return entry.commandType;
+        }
+
+        if (
+          normalized.startsWith(phrase) &&
+          VERB_TERMINATOR.test(normalized.slice(phrase.length))
+        ) {
+          return entry.commandType;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  private static defaultCommandFor(
+    surface: GitHubCommandSurface,
+  ): GitHubCommandType {
+    return surface === GitHubCommandSurface.PullRequest
+      ? GitHubCommandType.Revise
+      : GitHubCommandType.Implement;
+  }
+
+  /*
+   * Whether a candidate instruction says anything at all.
+   *
+   * "@mention 👍" and "@mention !!" are not requests to start work, but they
+   * are not empty strings either, so a bare truthiness check sent them to the
+   * surface default and spent a full agent run on a thumbs-up. A command needs
+   * a word in it.
+   */
+  private static hasSubstance(instruction: string): boolean {
+    return ALPHANUMERIC.test(instruction);
+  }
+
+  /*
+   * Returns null when the app was not mentioned in a commandable position —
+   * the overwhelmingly common case, since this runs on every comment in every
+   * connected repository.
+   *
+   * Every mention is considered, not just the first. A comment that mentions
+   * the app in passing and THEN gives it an order — "@oneuptime[bot] said it
+   * was flaky, so @oneuptime review this again" — is ordinary English, and
+   * reading only the first mention turns the order into part of an
+   * instruction string nobody wrote. So: the first mention followed by a
+   * recognized verb wins; failing that, the first mention that says anything
+   * at all; failing that, Help.
+   */
+  public static parse(data: {
+    body: string | null | undefined;
+    appSlug: string | null | undefined;
+    surface: GitHubCommandSurface;
+  }): GitHubCommand | null {
+    if (!data.body || !data.appSlug || !data.appSlug.trim()) {
+      return null;
+    }
+
+    const stripped: StrippedBody = GitHubCommandParser.stripNonCommandRegions(
+      data.body,
+    );
+
+    const mentionRegExp: RegExp = GitHubCommandParser.buildMentionRegExp(
+      data.appSlug,
+    );
+
+    let sawMention: boolean = false;
+    let firstSubstantive: GitHubCommand | null = null;
+    let mention: RegExpExecArray | null = null;
+
+    while ((mention = mentionRegExp.exec(stripped.searchable)) !== null) {
+      sawMention = true;
+
+      /*
+       * Sliced out of the ORIGINAL text at the same index — see
+       * stripNonCommandRegions for why the two strings stay index-aligned.
+       */
+      const instruction: string = stripped.original
+        .slice(mention.index + mention[0].length)
+        .trim();
+
+      if (!GitHubCommandParser.hasSubstance(instruction)) {
+        continue;
+      }
+
+      const verb: GitHubCommandType | null =
+        GitHubCommandParser.matchVerb(instruction);
+
+      if (verb) {
+        return { commandType: verb, instruction: instruction };
+      }
+
+      if (!firstSubstantive) {
+        firstSubstantive = {
+          commandType: GitHubCommandParser.defaultCommandFor(data.surface),
+          instruction: instruction,
+        };
+      }
+    }
+
+    if (firstSubstantive) {
+      return firstSubstantive;
+    }
+
+    if (sawMention) {
+      /*
+       * A mention with nothing to act on — bare, or only punctuation. A
+       * request for orientation, not a licence to start work on whatever the
+       * thread happens to be about.
+       */
+      return { commandType: GitHubCommandType.Help, instruction: "" };
+    }
+
+    return null;
+  }
+
+  /*
+   * Whether a command can be carried out on the surface it was written on.
+   * Kept beside the grammar so the two cannot drift: a Review on an issue and
+   * an Implement on a pull request are both real user mistakes that deserve a
+   * helpful reply rather than a silently dropped comment.
+   */
+  public static isSupportedOnSurface(data: {
+    commandType: GitHubCommandType;
+    surface: GitHubCommandSurface;
+  }): boolean {
+    if (
+      data.commandType === GitHubCommandType.Review ||
+      data.commandType === GitHubCommandType.Revise
+    ) {
+      return data.surface === GitHubCommandSurface.PullRequest;
+    }
+
+    if (data.commandType === GitHubCommandType.Implement) {
+      return data.surface === GitHubCommandSurface.Issue;
+    }
+
+    return true;
+  }
+}