@opengeni/api-router 3.0.1 → 3.1.2

package/src/site-publishing/limits.ts

@@ -0,0 +1,315 @@
+import {
+  DEFAULT_SITE_LIMITS,
+  SiteLimits,
+  UNLIMITED_SITE_FLOOD_BRAKES,
+  type SiteLimitProfile,
+  type SiteLimitProfileKind,
+  type SiteLimits as SiteLimitsValue,
+} from "@opengeni/contracts";
+import type { Settings } from "@opengeni/config";
+import type { StoredSiteLimitProfile } from "@opengeni/db";
+
+/**
+ * Limit profiles for published Sites. Opengeni enforces these values (the
+ * edge only brakes floods). Limits follow who the viewer is, not the Site's
+ * access mode:
+ *
+ * - Workspace members are never limited by Site limits, on any Site: they
+ *   use the workspace's normal session limits and billing. Only the request
+ *   flood brake applies.
+ * - Everyone outside the workspace (invited people and public visitors,
+ *   signed in or anonymous) shares ONE Site limit (per month by default, or
+ *   per day), and an optional per-person limit (off by default).
+ * - Anonymous guests also meet internal bot guards (conversation and message
+ *   counts and a per-conversation cap), configured in settings and not shown
+ *   to Site owners.
+ *
+ * The profile in force is the Site's own, else the workspace default, else
+ * `standard`. Every profile keeps the flood brakes, and deployment switches
+ * (public agents) apply last.
+ */
+
+export type SiteLimitSettings = Pick<
+  Settings,
+  | "sitesFreeRequestsPerMinutePerVisitor"
+  | "sitesFreeGuestWritesPerMinute"
+  | "sitesFreeConversationsPerVisitorPerDay"
+  | "sitesFreeConversationsPerSitePerDay"
+  | "sitesFreeTurnsPerConversation"
+  | "sitesFreeAgentMicrosPerConversation"
+  | "sitesFreeAgentMicrosPerVisitorPerDay"
+  | "sitesFreeAgentMicrosPerSitePerMonth"
+  | "sitesAgentMicrosPerSitePerMonth"
+  | "sitesAgentMicrosPerPersonPerDay"
+  | "sitesGuestConversationsPerVisitorPerDay"
+  | "sitesGuestConversationsPerSitePerDay"
+  | "sitesGuestTurnsPerConversation"
+  | "sitesGuestAgentMicrosPerConversation"
+  | "sitesCreditsLimitMultiplier"
+  | "sitesPublicAgentsEnabled"
+>;
+
+/** The stored kind as the API reports it: the legacy `free` is `standard`. */
+export function normalizedSiteLimitProfileKind(kind: SiteLimitProfileKind): SiteLimitProfileKind {
+  return kind === "free" ? "standard" : kind;
+}
+
+/** The standard limits from settings (the new setting, the deprecated one, the built-in default). */
+export function standardSiteLimits(settings: SiteLimitSettings): SiteLimitsValue {
+  const pick = (...values: (number | null | undefined)[]) =>
+    values.find((value) => value !== undefined && value !== null) ?? null;
+  const fallback = DEFAULT_SITE_LIMITS;
+  return {
+    ...fallback,
+    requestsPerMinutePerVisitor: settings.sitesFreeRequestsPerMinutePerVisitor,
+    guestWritesPerMinute: settings.sitesFreeGuestWritesPerMinute,
+    conversationsPerVisitorPerDay: pick(
+      settings.sitesGuestConversationsPerVisitorPerDay,
+      settings.sitesFreeConversationsPerVisitorPerDay,
+      fallback.conversationsPerVisitorPerDay,
+    ),
+    conversationsPerSitePerDay: pick(
+      settings.sitesGuestConversationsPerSitePerDay,
+      settings.sitesFreeConversationsPerSitePerDay,
+      fallback.conversationsPerSitePerDay,
+    ),
+    turnsPerConversation: pick(
+      settings.sitesGuestTurnsPerConversation,
+      settings.sitesFreeTurnsPerConversation,
+      fallback.turnsPerConversation,
+    ),
+    agentMicrosPerConversation: pick(
+      settings.sitesGuestAgentMicrosPerConversation,
+      settings.sitesFreeAgentMicrosPerConversation,
+      fallback.agentMicrosPerConversation,
+    ),
+    agentMicrosPerVisitorPerDay: pick(
+      settings.sitesAgentMicrosPerPersonPerDay,
+      settings.sitesFreeAgentMicrosPerVisitorPerDay,
+      fallback.agentMicrosPerVisitorPerDay,
+    ),
+    agentMicrosPerSitePerMonth: pick(
+      settings.sitesAgentMicrosPerSitePerMonth,
+      settings.sitesFreeAgentMicrosPerSitePerMonth,
+      fallback.agentMicrosPerSitePerMonth,
+    ),
+  };
+}
+
+/** @deprecated The former free profile: the standard limits. */
+export function freeSiteLimits(settings: SiteLimitSettings): SiteLimitsValue {
+  return standardSiteLimits(settings);
+}
+
+const times = (value: number | null, factor: number) => (value === null ? null : value * factor);
+
+/** A cap that never exceeds `brake` (null, no cap, becomes the brake). */
+const braked = (value: number | null, brake: number) =>
+  value === null ? brake : Math.min(value, brake);
+
+/**
+ * The previous release's free defaults. Its custom form always saved the six
+ * LEGACY_CUSTOM_FORM_FIELDS, prefilled with these, so in a profile of that
+ * shape a field with exactly this value means "the default" and takes the
+ * new standard value instead. Migration 0791 deliberately leaves stored rows
+ * intact for old readers. New writes mark explicit overrides with version 2;
+ * unmarked old-pod writes keep normalizing throughout the rolling deploy.
+ */
+export const LEGACY_FREE_SITE_LIMIT_DEFAULTS: Readonly<Record<string, unknown>> = Object.freeze({
+  requestsPerMinutePerVisitor: 120,
+  guestWritesPerMinute: 30,
+  agentsEnabled: true,
+  guestAgentsEnabled: true,
+  conversationsPerVisitorPerDay: 10,
+  conversationsPerSitePerDay: 50,
+  turnsPerConversation: 20,
+  agentMicrosPerConversation: 20_000,
+  agentMicrosPerVisitorPerDay: 200_000,
+  agentMicrosPerSitePerMonth: 2_000_000,
+  agentModels: null,
+});
+
+/** The fields the previous release's custom form always saved. */
+export const LEGACY_CUSTOM_FORM_FIELDS = Object.freeze([
+  "conversationsPerVisitorPerDay",
+  "conversationsPerSitePerDay",
+  "turnsPerConversation",
+  "agentMicrosPerConversation",
+  "agentMicrosPerVisitorPerDay",
+  "agentMicrosPerSitePerMonth",
+] as const);
+
+/** Parse stored overrides leniently: unknown or invalid fields are ignored. */
+export function siteLimitOverrides(
+  stored: Record<string, unknown> | null | undefined,
+): Partial<SiteLimitsValue> {
+  if (!stored) return {};
+  const legacyForm = stored.__siteLimitsVersion !== 2;
+  const overrides = legacyForm
+    ? Object.fromEntries(
+        Object.entries(stored).filter(
+          ([key, value]) =>
+            !(key in LEGACY_FREE_SITE_LIMIT_DEFAULTS) ||
+            LEGACY_FREE_SITE_LIMIT_DEFAULTS[key] !== value,
+        ),
+      )
+    : stored;
+  const parsed = SiteLimits.partial().safeParse(overrides);
+  if (parsed.success) return parsed.data as Partial<SiteLimitsValue>;
+  const kept: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(overrides)) {
+    const one = SiteLimits.partial().safeParse({ [key]: value });
+    if (one.success) Object.assign(kept, one.data);
+  }
+  return kept as Partial<SiteLimitsValue>;
+}
+
+/** The limits one profile gives people outside the workspace, before deployment switches. */
+export function siteLimitsForProfile(
+  settings: SiteLimitSettings,
+  profile: StoredSiteLimitProfile | SiteLimitProfile,
+): SiteLimitsValue {
+  const standard = standardSiteLimits(settings);
+  // Overrides adjust any kind's limits; custom is the standard limits plus them.
+  const overrides = siteLimitOverrides(
+    profile.kind === "custom" ||
+      (profile.overrides as Record<string, unknown> | null)?.__siteLimitsVersion === 2
+      ? profile.overrides
+      : null,
+  );
+  let limits: SiteLimitsValue;
+  switch (profile.kind) {
+    case "standard":
+    case "free":
+      limits = standard;
+      break;
+    case "credits": {
+      const factor = settings.sitesCreditsLimitMultiplier;
+      limits = {
+        ...standard,
+        conversationsPerVisitorPerDay: times(standard.conversationsPerVisitorPerDay, factor),
+        conversationsPerSitePerDay: times(standard.conversationsPerSitePerDay, factor),
+        agentMicrosPerConversation: times(standard.agentMicrosPerConversation, factor),
+        agentMicrosPerVisitorPerDay: times(standard.agentMicrosPerVisitorPerDay, factor),
+        agentMicrosPerVisitorPerMonth: times(standard.agentMicrosPerVisitorPerMonth, factor),
+        agentMicrosPerSitePerDay: times(standard.agentMicrosPerSitePerDay, factor),
+        agentMicrosPerSitePerMonth: times(standard.agentMicrosPerSitePerMonth, factor),
+      };
+      break;
+    }
+    case "unlimited":
+      limits = {
+        ...standard,
+        conversationsPerVisitorPerDay: null,
+        conversationsPerSitePerDay: UNLIMITED_SITE_FLOOD_BRAKES.conversationsPerSitePerDay,
+        turnsPerConversation: null,
+        agentMicrosPerVisitorPerDay: null,
+        agentMicrosPerVisitorPerMonth: null,
+        agentMicrosPerSitePerDay: null,
+        agentMicrosPerSitePerMonth: null,
+        requestsPerMinutePerVisitor: UNLIMITED_SITE_FLOOD_BRAKES.requestsPerMinutePerVisitor,
+        agentMicrosPerConversation: UNLIMITED_SITE_FLOOD_BRAKES.agentMicrosPerConversation,
+      };
+      break;
+    case "custom":
+      limits = standard;
+      break;
+  }
+  limits = { ...limits, ...overrides };
+  // Flood brakes hold under every profile.
+  return {
+    ...limits,
+    requestsPerMinutePerVisitor: braked(
+      limits.requestsPerMinutePerVisitor,
+      UNLIMITED_SITE_FLOOD_BRAKES.requestsPerMinutePerVisitor,
+    ),
+    conversationsPerSitePerDay: braked(
+      limits.conversationsPerSitePerDay,
+      UNLIMITED_SITE_FLOOD_BRAKES.conversationsPerSitePerDay,
+    ),
+    agentMicrosPerConversation: braked(
+      limits.agentMicrosPerConversation,
+      UNLIMITED_SITE_FLOOD_BRAKES.agentMicrosPerConversation,
+    ),
+  };
+}
+
+/** The profile in force: the Site's own, else the workspace default, else standard. */
+export function sourceSiteLimitProfile(
+  siteProfile: StoredSiteLimitProfile | null,
+  workspaceProfile: StoredSiteLimitProfile | null,
+): SiteLimitProfile {
+  const profile = siteProfile ?? workspaceProfile ?? { kind: "standard", overrides: null };
+  return {
+    kind: normalizedSiteLimitProfileKind(profile.kind),
+    overrides:
+      profile.kind === "custom" || profile.overrides?.__siteLimitsVersion === 2
+        ? siteLimitOverrides(profile.overrides)
+        : null,
+  };
+}
+
+/**
+ * The Site's limits (for people outside the workspace) under the profile in
+ * force, deployment switches applied. Viewer-specific limits: siteViewerLimits.
+ */
+export function effectiveSiteLimits(
+  settings: SiteLimitSettings,
+  siteProfile: StoredSiteLimitProfile | null,
+  workspaceProfile: StoredSiteLimitProfile | null,
+): SiteLimitsValue {
+  const limits = siteLimitsForProfile(
+    settings,
+    siteProfile ?? workspaceProfile ?? { kind: "standard", overrides: null },
+  );
+  return {
+    ...limits,
+    guestAgentsEnabled:
+      limits.agentsEnabled && limits.guestAgentsEnabled && settings.sitesPublicAgentsEnabled,
+  };
+}
+
+export type SiteViewerLimitKind = "member" | "invited" | "user" | "guest";
+
+/**
+ * The limits that govern one viewer:
+ * - members: no Site limits at all (agents on, nothing capped), only the
+ *   request flood brake;
+ * - signed-in people outside the workspace: the Site limit and the optional
+ *   per-person limit, with the flood brakes as their only guards;
+ * - anonymous guests: all of the Site's limits, bot guards included.
+ */
+export function siteViewerLimits(
+  limits: SiteLimitsValue,
+  viewerKind: SiteViewerLimitKind,
+): SiteLimitsValue {
+  if (viewerKind === "member")
+    return {
+      ...limits,
+      agentsEnabled: true,
+      guestAgentsEnabled: true,
+      conversationsPerVisitorPerDay: null,
+      conversationsPerSitePerDay: null,
+      turnsPerConversation: null,
+      agentMicrosPerConversation: null,
+      agentMicrosPerVisitorPerDay: null,
+      agentMicrosPerVisitorPerMonth: null,
+      agentMicrosPerSitePerDay: null,
+      agentMicrosPerSitePerMonth: null,
+    };
+  if (viewerKind === "guest") return limits;
+  return {
+    ...limits,
+    conversationsPerVisitorPerDay: null,
+    turnsPerConversation: null,
+    conversationsPerSitePerDay: UNLIMITED_SITE_FLOOD_BRAKES.conversationsPerSitePerDay,
+    agentMicrosPerConversation: UNLIMITED_SITE_FLOOD_BRAKES.agentMicrosPerConversation,
+  };
+}
+
+/** The stored form of a requested profile kind: `free` is stored as `standard`. */
+export function storedSiteLimitProfileKind(
+  kind: SiteLimitProfileKind,
+): StoredSiteLimitProfile["kind"] {
+  return normalizedSiteLimitProfileKind(kind);
+}

package/src/site-publishing/page-tool-authority.ts

@@ -0,0 +1,111 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import { hasPermission, type ApiRouteDeps, type SiteSessionOrigin } from "@opengeni/core";
+import {
+  getPublishedSiteVersion,
+  getWorkspaceGrant,
+  subjectHasLiveWorkspaceAuthorityInScope,
+  withWorkspaceSubjectRls,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+import type { WorkspaceSiteVersionResolver } from "../workspace-tool-gateway";
+import type { SiteGatewayFields } from "./gateway-signature";
+import {
+  requireServedSiteRuntimeHost,
+  resolveSiteRuntimeViewer,
+  siteNotAvailableForViewer,
+} from "./runtime";
+
+/** A Site cookie is NOT a console session or a general access authorization. */
+export type PublishedSiteToolAuthorization = {
+  readonly kind: "published_site_tools";
+  readonly grant: AccessGrant;
+};
+
+type Authority = {
+  requestedTools: Array<{ serverId: string; toolName: string }>;
+  origin: SiteSessionOrigin & { siteId: string; versionId: string };
+  reauthorize: () => Promise<void>;
+  readVersion: WorkspaceSiteVersionResolver;
+};
+const authorities = new WeakMap<PublishedSiteToolAuthorization, Authority>();
+
+export function isPublishedSiteToolAuthorization(
+  value: object,
+): value is PublishedSiteToolAuthorization {
+  return authorities.has(value as PublishedSiteToolAuthorization);
+}
+
+export function publishedSiteToolAuthority(value: PublishedSiteToolAuthorization): Authority {
+  const authority = authorities.get(value);
+  if (!authority) throw new HTTPException(403, { message: "site_tool_not_authorized" });
+  return authority;
+}
+
+/**
+ * Called only after gateway signature verification. Authenticate the opaque
+ * Site cookie against this served host; never accept a subject or grant from
+ * the page. The resulting capability is usable only by the tool gateway.
+ */
+export async function authorizePublishedSiteTools(
+  deps: ApiRouteDeps,
+  domain: string,
+  fields: SiteGatewayFields,
+): Promise<PublishedSiteToolAuthorization> {
+  const denied = () =>
+    siteNotAvailableForViewer("workspace_tools", "Workspace tools require workspace membership");
+  const read = async () => {
+    const host = await requireServedSiteRuntimeHost(deps, domain, fields.host);
+    const viewer = await resolveSiteRuntimeViewer(deps, host, fields);
+    if (viewer.kind !== "member" || !viewer.subjectId || !viewer.sessionId) throw denied();
+    const scope = { ...host.scope, subjectId: viewer.subjectId };
+    const grant = await withWorkspaceSubjectRls(
+      deps.db,
+      scope.workspaceId,
+      scope.subjectId,
+      async (tx) => {
+        // Membership is necessary but not sufficient while its organization is suspended.
+        if (!(await subjectHasLiveWorkspaceAuthorityInScope(tx, scope))) throw denied();
+        return await getWorkspaceGrant(tx, scope.subjectId, scope.workspaceId, {
+          principalKind: "human_session",
+        });
+      },
+    );
+    if (!grant || !hasPermission(grant.permissions, "workspace:read")) throw denied();
+    return { host, viewer, grant };
+  };
+  const initial = await read();
+  const { host, grant } = initial;
+  const version = await getPublishedSiteVersion(deps.db, host.scope, host.site.id, host.versionId);
+  if (!version) throw new HTTPException(403, { message: "site_tool_not_authorized" });
+  const reauthorize = async () => {
+    const live = await read();
+    if (
+      live.host.site.id !== host.site.id ||
+      live.host.versionId !== version.id ||
+      live.grant.accountId !== grant.accountId ||
+      live.grant.workspaceId !== grant.workspaceId ||
+      live.grant.subjectId !== grant.subjectId ||
+      live.viewer.sessionId !== initial.viewer.sessionId ||
+      grant.permissions.some((permission) => !hasPermission(live.grant.permissions, permission))
+    )
+      throw new HTTPException(403, { message: "site_tool_access_changed" });
+  };
+  Object.freeze(grant.permissions);
+  Object.freeze(grant);
+  const authorization: PublishedSiteToolAuthorization = Object.freeze({
+    kind: "published_site_tools",
+    grant,
+  });
+  authorities.set(authorization, {
+    requestedTools: version.requestedTools,
+    origin: { siteId: host.site.id, versionId: version.id, title: host.site.title },
+    reauthorize,
+    readVersion: async (_db, caller, siteId, versionId) => {
+      if (caller !== grant || siteId !== host.site.id || versionId !== version.id)
+        throw new HTTPException(403, { message: "site_tool_not_authorized" });
+      await reauthorize();
+      return { status: "active", version };
+    },
+  });
+  return authorization;
+}