@opengeni/api-router 3.0.1 → 3.0.2-canary.38894290271001

package/src/github-access.ts

@@ -1,8 +1,10 @@
-import type {
-  GitHubAppRepositoryBranchPage,
-  GitHubBindingStatus,
-  GitHubInstallationBinding,
-  GitHubRepository,
+import {
+  defaultRepositoryMountPath,
+  type GitHubAppRepositoryBranchPage,
+  type GitHubBindingStatus,
+  type GitHubInstallationBinding,
+  type GitHubRepository,
+  type RepositoryResourceRef,
 } from "@opengeni/contracts";
 import {
   GitHubRepositoryBranchesResponse as GitHubRepositoryBranchesResponseSchema,
@@ -200,6 +202,30 @@ export async function listWorkspaceGitHubRepositories(
   });
 }
 
+/**
+ * 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: {

package/src/github-browser-flow.ts

@@ -5,7 +5,7 @@ import type { GitHubSignedStatePayload } from "@opengeni/github";
 
 /**
  * Bounded configured-token browser handoff. These signed claims preserve only
- * the exact OpenGeni github:manage grant across GitHub redirects; the callback
+ * the exact Opengeni github:manage grant across GitHub redirects; the callback
  * independently proves current GitHub personal/organization ownership. This
  * state must never be interpreted as GitHub installation authority.
  */

package/src/http/acting-person.ts

@@ -0,0 +1,105 @@
+import { organizationAccessPresetPermissions, 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, or who gave a
+   session admin access (see organization-mcp.ts). Routes that otherwise need
+   the person's browser cookie accept it, within the organization and the
+   access the person gave it. The person's live role is still checked by the
+   route, exactly as for the browser.
+
+   With the person's full access, the agent can do what the person can in that
+   organization, including approving agent sign-ins, managing connected agents
+   and giving sessions admin access. An agent with less can't do those, so it
+   can never widen its own access. Only Opengeni sign-in itself, sign-in
+   methods and recovery, and provider sign-in pages (Claude, integration
+   OAuth) stay in the browser. Device-code sign-in (Codex, SuperGrok) is
+   allowed: the agent relays the code and the person approves at the provider.
+   -------------------------------------------------------------------------- */
+
+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;
+}
+
+const FULL_ACCESS = organizationAccessPresetPermissions("full");
+
+/**
+ * True when this request is an agent with the person's full access: every
+ * permission, in every workspace. Session admin access always is; a connected
+ * agent is when the person chose full access for it.
+ */
+export function isAgentWithFullAccess(c: Context): boolean {
+  const proof = verifiedDelegatedHumanAuthorizationForRequest(c.req.raw);
+  return (
+    proof !== null &&
+    proof.workspaceScope.kind === "all" &&
+    FULL_ACCESS.every((permission) => proof.permissions.includes(permission))
+  );
+}
+
+/**
+ * Refuse an agent with less than the person's full access on a step that
+ * gives or approves access (agent sign-ins, connected agents, admin access),
+ * so it can never widen its own. The person and a full-access agent pass.
+ */
+export function requireFullAccessIfAgent(c: Context, what: string): void {
+  if (isAgentActingAsPerson(c) && !isAgentWithFullAccess(c)) {
+    throw new HTTPException(403, {
+      message: `${what} needs full access, and this agent's access is limited. The person can do it in the Opengeni app.`,
+    });
+  }
+}
+
+/** 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 step that only works in a browser: signing in at a provider's own page. */
+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,5 +1,17 @@
-import type { ErrorCode } from "@opengeni/contracts";
-import { WorkspaceControlBusyError } from "@opengeni/db";
+import {
+  AgentConfigError,
+  AllowanceExhaustedRefusal,
+  ModelUnavailableError,
+  ScheduledTaskTargetAccessChange,
+  type ErrorCode,
+} from "@opengeni/contracts";
+import {
+  isDatabaseConnectionLoss,
+  SessionUsageLimitUnavailableError,
+  nestedPostgresSqlState,
+  WorkspaceControlBusyError,
+} from "@opengeni/db";
+import { SessionUsageLimitHttpError, sessionUsageLimitRefusalFromError } from "@opengeni/core";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 import { HTTPException } from "hono/http-exception";
 
@@ -28,6 +40,99 @@ export class ApiHttpError extends HTTPException {
   }
 }
 
+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,
+  });
+}
+
+const SESSION_USAGE_LIMIT_ERROR_CODES: Record<SessionUsageLimitHttpError["code"], ErrorCode> = {
+  session_usage_limit_conflict: "conflict",
+  session_usage_limit_not_root: "conflict",
+  session_usage_limit_preparing: "conflict",
+  session_usage_limit_disabled: "validation_failed",
+  session_usage_limit_forbidden: "forbidden",
+  session_usage_limit_unavailable: "upstream_unavailable",
+  session_not_found: "not_found",
+};
+
+/**
+ * Per-task usage limits. A reached root limit is a non-retryable 402
+ * `session_usage_limit_reached` whose details carry only the public refusal
+ * fields; it is never `allowance_exhausted`, `payment_required` or a purchase
+ * prompt. Limit writes map to stable `details.code` values. Unreadable usage
+ * state is a retryable 503 that was not applied (never unlimited).
+ */
+export function sessionUsageLimitHttpError(error: unknown): ApiHttpError | null {
+  const refusal = sessionUsageLimitRefusalFromError(error);
+  if (refusal) {
+    return new ApiHttpError(402, {
+      code: "session_usage_limit_reached",
+      message: refusal.message,
+      retryable: false,
+      outcomeUnknown: false,
+      details: {
+        basis: refusal.basis,
+        rootSessionId: refusal.rootSessionId,
+        limitMicros: refusal.limitMicros,
+        usedMicros: refusal.usedMicros,
+      },
+    });
+  }
+  if (error instanceof SessionUsageLimitHttpError) {
+    return new ApiHttpError(error.status, {
+      code: SESSION_USAGE_LIMIT_ERROR_CODES[error.code],
+      message: error.message,
+      retryable: error.code === "session_usage_limit_unavailable",
+      outcomeUnknown: false,
+      details: { ...error.details, code: error.code },
+    });
+  }
+  const unavailable =
+    error instanceof SessionUsageLimitUnavailableError
+      ? error
+      : error instanceof HTTPException && error.cause instanceof SessionUsageLimitUnavailableError
+        ? error.cause
+        : null;
+  if (unavailable) {
+    return new ApiHttpError(503, {
+      code: "upstream_unavailable",
+      message: "Usage for this task is temporarily unavailable. Try again shortly.",
+      retryable: true,
+      outcomeUnknown: false,
+      details: { code: "session_usage_limit_unavailable" },
+    });
+  }
+  return null;
+}
+
 /**
  * A request-scoped session/workspace mutation could not enter the workspace
  * control prefix within its bounded wait. The transaction rolled back before
@@ -51,3 +156,106 @@ export function workspaceControlBusyHttpError(error: unknown): ApiHttpError | nu
     details: { code: busy.code, lockTimeoutMs: busy.lockTimeoutMs },
   });
 }
+
+/** `details.code` of the retryable 503 for a request whose database connection was lost. */
+export const DATABASE_UNAVAILABLE_ERROR_DETAIL_CODE = "DATABASE_UNAVAILABLE";
+
+/**
+ * The request's database connection went away (an operator drain, failover,
+ * restart, or socket loss) rather than the statement being rejected. That is a
+ * brief, retryable outage, not an internal error. A read is safe to repeat. A
+ * mutation's outcome is unknown: the connection may have dropped after COMMIT,
+ * or after an earlier transaction of the same request committed, so the client
+ * must reconcile by its own idempotency key before resending.
+ */
+export function databaseUnavailableHttpError(error: unknown, method: string): ApiHttpError | null {
+  if (error instanceof ApiHttpError) return null;
+  if (error instanceof HTTPException && error.status < 500) return null;
+  if (!isDatabaseConnectionLoss(error)) return null;
+  const safeMethod = method === "GET" || method === "HEAD" || method === "OPTIONS";
+  return new ApiHttpError(503, {
+    code: "upstream_unavailable",
+    message: "Opengeni is temporarily unavailable. Retry shortly.",
+    retryable: true,
+    outcomeUnknown: !safeMethod,
+    details: { code: DATABASE_UNAVAILABLE_ERROR_DETAIL_CODE },
+  });
+}
+
+/** `details.code` of the retryable 503 for a deadlock/serialization victim. */
+export const DATABASE_CONTENTION_ERROR_DETAIL_CODE = "DATABASE_CONTENTION";
+
+/**
+ * PostgreSQL aborted the request's transaction as a deadlock (40P01) or
+ * serialization (40001) victim after any in-process retry was exhausted. The
+ * aborted transaction committed nothing, so this is transient contention, not
+ * an internal error. A read is safe to repeat. For a mutation the default is
+ * `outcomeUnknown` because an earlier transaction of the same request may have
+ * committed; a route whose only write is the aborted idempotent transaction
+ * passes `outcomeUnknown: false`.
+ */
+export function databaseContentionHttpError(
+  error: unknown,
+  method: string,
+  options: { outcomeUnknown?: boolean } = {},
+): ApiHttpError | null {
+  if (error instanceof ApiHttpError) return null;
+  if (error instanceof HTTPException && error.status < 500) return null;
+  const sqlState = nestedPostgresSqlState(error);
+  if (sqlState !== "40P01" && sqlState !== "40001") return null;
+  const safeMethod = method === "GET" || method === "HEAD" || method === "OPTIONS";
+  return new ApiHttpError(503, {
+    code: "upstream_unavailable",
+    message: "Opengeni hit transient database contention. Retry shortly.",
+    retryable: true,
+    outcomeUnknown: options.outcomeUnknown ?? !safeMethod,
+    details: { code: DATABASE_CONTENTION_ERROR_DETAIL_CODE, sqlState },
+  });
+}
+
+/**
+ * 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,6 +1,10 @@
 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 { isDesktopDistributionPath } from "../routes/desktop-distribution";
 import { installExactPaths, isInstallRedirectPath } from "../routes/install";
 import {
   isMcpOAuthPublicProtocolPath,
@@ -9,6 +13,15 @@ import {
 } from "../mcp-oauth";
 
 const githubConnectPathPattern = /^\/v1\/workspaces\/[^/]+\/github\/connect$/;
+// The Connected Machine agent's own protocol. A machine never holds the
+// deployment key; each route authenticates its own enroll token, device code,
+// or signed install-key proof, and is rate limited by its route.
+const connectedMachineProtocolPaths = new Set([
+  "/v1/enrollments/token/exchange",
+  "/v1/enrollments/device/start",
+  "/v1/enrollments/device/poll",
+  "/v1/enrollments/renew",
+]);
 const githubInstallationLinkPathPattern = /^\/v1\/workspaces\/[^/]+\/github\/installations$/;
 const prReviewGithubBrowserPathPattern =
   /^\/v1\/workspaces\/[^/]+\/pr-review\/github\/(?:connect|installations\/select|installations\/[^/]+\/configure)$/;
@@ -18,7 +31,7 @@ export function requireAccessKey(settings: Settings): MiddlewareHandler {
     // §7.2 P1: requireAccessKey is the coarse NETWORK perimeter, not the
     // per-tenant identity gate (that is resolveAccessContext). When
     // `authRequired:false` it is a NO-OP — the embedded (Path 2) case where the
-    // host's own auth is the sole human gate and OpenGeni is mounted behind it.
+    // host's own auth is the sole human gate and Opengeni is mounted behind it.
     // Standalone/separate deployments set `authRequired:true` to keep this ON as
     // the shared-deployment-key perimeter.
     if (!settings.authRequired || isAuthExempt(c, settings)) {
@@ -37,6 +50,11 @@ 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;
@@ -47,6 +65,21 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (path === "/v1/config/client") {
     return true;
   }
+  // The Site gateway authenticates every site-runtime call with its own
+  // signature, which the routes verify before anything else.
+  if (path === "/v1/site-runtime" || path.startsWith("/v1/site-runtime/")) {
+    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;
   }
@@ -117,9 +150,18 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
     return true;
   }
   // The get.<domain> install-serving routes (install.sh/.ps1/uninstall.sh/
-  // minisign pub + the release-binary redirects). Reached by a fresh machine
-  // with no credentials; the bodies carry no secrets.
-  if (installExactPaths.has(path) || isInstallRedirectPath(path)) {
+  // minisign pub + the release-binary redirects) and the desktop app downloads.
+  // Reached by a fresh machine with no credentials; the bodies carry no secrets.
+  if (
+    installExactPaths.has(path) ||
+    isInstallRedirectPath(path) ||
+    isDesktopDistributionPath(path)
+  ) {
+    return true;
+  }
+  // Without this a key-protected deployment could never enroll or renew a
+  // machine. Human approval and lookup stay behind the key.
+  if (c.req.method === "POST" && connectedMachineProtocolPaths.has(path)) {
     return true;
   }
   if (
@@ -163,6 +205,28 @@ async function isAuthorized(c: Context, settings: Settings): Promise<boolean> {
   );
 }
 
+/**
+ * A request to a key-only (configured) deployment that presents the deployment
+ * key itself, from the operator rather than an agent acting for someone. The
+ * key travels in a request header that a page on another site can't add, so
+ * browser same-origin checks have nothing to protect on such a request.
+ */
+export function isConfiguredDeploymentKeyRequest(c: Context, settings: Settings): boolean {
+  const expected = settings.accessKey;
+  if (settings.productAccessMode !== "configured" || !settings.authRequired || !expected) {
+    return false;
+  }
+  if (verifiedDelegatedHumanAuthorizationForRequest(c.req.raw) !== null) return false;
+  const authorization = c.req.header("authorization");
+  const bearer = authorization?.startsWith("Bearer ")
+    ? authorization.slice("Bearer ".length)
+    : undefined;
+  return (
+    constantTimeEqual(c.req.header("x-opengeni-access-key"), expected) ||
+    constantTimeEqual(bearer, expected)
+  );
+}
+
 function constantTimeEqual(actual: string | undefined, expected: string): boolean {
   if (typeof actual !== "string") {
     return false;

package/src/http/cors.ts

@@ -26,13 +26,45 @@ export function validateInteractionRequestOrigin(
   ) {
     throw new HTTPException(400, { message: "invalid request origin" });
   }
-  if (
-    allowedCorsOrigin(input.corsAllowOriginRegex, url.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 === url.origin : false,
+      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 url.origin;
+    return false;
   }
-  throw new HTTPException(403, { message: "request origin is not allowed" });
+  return isConfiguredBrowserOrigin(url.origin, input);
 }