@opengeni/api-router 0.30.3 → 1.0.0

package/src/github-access.ts

@@ -1,15 +1,63 @@
-import type {
-  GitHubBindingStatus,
-  GitHubInstallationBinding,
-  GitHubRepository,
+import {
+  defaultRepositoryMountPath,
+  type GitHubAppRepositoryBranchPage,
+  type GitHubBindingStatus,
+  type GitHubInstallationBinding,
+  type GitHubRepository,
+  type RepositoryResourceRef,
 } from "@opengeni/contracts";
 import {
+  GitHubRepositoryBranchesResponse as GitHubRepositoryBranchesResponseSchema,
+  type GitHubRepositoryBranchesResponse,
+  type ListGitHubRepositoryBranchesQuery,
+} from "@opengeni/contracts/github-repository-contracts";
+import {
+  areGitHubRepositoriesAllowedForWorkspace,
   hasAuditableGitHubInstallationAuthority,
   listGitHubInstallationAccessForWorkspace,
 } from "@opengeni/db";
-import { listGitHubAppInstallationSummaries, listGitHubAppRepositories } from "@opengeni/github";
+import {
+  GitHubAppApiError,
+  listGitHubAppInstallationSummaries,
+  listGitHubAppRepositories,
+  listGitHubAppRepositoryBranches,
+} from "@opengeni/github";
 import type { ApiRouteDeps } from "@opengeni/core";
 
+export type GitHubRepositoryBranchAuthorityErrorCode = "changed" | "not_authorized";
+
+export class GitHubRepositoryBranchAuthorityError extends Error {
+  constructor(readonly code: GitHubRepositoryBranchAuthorityErrorCode) {
+    super(code);
+    this.name = "GitHubRepositoryBranchAuthorityError";
+  }
+}
+
+export type WorkspaceGitHubRepositoryBranchServices = {
+  listInstallationAccess: typeof listGitHubInstallationAccessForWorkspace;
+  areRepositoriesAllowed: typeof areGitHubRepositoriesAllowedForWorkspace;
+  listProviderBranches: (
+    deps: ApiRouteDeps,
+    input: {
+      installationId: number;
+      repositoryId: number;
+      page: number;
+      limit: number;
+    },
+  ) => Promise<GitHubAppRepositoryBranchPage | null>;
+};
+
+const workspaceGitHubRepositoryBranchServices: WorkspaceGitHubRepositoryBranchServices = {
+  listInstallationAccess: listGitHubInstallationAccessForWorkspace,
+  areRepositoriesAllowed: areGitHubRepositoriesAllowedForWorkspace,
+  listProviderBranches: async (deps, input) =>
+    deps.githubAppApi?.listRepositoryBranches
+      ? await deps.githubAppApi.listRepositoryBranches(input)
+      : deps.githubAppApi
+        ? null
+        : await listGitHubAppRepositoryBranches(deps.settings, input),
+};
+
 export async function listWorkspaceGitHubInstallationBindings(
   deps: ApiRouteDeps,
   workspaceId: string,
@@ -153,3 +201,97 @@ export async function listWorkspaceGitHubRepositories(
     return installation.repositoryIds.includes(repository.id);
   });
 }
+
+/**
+ * The exact session repository resource for one workspace GitHub App
+ * repository: its default branch, a canonical clone URI, and the installation
+ * identity that platform-brokered Git auth and create-time validation check.
+ */
+export function githubRepositoryResourceRef(repository: GitHubRepository): RepositoryResourceRef {
+  const uri = normalizedRepositoryUri(repository.cloneUrl);
+  return {
+    kind: "repository",
+    uri,
+    ref: repository.defaultBranch,
+    provider: "github",
+    mountPath: defaultRepositoryMountPath(uri, "github"),
+    githubInstallationId: repository.installationId,
+    githubRepositoryId: repository.id,
+  };
+}
+
+function normalizedRepositoryUri(value: string): string {
+  const url = new URL(value);
+  const path = url.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/, "");
+  return `https://${url.host.toLowerCase()}/${path}.git`;
+}
+
+export async function listWorkspaceGitHubRepositoryBranches(
+  deps: ApiRouteDeps,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    installationId: number;
+    repositoryId: number;
+    query: ListGitHubRepositoryBranchesQuery;
+  },
+  services: WorkspaceGitHubRepositoryBranchServices = workspaceGitHubRepositoryBranchServices,
+): Promise<GitHubRepositoryBranchesResponse> {
+  const installations = await services.listInstallationAccess(deps.db, input.workspaceId);
+  const installation = installations.find(
+    (candidate) => candidate.installationId === input.installationId,
+  );
+  if (
+    !installation ||
+    installation.accountId !== input.accountId ||
+    !hasAuditableGitHubInstallationAuthority(installation) ||
+    !installation.repositoryIds.includes(input.repositoryId)
+  ) {
+    throw new GitHubRepositoryBranchAuthorityError("not_authorized");
+  }
+  if (
+    !(await services.areRepositoriesAllowed(deps.db, input.workspaceId, input.installationId, [
+      input.repositoryId,
+    ]))
+  ) {
+    throw new GitHubRepositoryBranchAuthorityError("changed");
+  }
+  const page = await services.listProviderBranches(deps, {
+    installationId: input.installationId,
+    repositoryId: input.repositoryId,
+    page: input.query.cursor,
+    limit: input.query.limit,
+  });
+  if (!page) {
+    throw new GitHubAppApiError(
+      "The configured GitHub provider cannot list exact repository branches",
+    );
+  }
+  if (
+    page.installationId !== input.installationId ||
+    page.repositoryId !== input.repositoryId ||
+    page.branches.length > input.query.limit ||
+    (page.nextPage !== null && page.nextPage !== input.query.cursor + 1) ||
+    (page.branches.length < input.query.limit && page.nextPage !== null)
+  ) {
+    throw new GitHubAppApiError("GitHub returned an invalid repository branches page");
+  }
+  const response = GitHubRepositoryBranchesResponseSchema.safeParse({
+    branches: page.branches.map((name) => ({
+      name,
+      isDefault: name === page.defaultBranch,
+    })),
+    nextCursor: page.nextPage,
+  });
+  if (!response.success) {
+    throw new GitHubAppApiError("GitHub returned an invalid repository branches page");
+  }
+  if (
+    !(await services.areRepositoriesAllowed(deps.db, input.workspaceId, input.installationId, [
+      input.repositoryId,
+    ]))
+  ) {
+    throw new GitHubRepositoryBranchAuthorityError("changed");
+  }
+  return response.data;
+}

package/src/http/acting-person.ts

@@ -0,0 +1,71 @@
+import type { Permission } from "@opengeni/contracts";
+import { verifiedDelegatedHumanAuthorizationForRequest } from "@opengeni/core";
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+/* ----------------------------------------------------------------------------
+   An agent acting as a person: an organization MCP action this server
+   dispatched in process for someone who signed the agent in (see
+   organization-mcp.ts). Routes that otherwise need the person's browser
+   cookie accept it, within the connection's organization and access setting.
+   The person's live role is still checked by the route, exactly as for the
+   browser.
+
+   Only Opengeni sign-in, approving a connection, third-party provider consent
+   and account recovery stay in the browser; those routes don't call this.
+   -------------------------------------------------------------------------- */
+
+export type ActingPerson = { subjectId: string };
+
+/** True when this request is an agent acting as a person. */
+export function isAgentActingAsPerson(c: Context): boolean {
+  return verifiedDelegatedHumanAuthorizationForRequest(c.req.raw) !== null;
+}
+
+/**
+ * The person this agent acts as, for an action in `organizationId` that needs
+ * `permission`; null when the request is not an agent acting as a person.
+ * Another organization reads as not found; a permission the connection's
+ * access setting leaves out is refused.
+ */
+export function agentActingAsPerson(
+  c: Context,
+  organizationId: string,
+  permission: Permission,
+): ActingPerson | null {
+  const proof = verifiedDelegatedHumanAuthorizationForRequest(c.req.raw);
+  if (!proof) return null;
+  if (proof.organizationId.toLowerCase() !== organizationId.toLowerCase()) {
+    throw new HTTPException(404, { message: "organization not found" });
+  }
+  if (!proof.permissions.includes(permission)) {
+    throw new HTTPException(403, {
+      message: `This connection's access doesn't include ${permission}.`,
+    });
+  }
+  return { subjectId: proof.subjectId };
+}
+
+/**
+ * The person an agent acts as, with no organization or permission check here:
+ * only for a route that next requires this same person's workspace grant,
+ * which carries the connection's organization, workspaces and access.
+ */
+export function agentActingAsPersonBeforeGrantCheck(c: Context): ActingPerson | null {
+  const proof = verifiedDelegatedHumanAuthorizationForRequest(c.req.raw);
+  return proof ? { subjectId: proof.subjectId } : null;
+}
+
+/** Organization settings: reading needs account:read, changing needs account:admin. */
+export function organizationSettingsPermission(c: Context): Permission {
+  return c.req.method === "GET" || c.req.method === "HEAD" ? "account:read" : "account:admin";
+}
+
+/** Refuse an agent on a browser-only step (provider consent, cross-organization actions). */
+export function requireNotAgent(c: Context, what: string): void {
+  if (isAgentActingAsPerson(c)) {
+    throw new HTTPException(403, {
+      message: `${what} has to be done by the person in the Opengeni app in a browser.`,
+    });
+  }
+}

package/src/http/api-contract-compat.ts

@@ -0,0 +1,49 @@
+import type { MiddlewareHandler } from "hono";
+import { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "@opengeni/contracts";
+
+const BEARER_AUTHORIZATION = /^bearer\s+\S/i;
+
+/**
+ * Keep published SDKs working across additive contract-revision bumps.
+ *
+ * Every `@opengeni/sdk` release up to 7.x throws `OpenGeniApiContractMismatchError`
+ * on ANY response whose `x-opengeni-api-contract` header differs from the
+ * revision it was built with, reads included. The header exists to make a
+ * stale first-party browser tab reload (docs/design/api-compatibility-policy.md
+ * (e)); a backend integration pinned to an SDK version cannot reload, so the
+ * next additive revision bump would break every call it makes.
+ *
+ * For a bearer-authenticated caller (API key, delegated token) that announced a
+ * different revision, the response therefore omits the header instead of
+ * advertising one the caller is known to reject. Cookie/unauthenticated
+ * callers (the stock web app) keep it, and so does an explicit
+ * `API_CONTRACT_CHANGED` refusal, so a refused client can still explain the
+ * mismatch. This is not an authorization boundary: routes authorize as usual.
+ */
+export function bearerApiContractHeaderCompatibility(): MiddlewareHandler {
+  return async (context, next) => {
+    await next();
+    const claimed = context.req.header(OPENGENI_API_CONTRACT_HEADER);
+    if (claimed === undefined || claimed === OPENGENI_API_CONTRACT_REVISION) return;
+    if (!BEARER_AUTHORIZATION.test(context.req.header("authorization") ?? "")) return;
+    if (!context.res.headers.has(OPENGENI_API_CONTRACT_HEADER)) return;
+    if (context.res.status === 409 && (await isContractRefusal(context.res))) return;
+    try {
+      context.res.headers.delete(OPENGENI_API_CONTRACT_HEADER);
+    } catch {
+      // Immutable headers (a proxied or redirect response): copy once.
+      context.res = new Response(context.res.body, context.res);
+      context.res.headers.delete(OPENGENI_API_CONTRACT_HEADER);
+    }
+  };
+}
+
+async function isContractRefusal(response: Response): Promise<boolean> {
+  if (!/^application\/json/i.test(response.headers.get("content-type") ?? "")) return false;
+  try {
+    const body = (await response.clone().json()) as { code?: unknown };
+    return body?.code === "API_CONTRACT_CHANGED";
+  } catch {
+    return false;
+  }
+}

package/src/http/api-error.ts

@@ -1,4 +1,11 @@
-import type { ErrorCode } from "@opengeni/contracts";
+import {
+  AgentConfigError,
+  AllowanceExhaustedRefusal,
+  ModelUnavailableError,
+  ScheduledTaskTargetAccessChange,
+  type ErrorCode,
+} from "@opengeni/contracts";
+import { WorkspaceControlBusyError } from "@opengeni/db";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 import { HTTPException } from "hono/http-exception";
 
@@ -6,6 +13,7 @@ type ApiHttpErrorOptions = {
   code: ErrorCode;
   message: string;
   retryable?: boolean;
+  outcomeUnknown?: boolean;
   details?: Record<string, unknown>;
 };
 
@@ -13,6 +21,7 @@ type ApiHttpErrorOptions = {
 export class ApiHttpError extends HTTPException {
   readonly code: ErrorCode;
   readonly retryable: boolean | undefined;
+  readonly outcomeUnknown: boolean | undefined;
   readonly details: Record<string, unknown> | undefined;
 
   constructor(status: number, options: ApiHttpErrorOptions) {
@@ -20,6 +29,111 @@ export class ApiHttpError extends HTTPException {
     this.name = "ApiHttpError";
     this.code = options.code;
     this.retryable = options.retryable;
+    this.outcomeUnknown = options.outcomeUnknown;
     this.details = options.details;
   }
 }
+
+export function scheduledTaskTargetAccessHttpError(error: unknown): ApiHttpError | null {
+  if (!(error instanceof HTTPException) || error.status !== 409) return null;
+  const result = ScheduledTaskTargetAccessChange.safeParse(error.cause);
+  return result.success
+    ? new ApiHttpError(409, {
+        code: "conflict",
+        message: error.message,
+        retryable: false,
+        outcomeUnknown: false,
+        details: result.data,
+      })
+    : null;
+}
+
+/** Preserve typed admission details through the common public error envelope. */
+export function allowanceExhaustedHttpError(error: unknown): ApiHttpError | null {
+  if (!(error instanceof HTTPException) || error.status !== 402) return null;
+  const parsed = AllowanceExhaustedRefusal.safeParse(
+    error.cause && typeof error.cause === "object"
+      ? Object.fromEntries(Object.entries(error.cause).filter(([key]) => key !== "allowed"))
+      : error.cause,
+  );
+  if (!parsed.success) return null;
+  const { code, message, ...details } = parsed.data;
+  return new ApiHttpError(402, {
+    code,
+    message,
+    retryable: false,
+    outcomeUnknown: false,
+    details,
+  });
+}
+
+/**
+ * A request-scoped session/workspace mutation could not enter the workspace
+ * control prefix within its bounded wait. The transaction rolled back before
+ * any write, so the outcome is known and the client may retry. `app.onError`
+ * applies this once for every route; Slack interactions keep the raw typed
+ * error so their retry classifier treats it as transient.
+ */
+export function workspaceControlBusyHttpError(error: unknown): ApiHttpError | null {
+  const busy =
+    error instanceof WorkspaceControlBusyError
+      ? error
+      : error instanceof HTTPException && error.cause instanceof WorkspaceControlBusyError
+        ? error.cause
+        : null;
+  if (!busy) return null;
+  return new ApiHttpError(503, {
+    code: "upstream_unavailable",
+    message: "The workspace is busy applying other session commands; retry shortly.",
+    retryable: true,
+    outcomeUnknown: false,
+    details: { code: busy.code, lockTimeoutMs: busy.lockTimeoutMs },
+  });
+}
+
+/**
+ * A typed agent-configuration failure (capability unavailable, conflict,
+ * widening, not enabled). Rendered as 422 validation_failed with the specific
+ * code in `details.code` so clients can branch without parsing messages.
+ */
+export function agentConfigHttpError(error: unknown): ApiHttpError | null {
+  const cause =
+    error instanceof AgentConfigError
+      ? error
+      : error instanceof HTTPException && error.cause instanceof AgentConfigError
+        ? error.cause
+        : null;
+  if (!cause) return null;
+  return new ApiHttpError(422, {
+    code: "validation_failed",
+    message: cause.message,
+    retryable: false,
+    details: {
+      code: cause.code,
+      ...(cause.capability ? { capability: cause.capability } : {}),
+    },
+  });
+}
+
+/**
+ * The requested or stored model is not in the live catalog. Rendered as the
+ * same 422 `validation_failed` with its historical message, plus
+ * `details.code: "model_unavailable"` and the model id so clients can ask for
+ * another model rather than offer a retry that cannot succeed.
+ */
+export function modelUnavailableHttpError(error: unknown): ApiHttpError | null {
+  const cause =
+    error instanceof ModelUnavailableError
+      ? error
+      : error instanceof HTTPException && error.cause instanceof ModelUnavailableError
+        ? error.cause
+        : null;
+  if (!cause) return null;
+  return new ApiHttpError(422, {
+    code: "validation_failed",
+    message: cause.message,
+    retryable: false,
+    outcomeUnknown: false,
+    details: { code: cause.code, modelId: cause.modelId },
+  });
+}

package/src/http/auth.ts

@@ -1,10 +1,20 @@
 import { resolveFirstPartyDelegationSecret, type Settings } from "@opengeni/config";
 import { verifyDelegatedAccessToken } from "@opengeni/contracts";
+import { verifiedDelegatedHumanAuthorizationForRequest } from "@opengeni/core";
 import type { Context, MiddlewareHandler } from "hono";
+import { ANALYTICS_CONSENT_PATH } from "../routes/analytics-consent";
+import { CLIENT_ERRORS_PATH } from "../routes/client-errors";
 import { installExactPaths, isInstallRedirectPath } from "../routes/install";
+import {
+  isMcpOAuthPublicProtocolPath,
+  isMcpOAuthResourcePath,
+  mcpOAuthBearerToken,
+} from "../mcp-oauth";
 
 const githubConnectPathPattern = /^\/v1\/workspaces\/[^/]+\/github\/connect$/;
 const githubInstallationLinkPathPattern = /^\/v1\/workspaces\/[^/]+\/github\/installations$/;
+const prReviewGithubBrowserPathPattern =
+  /^\/v1\/workspaces\/[^/]+\/pr-review\/github\/(?:connect|installations\/select|installations\/[^/]+\/configure)$/;
 
 export function requireAccessKey(settings: Settings): MiddlewareHandler {
   return async (c, next) => {
@@ -30,16 +40,43 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (c.req.method === "OPTIONS") {
     return true;
   }
+  // An organization MCP action dispatched in this process for a verified
+  // person. Only server code can stamp the exact Request object.
+  if (verifiedDelegatedHumanAuthorizationForRequest(c.req.raw)) {
+    return true;
+  }
   const path = new URL(c.req.url).pathname;
+  if (settings.mcpOauthEnabled && isMcpOAuthPublicProtocolPath(path)) {
+    return true;
+  }
+  if (settings.mcpOauthEnabled && isMcpOAuthResourcePath(path) && mcpOAuthBearerToken(c.req.raw)) {
+    return true;
+  }
   if (path === "/v1/config/client") {
     return true;
   }
+  // The web error beacon must count failures before sign-in. Its payload is a
+  // closed, content-free report and the route bounds its own admission.
+  if (c.req.method === "POST" && path === CLIENT_ERRORS_PATH) {
+    return true;
+  }
+  // The analytics banner is answered before sign-in too. The report is one
+  // closed decision and the route bounds its own admission.
+  if (c.req.method === "POST" && path === ANALYTICS_CONSENT_PATH) {
+    return true;
+  }
   if (path === "/v1/auth" || path.startsWith("/v1/auth/")) {
     return true;
   }
   if (path === "/v1/webhooks/stripe") {
     return true;
   }
+  if (c.req.method === "POST" && path.startsWith("/v1/webhooks/automations/")) {
+    return true;
+  }
+  if (c.req.method === "POST" && path === "/v1/webhooks/pr-review/github") {
+    return true;
+  }
   if (
     path === "/v1/github/setup" ||
     path === "/v1/github/install/callback" ||
@@ -48,9 +85,17 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   ) {
     return true;
   }
+  if (
+    path === "/v1/pr-review/github/setup" ||
+    path === "/v1/pr-review/github/install/callback" ||
+    path === "/v1/pr-review/github/oauth/callback"
+  ) {
+    return true;
+  }
   if (
     path === "/v1/integrations/oauth/callback" ||
     path === "/v1/integrations/provider-oauth/callback" ||
+    path === "/v1/integrations/github-personal/oauth/callback" ||
     path === "/v1/integrations/google-drive/callback" ||
     path === "/v1/integrations/oauth/client-metadata.json" ||
     path === "/v1/integrations/slack/callback" ||
@@ -79,6 +124,9 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (githubConnectPathPattern.test(path)) {
     return true;
   }
+  if (prReviewGithubBrowserPathPattern.test(path)) {
+    return true;
+  }
   // Compatibility endpoint for stale chooser submissions. It remains public
   // only so already-rendered forms can authenticate their signed account and
   // workspace state locally before terminating with 410; it does not parse a

package/src/http/cors.ts

@@ -1,3 +1,70 @@
+import { HTTPException } from "hono/http-exception";
+
 export function allowedCorsOrigin(pattern: string, origin: string): boolean {
   return new RegExp(`^(?:${pattern})$`).test(origin);
 }
+
+export function validateInteractionRequestOrigin(
+  value: string | undefined,
+  input: {
+    corsAllowOriginRegex: string;
+    publicBaseUrl?: string | undefined;
+    webBaseUrl?: string | undefined;
+  },
+): string | null {
+  if (!value) return null;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new HTTPException(400, { message: "invalid request origin" });
+  }
+  if (
+    url.origin === "null" ||
+    (url.protocol !== "http:" && url.protocol !== "https:") ||
+    url.origin !== value
+  ) {
+    throw new HTTPException(400, { message: "invalid request origin" });
+  }
+  if (isConfiguredBrowserOrigin(url.origin, input)) {
+    return url.origin;
+  }
+  throw new HTTPException(403, { message: "request origin is not allowed" });
+}
+
+type BrowserOriginSettings = {
+  corsAllowOriginRegex: string;
+  publicBaseUrl?: string | undefined;
+  webBaseUrl?: string | undefined;
+};
+
+function isConfiguredBrowserOrigin(origin: string, input: BrowserOriginSettings): boolean {
+  return (
+    allowedCorsOrigin(input.corsAllowOriginRegex, origin) ||
+    [input.publicBaseUrl, input.webBaseUrl].some((baseUrl) =>
+      baseUrl ? new URL(baseUrl).origin === origin : false,
+    )
+  );
+}
+
+/**
+ * Whether a present `Origin` header names a browser origin this deployment
+ * serves its web app from: the CORS allowlist, the public base URL, or the
+ * separate web base URL. `null` and malformed values are never allowed.
+ */
+export function isAllowedBrowserOrigin(value: string, input: BrowserOriginSettings): boolean {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (
+    url.origin === "null" ||
+    (url.protocol !== "http:" && url.protocol !== "https:") ||
+    url.origin !== value
+  ) {
+    return false;
+  }
+  return isConfiguredBrowserOrigin(url.origin, input);
+}