@opengeni/api-router 3.0.1 → 3.1.2

package/dist/site-publishing/gateway-signature.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Verification of gateway-signed site-runtime requests. The gateway HMACs
+ * `siteGatewayCanonicalString` with the shared secret; the API accepts the
+ * current or the previous secret (rotation), within 30 s of its clock. The
+ * signed body hash travels in its own header, so the signature is checked
+ * from the headers alone, before the body is read; the route then hashes the
+ * body as it reads it and refuses a body that does not match. Nothing else
+ * about the request is trusted before this passes.
+ */
+export type SiteGatewayFields = {
+    host: string;
+    session: string;
+    visitor: string;
+    clientIp: string;
+    human: boolean;
+};
+export type SiteGatewayVerification = {
+    ok: true;
+    fields: SiteGatewayFields;
+    /** The signed hex SHA-256 the body read afterwards must match. */
+    bodySha256: string;
+} | {
+    ok: false;
+    reason: "not_configured" | "missing_headers" | "bad_timestamp" | "skew" | "bad_body_hash" | "bad_signature" | "body_mismatch" | "credentials";
+};
+/** Request headers that carry Opengeni app credentials; site-runtime refuses them. */
+export declare const SITE_RUNTIME_REFUSED_HEADERS: readonly string[];
+export declare function sha256Hex(bytes: Uint8Array): string;
+export declare function siteGatewaySignature(secret: string, canonical: string): string;
+/**
+ * Verify a signed request from its headers alone; the body is not needed.
+ * On success the caller reads the body (capped) and checks it against
+ * `bodySha256` with `sameSha256Hex`, refusing a mismatch as `body_mismatch`.
+ */
+export declare function verifySiteGatewayRequest(input: {
+    method: string;
+    pathWithQuery: string;
+    headers: Headers;
+    secrets: readonly (string | undefined)[];
+    nowMs?: number;
+}): SiteGatewayVerification;
+/** Whether two hex digests are equal, compared in constant time. */
+export declare function sameSha256Hex(actual: string, signed: string): boolean;
+/** Sign a request as the gateway does (tests and local tools). */
+export declare function signSiteGatewayRequest(input: {
+    secret: string;
+    method: string;
+    pathWithQuery: string;
+    host: string;
+    body?: Uint8Array | string;
+    session?: string;
+    visitor?: string;
+    clientIp?: string;
+    human?: boolean;
+    nowMs?: number;
+}): Record<string, string>;

package/dist/site-publishing/limits.d.ts

@@ -0,0 +1,63 @@
+import { 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 declare function normalizedSiteLimitProfileKind(kind: SiteLimitProfileKind): SiteLimitProfileKind;
+/** The standard limits from settings (the new setting, the deprecated one, the built-in default). */
+export declare function standardSiteLimits(settings: SiteLimitSettings): SiteLimitsValue;
+/** @deprecated The former free profile: the standard limits. */
+export declare function freeSiteLimits(settings: SiteLimitSettings): SiteLimitsValue;
+/**
+ * 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 declare const LEGACY_FREE_SITE_LIMIT_DEFAULTS: Readonly<Record<string, unknown>>;
+/** The fields the previous release's custom form always saved. */
+export declare const LEGACY_CUSTOM_FORM_FIELDS: readonly ["conversationsPerVisitorPerDay", "conversationsPerSitePerDay", "turnsPerConversation", "agentMicrosPerConversation", "agentMicrosPerVisitorPerDay", "agentMicrosPerSitePerMonth"];
+/** Parse stored overrides leniently: unknown or invalid fields are ignored. */
+export declare function siteLimitOverrides(stored: Record<string, unknown> | null | undefined): Partial<SiteLimitsValue>;
+/** The limits one profile gives people outside the workspace, before deployment switches. */
+export declare function siteLimitsForProfile(settings: SiteLimitSettings, profile: StoredSiteLimitProfile | SiteLimitProfile): SiteLimitsValue;
+/** The profile in force: the Site's own, else the workspace default, else standard. */
+export declare function sourceSiteLimitProfile(siteProfile: StoredSiteLimitProfile | null, workspaceProfile: StoredSiteLimitProfile | null): SiteLimitProfile;
+/**
+ * The Site's limits (for people outside the workspace) under the profile in
+ * force, deployment switches applied. Viewer-specific limits: siteViewerLimits.
+ */
+export declare function effectiveSiteLimits(settings: SiteLimitSettings, siteProfile: StoredSiteLimitProfile | null, workspaceProfile: StoredSiteLimitProfile | null): SiteLimitsValue;
+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 declare function siteViewerLimits(limits: SiteLimitsValue, viewerKind: SiteViewerLimitKind): SiteLimitsValue;
+/** The stored form of a requested profile kind: `free` is stored as `standard`. */
+export declare function storedSiteLimitProfileKind(kind: SiteLimitProfileKind): StoredSiteLimitProfile["kind"];

package/dist/site-publishing/page-tool-authority.d.ts

@@ -0,0 +1,30 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import { type ApiRouteDeps, type SiteSessionOrigin } from "@opengeni/core";
+import type { WorkspaceSiteVersionResolver } from "../workspace-tool-gateway.js";
+import type { SiteGatewayFields } from "./gateway-signature.js";
+/** 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;
+};
+export declare function isPublishedSiteToolAuthorization(value: object): value is PublishedSiteToolAuthorization;
+export declare function publishedSiteToolAuthority(value: PublishedSiteToolAuthorization): 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 declare function authorizePublishedSiteTools(deps: ApiRouteDeps, domain: string, fields: SiteGatewayFields): Promise<PublishedSiteToolAuthorization>;
+export {};

package/dist/site-publishing/platform-usage.d.ts

@@ -0,0 +1,113 @@
+import { type SitePlatformMeter, type SitePlatformUsage } from "@opengeni/contracts";
+import type { Settings } from "@opengeni/config";
+import { type Database, type SitePlatformBrakeRecord, type SitePlatformScope, type SitePlatformUsageRecord } from "@opengeni/db";
+import { ApiHttpError } from "../http/api-error.js";
+/**
+ * Site platform usage: what published Sites cost the platform apart from
+ * model spend (gateway requests, Site SQL rows read and written, Site SQL
+ * plus Site Data storage). Every mode meters it per workspace and month.
+ *
+ * - usage_only (default): recorded only.
+ * - shadow: what credits mode would charge is recorded (shadow_micros).
+ * - credits: usage above the workspace's monthly allowance is charged from
+ *   organization credits; a workspace past an allowance with no credits (or
+ *   with overage off) is refused further Site SQL and Site Data use (402).
+ *
+ * Separately, one Opengeni-wide monthly limit brakes every workspace: when
+ * the estimated cost of all metered usage this month reaches
+ * OPENGENI_SITES_PLATFORM_MONTHLY_LIMIT_USD the brake engages and refuses
+ * new Site SQL writes, new publishes and guest agent turns (503,
+ * details.code site_platform_brake_engaged). Published pages keep serving.
+ */
+export type SitePlatformSettings = Pick<Settings, "sitesPlatformBillingMode" | "sitesPlatformOverageEnabled" | "sitesPlatformAllowanceRequests" | "sitesPlatformAllowanceSqlRowsRead" | "sitesPlatformAllowanceSqlRowsWritten" | "sitesPlatformAllowanceStorageBytes" | "sitesPlatformPriceMicrosPerMillionRequests" | "sitesPlatformPriceMicrosPerMillionSqlRowsRead" | "sitesPlatformPriceMicrosPerMillionSqlRowsWritten" | "sitesPlatformPriceMicrosPerGbMonth" | "sitesPlatformMonthlyLimitUsd" | "sitesPlatformAlertPercent">;
+export type SitePlatformDeps = {
+    db: Database;
+    settings: SitePlatformSettings;
+};
+type MeterRule = {
+    meter: SitePlatformMeter;
+    allowance: number;
+    priceMicros: number;
+    priceUnit: number;
+};
+/** GB-month unit of storage prices (decimal gigabytes, as Cloudflare bills). */
+export declare const SITE_PLATFORM_GB = 1000000000;
+export declare function sitePlatformMeterRules(settings: SitePlatformSettings): MeterRule[];
+type UsageAmounts = {
+    requests: number;
+    sqlRowsRead: number;
+    sqlRowsWritten: number;
+    storageBytes: number;
+    storagePeakBytes?: number;
+};
+/**
+ * Estimated cost of usage, micro-USD, before allowances. Storage is priced
+ * at its level (peak for a workspace) as if held the whole month: an upper
+ * bound, so the brake errs early rather than late.
+ */
+export declare function sitePlatformEstimateMicros(settings: SitePlatformSettings, usage: UsageAmounts): number;
+/** What credits mode charges this month: usage above each allowance, at its price. */
+export declare function sitePlatformBillableMicros(settings: SitePlatformSettings, usage: UsageAmounts): number;
+export declare function sitePlatformUsageView(settings: SitePlatformSettings, workspaceId: string, usage: SitePlatformUsageRecord, brake: SitePlatformBrakeRecord): SitePlatformUsage;
+export declare function readSitePlatformUsageView(deps: SitePlatformDeps, scope: SitePlatformScope): Promise<SitePlatformUsage>;
+/** Charges smaller than this wait for more usage (one debit per cent at most). */
+export declare const SITE_PLATFORM_MIN_CHARGE_MICROS = 10000;
+/**
+ * After usage was recorded: in shadow mode record what credits would charge;
+ * in credits mode charge the new billable amount from organization credits
+ * (claim and debit in one transaction). Best effort: a failure is logged and
+ * the next metered call retries it.
+ */
+export declare function settleSitePlatformCharges(deps: SitePlatformDeps, scope: SitePlatformScope, usage: SitePlatformUsageRecord): Promise<void>;
+/**
+ * Credits mode only: refuse (402, details.code site_platform_quota_exhausted)
+ * when a meter the call uses is at or past its allowance and the workspace
+ * cannot pay for more (overage off, or no spendable credits).
+ */
+export declare function requireSitePlatformQuota(deps: SitePlatformDeps, scope: SitePlatformScope, meters: readonly SitePlatformMeter[]): Promise<void>;
+/** The monthly limit in micro-USD, or null when the automatic brake is off (limit 0). */
+export declare function sitePlatformLimitMicros(settings: SitePlatformSettings): number | null;
+/** How long a process trusts a brake read. */
+export declare const SITE_PLATFORM_BRAKE_CACHE_MS = 15000;
+/** How often a process re-evaluates the Opengeni-wide estimate after metering. */
+export declare const SITE_PLATFORM_EVALUATE_INTERVAL_MS = 30000;
+/** Forget cached brake state and the evaluation throttle (tests). */
+export declare function resetSitePlatformBrakeCache(): void;
+export type SitePlatformBrakedAction = "sql_write" | "publish" | "guest_agent";
+/** The 503 a braked action gets. */
+export declare function sitePlatformBrakeError(action: SitePlatformBrakedAction): ApiHttpError;
+/**
+ * Run a brake check for a first-party agent tool: null when it passes, else
+ * the refusal as a tool result (details.code site_platform_brake_engaged).
+ */
+export declare function sitePlatformBrakeToolRefusal(check: () => Promise<void>): Promise<{
+    isError: true;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+} | null>;
+/** Whether the Opengeni-wide brake is engaged (cached per process for 15 seconds). */
+export declare function sitePlatformBrakeEngaged(deps: SitePlatformDeps): Promise<boolean>;
+/** Refuse a braked action while the brake is engaged. A failed read never refuses. */
+export declare function requireSitePlatformOpen(deps: SitePlatformDeps, action: SitePlatformBrakedAction): Promise<void>;
+/**
+ * Re-evaluate the Opengeni-wide estimate: the month's totals of every
+ * workspace and the current storage level, at the configured prices. At the
+ * alert threshold operators are alerted once a month (a structured log line,
+ * `site_platform_limit_alert`; Opengeni has no operator mailer); at the limit
+ * the brake engages (`site_platform_brake_engaged`) unless an operator lifted
+ * it this month.
+ */
+export declare function evaluateSitePlatformLimit(deps: SitePlatformDeps, now?: Date): Promise<{
+    estimateMicros: number;
+    limitMicros: number | null;
+    brake: SitePlatformBrakeRecord;
+}>;
+/**
+ * After usage was metered: charge it (shadow and credits modes) and, at most
+ * every 30 seconds per process, re-evaluate the Opengeni-wide limit in the
+ * background (the request does not wait for it). Never throws.
+ */
+export declare function afterSitePlatformUsage(deps: SitePlatformDeps, scope: SitePlatformScope, usage: SitePlatformUsageRecord): Promise<void>;
+export {};

package/dist/site-publishing/platform.d.ts

@@ -0,0 +1,21 @@
+import { type SitePublicationRecord } from "@opengeni/db";
+import { type SitePublishingDeps } from "./service.js";
+/**
+ * Platform moderation: the deployment operator takes a published Site down
+ * (or restores one it took down) by hostname or Site id, across workspaces.
+ * There is no platform-admin API in Opengeni, so this runs from the operator
+ * script (`scripts/operator/site-takedown.ts`) with the migrations
+ * credential. Owners and workspace admins cannot lift a platform takedown,
+ * and its hostname stays held for the platform even if the Site or its
+ * workspace is deleted (`liftSiteHostnameHold` releases it). Viewer sessions
+ * are revoked at once; running conversations are refused further work by
+ * site-runtime and end on their own usage caps (the script has no
+ * in-process session dispatch to cancel them).
+ */
+export declare function moderateSiteAsPlatform(deps: SitePublishingDeps, input: {
+    /** A label, a full hostname, or a Site id. */
+    host: string;
+    operator: string;
+    action: "takedown" | "restore";
+    reason?: string | undefined;
+}): Promise<SitePublicationRecord>;

package/dist/site-publishing/readiness.d.ts

@@ -0,0 +1,62 @@
+import type { AccessGrant, SitePublishWarningFix, SiteAccessMode, SiteDataAccessMode, SiteDataGuestAccess, SitePublishWarning, SiteSqlQueryAudience } from "@opengeni/contracts";
+import { type SitePublicationRecord, type SitePublishingScope } from "@opengeni/db";
+import type { ApiRouteDeps } from "@opengeni/core";
+import { type SiteOutsideModelChoice } from "./agent-model.js";
+/** The most HTML read for the check. */
+export declare const SITE_READINESS_MAX_HTML_BYTES: number;
+export type SitePageUsage = {
+    /** Collections the page names, and how it writes them. */
+    collections: Map<string, {
+        writes: boolean;
+        changes: boolean;
+    }>;
+    queries: Set<string>;
+    workspaceTools: boolean;
+};
+/** What a page's source uses (see the heuristics above). */
+export declare function scanSitePageUsage(source: string): SitePageUsage;
+export type SiteReadinessInput = {
+    access: SiteAccessMode;
+    /** Anonymous visitors are admitted (public, and not a login-only deployment). */
+    guestsAllowed: boolean;
+    page: SitePageUsage | null;
+    /** The page was too large to read (SITE_READINESS_MAX_HTML_BYTES). */
+    pageTooLarge?: boolean;
+    requestedTools: number;
+    agent: {
+        enabled: boolean;
+        tools: readonly string[] | null;
+    };
+    collections: ReadonlyArray<{
+        name: string;
+        accessMode: SiteDataAccessMode;
+        guestAccess: SiteDataGuestAccess;
+    }>;
+    queries: ReadonlyArray<{
+        name: string;
+        audience: SiteSqlQueryAudience;
+    }>;
+    outsideModel: SiteOutsideModelChoice | null;
+};
+/** The warnings for a members-only Site are none: members may do everything the page does. */
+export declare function siteReadinessWarnings(input: SiteReadinessInput): SitePublishWarning[];
+export type SiteReadiness = {
+    warnings: SitePublishWarning[];
+    /** The model people outside the workspace use instead of a subscription model. */
+    outsideAgentModel: string | null;
+};
+/**
+ * The readiness of a publication's current version. Any read that fails
+ * (no storage, a missing version) leaves that part out rather than failing
+ * the publication view.
+ */
+export declare function readSitePublicationReadiness(deps: Pick<ApiRouteDeps, "db" | "settings" | "objectStorage">, scope: SitePublishingScope, publication: Pick<SitePublicationRecord, "siteId" | "access" | "agent">): Promise<SiteReadiness>;
+/**
+ * Apply a readiness warning's safe fix through the ordinary definition
+ * paths (the same checks as defining the collection or query by hand): a
+ * collection's guest access, or a named query's audience. Everything else
+ * about the collection or query stays as it is.
+ */
+export declare function applySitePublishWarningFix(deps: ApiRouteDeps, grant: AccessGrant, scope: SitePublishingScope, siteId: string, fix: SitePublishWarningFix): Promise<void>;
+export declare class SiteFixTargetMissing extends Error {
+}

package/dist/site-publishing/runtime.d.ts

@@ -0,0 +1,179 @@
+import { type Permission, type SiteLimitProfileKind, type SiteLimits, type SiteViewerCapabilities } from "@opengeni/contracts";
+import { type ApiRouteDeps } from "@opengeni/core";
+import { type PublishedSiteRecord, type SitePublicationRecord, type SitePublishingScope, type SiteRuntimeBudget, type SiteRuntimeBudgetLimits, type SiteRuntimeConversationRecord, type SiteRuntimeRateBucket, type SiteRuntimeReservation } from "@opengeni/db";
+import type { SiteGatewayFields } from "./gateway-signature.js";
+import { SITE_RUNTIME_AGENT_PERMISSIONS } from "./service.js";
+import { type SiteRuntimeViewer } from "./viewer.js";
+/**
+ * Site-runtime: the narrow API a Site gateway calls for one published Site
+ * host, after the gateway signature passed. Everything here works for exactly
+ * one Site: the host names it, the viewer is resolved for it, and the agent
+ * principal is `site:<siteId>`.
+ */
+export type SiteRuntimeDeps = Pick<ApiRouteDeps, "db" | "settings" | "objectStorage">;
+export type SiteRuntimeHost = {
+    domain: string;
+    label: string;
+    hostname: string;
+    scope: SitePublishingScope;
+    publication: SitePublicationRecord;
+    site: PublishedSiteRecord;
+};
+/** The Site behind a host, whatever its status (null when the host names no Site). */
+export declare function findSiteRuntimeHost(deps: SiteRuntimeDeps, domain: string, host: string): Promise<SiteRuntimeHost | null>;
+/** The Site behind a host when it is served: 404 for no Site, 410 when not served. */
+export declare function requireServedSiteRuntimeHost(deps: SiteRuntimeDeps, domain: string, host: string): Promise<SiteRuntimeHost & {
+    versionId: string;
+}>;
+export declare function sha256Text(value: string): string;
+/**
+ * Who is viewing: a live site-session of this Site whose person the Site
+ * still admits (membership and invitations are re-read every call), else an
+ * anonymous guest of a public Site, else sign-in is required.
+ *
+ * "View as visitor": a workspace member whose site-session previews another
+ * role is resolved as exactly that role, and only ever downgraded: `public`
+ * is an anonymous guest (refused where guests are not admitted), `invited`
+ * a signed-in person outside the workspace (refused on members-only Sites).
+ * A preview role on the session of anyone who is not a member is ignored, so
+ * it can never grant more than the person already has. `ignoreViewAs`
+ * resolves the real viewer (to start or end a preview).
+ */
+export declare function resolveSiteRuntimeViewer(deps: SiteRuntimeDeps, host: SiteRuntimeHost, fields: SiteGatewayFields, options?: {
+    ignoreViewAs?: boolean;
+}): Promise<SiteRuntimeViewer>;
+/** What a viewer cannot do on a Site: 403 with `details.code` `not_available_for_viewer`. */
+export type SiteViewerFeature = "agent" | "agent_model" | "workspace_tools" | "site_data" | "site_sql";
+export declare function siteNotAvailableForViewer(feature: SiteViewerFeature, message: string, extra?: Record<string, unknown>): import("../http/api-error.js").ApiHttpError;
+/** The viewer capabilities a page reads from `site.config` to hide what won't work. */
+export declare function siteViewerCapabilities(deps: SiteRuntimeDeps, host: SiteRuntimeHost, viewer: SiteRuntimeViewer, limits: SiteLimits): SiteViewerCapabilities;
+export declare function siteRuntimeLimits(deps: SiteRuntimeDeps, host: SiteRuntimeHost, viewer?: Pick<SiteRuntimeViewer, "kind">): Promise<SiteLimits>;
+/**
+ * The limits that govern a viewer and the kind of limit profile they come
+ * from: workspace members are never limited by Site limits (flood brakes
+ * only); everyone else gets the Site's limits (siteViewerLimits). Without a
+ * viewer: the Site's limits.
+ */
+export declare function siteRuntimeLimitProfile(deps: SiteRuntimeDeps, host: SiteRuntimeHost, viewer?: Pick<SiteRuntimeViewer, "kind">): Promise<{
+    limits: SiteLimits;
+    kind: SiteLimitProfileKind;
+}>;
+/** A guest's client address may carry this many visitors' worth of traffic. */
+export declare const SITE_GUEST_IP_LIMIT_FACTOR = 4;
+/**
+ * A viewer's per-minute bucket. Guests are also counted per signed client
+ * address (`ip:<address>`, `SITE_GUEST_IP_LIMIT_FACTOR` times the visitor
+ * limit), so minting new visitor ids does not reset their limits; both must
+ * pass.
+ */
+export declare function enforceSiteRuntimeViewerRate(deps: SiteRuntimeDeps, host: SiteRuntimeHost, viewer: SiteRuntimeViewer, fields: Pick<SiteGatewayFields, "clientIp">, bucket: SiteRuntimeRateBucket, limit: number | null): Promise<void>;
+/**
+ * The rate principal of the signed client address (`ip:unknown` when the
+ * gateway sent none). IPv6 addresses count per /64 (one subscriber usually
+ * holds a whole /64, so per-address keys would be free to rotate);
+ * IPv4-mapped IPv6 counts as its IPv4 address.
+ */
+export declare function siteClientAddressPrincipal(fields: Pick<SiteGatewayFields, "clientIp">): string;
+/** A client address as a rate key: IPv4 as is, IPv6 as its /64 prefix. */
+export declare function siteClientAddressKey(raw: string): string;
+/** Count one operation in a per-minute bucket; 429 with Retry-After past `limit` (null: no limit). */
+export declare function enforceSiteRuntimeRate(deps: SiteRuntimeDeps, host: SiteRuntimeHost, principal: string, bucket: SiteRuntimeRateBucket, limit: number | null): Promise<void>;
+export { SITE_RUNTIME_AGENT_PERMISSIONS };
+/** A short display label for the viewer, recorded as the end user of the agent's work. */
+export declare function siteRuntimeViewerLabel(viewer: SiteRuntimeViewer): string;
+/** Whether this viewer may use the Site's embedded agent at all (before budgets). */
+export declare function siteAgentRefusal(deps: SiteRuntimeDeps, host: SiteRuntimeHost, viewer: SiteRuntimeViewer, limits: SiteLimits): string | null;
+export declare function requireSiteAgent(deps: SiteRuntimeDeps, host: SiteRuntimeHost, viewer: SiteRuntimeViewer, limits: SiteLimits): void;
+/** The 429 for a refused reservation. */
+export declare function siteBudgetExhausted(budget: SiteRuntimeBudget): import("../http/api-error.js").ApiHttpError;
+/** Seconds a viewer waits before retrying a start or message refused as busy. */
+export declare const SITE_BUDGET_BUSY_RETRY_SECONDS = 30;
+/**
+ * The 429 when only other running conversations' reservations refuse a
+ * reservation: the budget has room once their spend settles, so it is worth
+ * retrying shortly (`site_budget_busy`, with `retryAfterSeconds`).
+ */
+export declare function siteBudgetBusy(budget: SiteRuntimeBudget): import("../http/api-error.js").ApiHttpError;
+/** The 429 for a refused reservation, busy or exhausted. */
+export declare function siteReservationRefused(result: Extract<SiteRuntimeReservation, {
+    ok: false;
+}>): import("../http/api-error.js").ApiHttpError;
+/**
+ * The budgets a conversation start or message is reserved against. Members
+ * reserve nothing (their caps are all null). For everyone else a
+ * conversation is bounded by the per-conversation cap, else by the smallest
+ * spend limit that applies, so a session usage limit always holds it.
+ */
+export declare function siteRuntimeBudgetLimits(limits: SiteLimits, settings: Pick<SiteRuntimeDeps["settings"], "sitesAgentReservationMicrosPerTurn">): SiteRuntimeBudgetLimits;
+/**
+ * The Site-wide usage windows a viewer's conversations count in: members
+ * count apart (`*members`), so they never use up the Site limit.
+ */
+export declare function siteRuntimeBudgetKey(viewer: Pick<SiteRuntimeViewer, "kind">): string;
+/** Whether a refusal is a Site-wide budget (stale reservations of others may free it). */
+export declare function siteWideBudget(result: SiteRuntimeReservation): boolean;
+/** A conversation's session usage as read while settling. */
+export type SiteConversationUsage = {
+    usedMicros: number;
+    limitMicros: number | null;
+    version: number;
+};
+/**
+ * Bring a conversation's counted spend up to its session usage so far and
+ * release what it no longer needs reserved (all of it once the session is
+ * idle, or when `release` says so). A start whose session never appeared is
+ * released entirely. A read failure leaves the counters as they are; the
+ * session's own usage limit still caps the conversation.
+ */
+export declare function settleSiteRuntimeSpend(deps: SiteRuntimeDeps, host: SiteRuntimeHost, conversation: Pick<SiteRuntimeConversationRecord, "sessionId" | "admissions"> & Partial<Pick<SiteRuntimeConversationRecord, "createdAt">>, options?: {
+    release?: boolean;
+}): Promise<SiteConversationUsage | null>;
+/**
+ * Lift the session usage limit a Site stamped on a workspace member's
+ * conversation before members were kept out of Site limits: cleared only
+ * while it is still exactly the Site's cap (`siteCapMicros`), so a limit
+ * someone set on the session since is kept. Failure refuses admission; the
+ * caller retains its durable normalization marker and retries next time.
+ */
+export declare function liftSiteConversationUsageLimit(deps: SiteRuntimeDeps, host: SiteRuntimeHost, sessionId: string, siteCapMicros: number, usage: SiteConversationUsage | null): Promise<void>;
+/**
+ * Stamp only funded execution: cumulative spend plus the current reservation,
+ * bounded by the conversation cap. Top-ups reserve atomically before this
+ * raises the ceiling; reread under the reservation lock so overlapping
+ * admissions cannot stamp a stale larger allowance. Failure refuses work.
+ */
+export declare function capSiteConversationUsageLimit(deps: SiteRuntimeDeps, host: SiteRuntimeHost, sessionId: string, usage: SiteConversationUsage | null): Promise<void>;
+/**
+ * Release reservations that conversations no longer need, so a Site-wide
+ * budget held by finished, abandoned or long-inactive conversations frees
+ * up. Claims a bounded batch of likely candidates (idle sessions, starts
+ * whose session never appeared, reservations inactive for six hours),
+ * least recently visited first and each at most every 30 seconds, and
+ * settles each. A sweep that finds nothing pauses sweeping the Site for a
+ * few seconds, so refused starts in a burst cost one cheap check at most.
+ * Returns whether any reservation was visited.
+ */
+export declare function sweepSiteRuntimeReservations(deps: SiteRuntimeDeps, host: SiteRuntimeHost): Promise<boolean>;
+/** Usage-only metering for Site runtime events (agent spend is metered by the session itself). */
+export declare function meterSiteRuntime(deps: SiteRuntimeDeps, host: SiteRuntimeHost, event: {
+    type: "conversation" | "sign_in" | "report";
+    viewer?: SiteRuntimeViewer;
+}): Promise<void>;
+/**
+ * Run an ordinary session route in this process as the Site's service
+ * principal (`site:<siteId>`), with a 60-second delegated token carrying only
+ * session permissions and the viewer as its display label. The Site and the
+ * served version ride along as the request's Site origin, so new sessions and
+ * turns record where they came from. The route authorizes as usual.
+ */
+export declare function siteRuntimeSessionRequest(deps: SiteRuntimeDeps, host: SiteRuntimeHost & {
+    versionId: string;
+}, viewer: SiteRuntimeViewer, input: {
+    origin: string;
+    method: string;
+    path: string;
+    body?: unknown;
+    extraPermissions?: readonly Permission[];
+}): Promise<Request>;
+/** A forwarded response without cookies (site-runtime never sets any). */
+export declare function siteRuntimeForwardedResponse(response: Response): Response;