@opengeni/api-router 2.0.1 → 2.0.2-canary.38789554071001

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/dist/app.js +1 -1
  2. package/dist/browser-action-fences.d.ts +13 -0
  3. package/dist/browser-lost-runtime-end.d.ts +24 -0
  4. package/dist/{chunk-ZDTWXRFX.js → chunk-QLJPLU7J.js} +13405 -5201
  5. package/dist/{chunk-ZDTWXRFX.js.map → chunk-QLJPLU7J.js.map} +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/integrations/atlassian.d.ts +1 -1
  8. package/dist/integrations/github-lens-connect.d.ts +2 -1
  9. package/dist/integrations/slack-interactions.d.ts +1 -1
  10. package/dist/interaction-agent-access.d.ts +9 -0
  11. package/dist/interaction-agent-version.d.ts +21 -0
  12. package/dist/interaction-route-stages.d.ts +25 -0
  13. package/dist/interaction-secrets.d.ts +4 -0
  14. package/dist/mcp/company-profile-agent-admin.d.ts +12 -0
  15. package/dist/mcp/scheduled-task-input.d.ts +35 -4
  16. package/dist/mcp/scheduled-task-view.d.ts +4 -4
  17. package/dist/mcp/server.d.ts +1 -1
  18. package/dist/mcp/site-agent-clamp-tools.d.ts +38 -0
  19. package/dist/mcp/site-data-tools.d.ts +7 -1
  20. package/dist/mcp/site-publication-tools.d.ts +19 -0
  21. package/dist/mcp/site-sql-tools.d.ts +27 -0
  22. package/dist/routes/client-errors.d.ts +1 -0
  23. package/dist/routes/desktop-distribution.d.ts +32 -0
  24. package/dist/routes/sessions.d.ts +8 -0
  25. package/dist/routes/site-publishing.d.ts +5 -0
  26. package/dist/routes/site-runtime.d.ts +31 -0
  27. package/dist/routes/site-sql.d.ts +16 -0
  28. package/dist/site-agent-guard.d.ts +53 -0
  29. package/dist/site-data/operations.d.ts +15 -15
  30. package/dist/site-data/service.d.ts +23 -3
  31. package/dist/site-frame-guard.d.ts +32 -0
  32. package/dist/site-publishing/agent-data-tools.d.ts +84 -0
  33. package/dist/site-publishing/agent-model.d.ts +58 -0
  34. package/dist/site-publishing/content-scanner.d.ts +31 -0
  35. package/dist/site-publishing/edge-sync.d.ts +48 -0
  36. package/dist/site-publishing/gateway-signature.d.ts +56 -0
  37. package/dist/site-publishing/limits.d.ts +63 -0
  38. package/dist/site-publishing/platform-usage.d.ts +113 -0
  39. package/dist/site-publishing/platform.d.ts +21 -0
  40. package/dist/site-publishing/readiness.d.ts +62 -0
  41. package/dist/site-publishing/runtime.d.ts +179 -0
  42. package/dist/site-publishing/service.d.ts +264 -0
  43. package/dist/site-publishing/session-events.d.ts +22 -0
  44. package/dist/site-publishing/session-views.d.ts +36 -0
  45. package/dist/site-publishing/viewer.d.ts +40 -0
  46. package/dist/site-session-origin.d.ts +21 -7
  47. package/dist/site-sql/format.d.ts +47 -0
  48. package/dist/site-sql/gateway.d.ts +50 -0
  49. package/dist/site-sql/service.d.ts +213 -0
  50. package/package.json +22 -22
  51. package/src/app.ts +46 -5
  52. package/src/browser-action-fences.ts +45 -0
  53. package/src/browser-lost-runtime-end.ts +71 -0
  54. package/src/codemode.ts +42 -10
  55. package/src/http/auth.ts +13 -3
  56. package/src/interaction-agent-access.ts +32 -0
  57. package/src/interaction-agent-version.ts +85 -0
  58. package/src/interaction-route-stages.ts +83 -0
  59. package/src/interaction-secrets.ts +6 -1
  60. package/src/mcp/action-catalog.gen.ts +204 -0
  61. package/src/mcp/action-descriptions.ts +2 -2
  62. package/src/mcp/action-schema-imports.gen.ts +13 -1
  63. package/src/mcp/company-profile-agent-admin.ts +13 -0
  64. package/src/mcp/editable-artifacts.ts +17 -5
  65. package/src/mcp/knowledge-entries.ts +52 -24
  66. package/src/mcp/secret-tools.ts +21 -5
  67. package/src/mcp/server.ts +117 -10
  68. package/src/mcp/session-admin-access-tools.ts +5 -0
  69. package/src/mcp/site-agent-clamp-tools.ts +140 -0
  70. package/src/mcp/site-data-tools.ts +54 -9
  71. package/src/mcp/site-publication-tools.ts +201 -0
  72. package/src/mcp/site-sql-tools.ts +427 -0
  73. package/src/routes/automations.ts +30 -8
  74. package/src/routes/browser-sessions.ts +303 -26
  75. package/src/routes/computer-sessions.ts +18 -1
  76. package/src/routes/desktop-distribution.ts +217 -0
  77. package/src/routes/machines.ts +9 -2
  78. package/src/routes/pr-review.ts +3 -0
  79. package/src/routes/scheduled-tasks.ts +6 -4
  80. package/src/routes/session-admin-access.ts +13 -0
  81. package/src/routes/sessions.ts +196 -3
  82. package/src/routes/site-publishing.ts +584 -0
  83. package/src/routes/site-runtime.ts +1867 -0
  84. package/src/routes/site-sql.ts +263 -0
  85. package/src/routes/vaults.ts +7 -1
  86. package/src/routes/workspace-artifacts.ts +56 -31
  87. package/src/sandbox/channel-a.ts +47 -5
  88. package/src/site-agent-guard.ts +261 -0
  89. package/src/site-data/operations.ts +18 -14
  90. package/src/site-data/service.ts +77 -3
  91. package/src/site-frame-guard.ts +107 -0
  92. package/src/site-publishing/agent-data-tools.ts +250 -0
  93. package/src/site-publishing/agent-model.ts +127 -0
  94. package/src/site-publishing/content-scanner.ts +93 -0
  95. package/src/site-publishing/edge-sync.ts +148 -0
  96. package/src/site-publishing/gateway-signature.ts +198 -0
  97. package/src/site-publishing/limits.ts +315 -0
  98. package/src/site-publishing/platform-usage.ts +479 -0
  99. package/src/site-publishing/platform.ts +98 -0
  100. package/src/site-publishing/readiness.ts +330 -0
  101. package/src/site-publishing/runtime.ts +830 -0
  102. package/src/site-publishing/service.ts +1282 -0
  103. package/src/site-publishing/session-events.ts +262 -0
  104. package/src/site-publishing/session-views.ts +262 -0
  105. package/src/site-publishing/viewer.ts +75 -0
  106. package/src/site-session-origin.ts +63 -6
  107. package/src/site-sql/format.ts +134 -0
  108. package/src/site-sql/gateway.ts +168 -0
  109. package/src/site-sql/service.ts +1636 -0
  110. package/src/workspace-deletion.ts +5 -0
@@ -0,0 +1,32 @@
1
+ import type { Hono } from "hono";
2
+ import type { ApiRouteDeps } from "@opengeni/core";
3
+ export declare const DESKTOP_INSTALLER_PATH = "/desktop/install.sh";
4
+ export declare const DESKTOP_RELEASE_PAGE_PATH = "/desktop/latest";
5
+ export declare const DESKTOP_DOWNLOAD_PREFIX = "/desktop/latest/";
6
+ /** The versioned release file for a version-less name, or null if it isn't one. */
7
+ export declare function desktopReleaseFile(asset: string, version: string): string | null;
8
+ /** The highest stable version among desktop-v<version> tags. */
9
+ export declare function newestDesktopVersion(tags: readonly string[]): string | null;
10
+ /** owner/name for a https://github.com/<owner>/<name>/releases base, else null. */
11
+ export declare function githubRepositoryOf(releasesBase: string): string | null;
12
+ export interface DesktopVersionResolverOptions {
13
+ /** An operator pin. When set, it is the only version ever served. */
14
+ pinnedVersion?: string | undefined;
15
+ releasesBase: string;
16
+ fetchImpl?: typeof fetch;
17
+ now?: () => number;
18
+ /** How long a looked-up version is reused. */
19
+ freshForMs?: number;
20
+ /** How long to wait before looking again after a failed lookup. */
21
+ retryAfterMs?: number;
22
+ }
23
+ /**
24
+ * The version /desktop/latest serves: the pin, or the newest desktop-v tag on
25
+ * the release repository. A lookup is shared by concurrent requests and reused
26
+ * for ten minutes, well within GitHub's unauthenticated rate limit. When GitHub
27
+ * is unreachable the last known version keeps serving.
28
+ */
29
+ export declare function createDesktopVersionResolver(options: DesktopVersionResolverOptions): () => Promise<string>;
30
+ export declare function desktopInstallerFor(body: string, publicBaseUrl: string | undefined): string;
31
+ export declare function registerDesktopDistributionRoutes(app: Hono, deps: ApiRouteDeps, resolveVersion?: () => Promise<string>): void;
32
+ export declare function isDesktopDistributionPath(path: string): boolean;
@@ -1,3 +1,4 @@
1
+ import { type AgentCapabilities } from "@opengeni/contracts";
1
2
  import { ClientSessionEvent, SessionScopeSubjectId, SteerSessionMessageRequest, type SessionStatus, type WorkClaimSubjectFilter, type SessionGoalRevision, type SessionAuthorizationOperation } from "@opengeni/contracts";
2
3
  import { decodeSessionListCursor, type SessionDiscoveryCursor } from "@opengeni/db";
3
4
  import type { Context, Hono } from "hono";
@@ -65,6 +66,13 @@ export declare function agentTopologyQuery(query: Record<string, string>): {
65
66
  claimLimit: number | undefined;
66
67
  cursor: SessionDiscoveryCursor | undefined;
67
68
  };
69
+ /**
70
+ * A Site page's session capabilities: the workspace default with workspace
71
+ * administration (sandboxes, Connected Machines, `run_on`) and browser and
72
+ * computer control off. Capabilities this server does not offer are left to
73
+ * the default, so the create never fails on them.
74
+ */
75
+ export declare function siteFrameCapabilities(workspaceDefault: AgentCapabilities, unavailable: Readonly<Partial<Record<string, string>>>): Exclude<AgentCapabilities, string>;
68
76
  /** Stable, value-free JSON errors for only the create-session boundary. */
69
77
  export declare function sessionCreateErrorResponse(c: Context, error: unknown): Response;
70
78
  export declare function parseSessionEventAdmission(raw: unknown): ClientSessionEvent;
@@ -0,0 +1,5 @@
1
+ import { type ApiRouteDeps } from "@opengeni/core";
2
+ import type { Hono } from "hono";
3
+ /** A one-time sign-in code lives this long. */
4
+ export declare const SITE_AUTH_CODE_TTL_SECONDS = 60;
5
+ export declare function registerSitePublishingRoutes(app: Hono, deps: ApiRouteDeps): void;
@@ -0,0 +1,31 @@
1
+ import { type SiteEmbeddedAgent, type ToolRef } from "@opengeni/contracts";
2
+ import { type ApiRouteDeps } from "@opengeni/core";
3
+ import type { Hono } from "hono";
4
+ import { type SiteRuntimeViewer } from "../site-publishing/viewer.js";
5
+ /** Request bodies site-runtime reads at most (the gateway enforces the same caps). */
6
+ export declare const SITE_RUNTIME_JSON_BODY_LIMIT: number;
7
+ export declare const SITE_RUNTIME_FILE_BODY_LIMIT: number;
8
+ /** A version a publish or rollback replaced is still served this long (open pages keep loading). */
9
+ export declare const SITE_VERSION_GRACE_SECONDS = 600;
10
+ /** The document policy for a published version: scripts in an opaque origin, framed only by its own shell. */
11
+ export declare const SITE_VERSION_CONTENT_SECURITY_POLICY = "sandbox allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals; frame-ancestors 'self'";
12
+ /**
13
+ * The Site-safe projection of a session: no account or workspace ids,
14
+ * instructions, tools or policies, metadata, creator, sandbox or diagnostics.
15
+ */
16
+ export declare function siteSessionProjection(session: unknown): Record<string, unknown>;
17
+ /**
18
+ * The workspace tools a Site conversation gets: the OVERLAP of what the Site
19
+ * declares (its admin-chosen MCP connections) and what the viewer may do in
20
+ * the workspace. Only workspace members who may attach MCP connections to
21
+ * their own sessions (`mcp_servers:attach`, or workspace admins) get them.
22
+ * People outside the workspace (invited people and public visitors, signed in
23
+ * or anonymous) never get workspace tools: only the Site's own data and the
24
+ * page. There is no setting that changes this; `guestTools` is ignored.
25
+ * Optional references: a connection the workspace does not have is skipped
26
+ * rather than failing the conversation.
27
+ */
28
+ export declare function siteAgentToolRefs(agent: Pick<SiteEmbeddedAgent, "tools">, viewer: Pick<SiteRuntimeViewer, "kind">, memberPermissions?: readonly string[] | null): ToolRef[];
29
+ /** Only workspace members who may use MCP connections get the Site's tools. */
30
+ export declare function siteViewerGetsTools(viewer: Pick<SiteRuntimeViewer, "kind">, memberPermissions: readonly string[] | null): boolean;
31
+ export declare function registerSiteRuntimeRoutes(app: Hono, deps: ApiRouteDeps): void;
@@ -0,0 +1,16 @@
1
+ import { type ApiRouteDeps } from "@opengeni/core";
2
+ import type { Context, Hono } from "hono";
3
+ import { z } from "zod";
4
+ import { ApiHttpError } from "../http/api-error.js";
5
+ import { SiteSqlError } from "../site-sql/service.js";
6
+ /** Typed Site SQL errors in the public envelope; `details.code` is the Site SQL code. */
7
+ export declare function siteSqlHttpError(error: SiteSqlError): ApiHttpError;
8
+ export declare function runSiteSqlRoute<T>(fn: () => Promise<T>): Promise<T>;
9
+ export declare function siteSqlBody<S extends z.ZodType>(context: Context, schema: S): Promise<z.infer<S>>;
10
+ /**
11
+ * Site SQL routes. Running a named query needs Site access (`artifacts:read`
12
+ * and the viewer's audience); the query's audience decides the rest. Everything
13
+ * else is management: a manager of the Site outside any Site frame, with
14
+ * `artifacts:read` to look and `artifacts:publish` to change.
15
+ */
16
+ export declare function registerSiteSqlRoutes(app: Hono, deps: ApiRouteDeps): void;
@@ -0,0 +1,53 @@
1
+ import { type ApiRouteDeps, type SiteClampedResource } from "@opengeni/core";
2
+ import type { Context, Next } from "hono";
3
+ /**
4
+ * The only writes (any method but `GET`, `HEAD` and `OPTIONS`) a
5
+ * Site-started agent may send under `/v1/workspaces/:workspaceId`, matched
6
+ * on the path after the workspace id. Every other write is refused, so a
7
+ * route family added later starts closed to it.
8
+ */
9
+ export declare const SITE_AGENT_WRITES: readonly RegExp[];
10
+ /**
11
+ * Writes open to a Site-started agent for one method only, where the same
12
+ * path also manages something. A Site's named query runs with `POST`
13
+ * (exactly what its page may call, under the query's audience; Site SQL's
14
+ * own clamp limits it to the Site the agent was started from), while `PUT`
15
+ * and `DELETE` on that path define and delete the query and stay closed, as
16
+ * does every other Site SQL route (settings, migrations, ad hoc statements,
17
+ * import and reset).
18
+ */
19
+ export declare const SITE_AGENT_METHOD_WRITES: readonly {
20
+ method: string;
21
+ pattern: RegExp;
22
+ }[];
23
+ /**
24
+ * Whether a Site-started agent may send a `method` write to `path` (before
25
+ * the Site content rule). Without a method only the path-wide allowlist
26
+ * applies.
27
+ */
28
+ export declare function siteAgentMayWrite(path: string, method?: string): boolean;
29
+ /** What a refused write to `path` names. */
30
+ export declare function siteAgentWriteResource(path: string): SiteClampedResource;
31
+ /**
32
+ * Server-side boundary for agents started from a Site page (a published
33
+ * Site, or a console frame). Such an agent acts with the page's reach: it
34
+ * does not learn and cannot widen anyone's access. Under
35
+ * `/v1/workspaces/:workspaceId` it may send only the writes in
36
+ * `SITE_AGENT_WRITES` (its tools, its conversations, files and content, and
37
+ * reads sent as POST) and `SITE_AGENT_METHOD_WRITES` (running a Site's named
38
+ * SQL queries); any other write, including `PATCH` or `DELETE` on the
39
+ * workspace itself and browser or computer sessions (which can drive the
40
+ * viewer's Chrome or screen), is refused with 403 before the route runs. It also
41
+ * changes a published Site's content only for a Site it was started from.
42
+ * Reads are unaffected, and so is every caller that is not a Site-clamped
43
+ * agent. The first-party tools that write workspace state (`knowledge_save`,
44
+ * `instruction_policy_save`, `secret_save`, `skill_save`,
45
+ * `company_profile_propose`, the Connected Machine, sandbox environment and
46
+ * fleet tools (`run_on`, `sandbox_attach`, `sandbox_swap`,
47
+ * `sandbox_provision`), the artifact tools and their siblings) check the
48
+ * same clamp themselves.
49
+ *
50
+ * Paths are matched as Hono routes them (`c.req.path`, percent-decoded), so
51
+ * an encoded segment cannot reach a route this guard did not recognize.
52
+ */
53
+ export declare function siteClampedAgentGuard(deps: ApiRouteDeps): (c: Context, next: Next) => Promise<void>;
@@ -1,7 +1,7 @@
1
1
  import type { ApiRouteDeps } from "@opengeni/core";
2
- import type { AccessGrant, SiteDataCollectionDefinitionRequest, SiteDataDescribeResponse, SiteDataFileScope, SiteDataImportRequest, SiteDataQueryRequest, SiteDataWriteOperation } from "@opengeni/contracts";
2
+ import type { SiteDataCollectionDefinitionRequest, SiteDataDescribeResponse, SiteDataFileScope, SiteDataImportRequest, SiteDataQueryRequest, SiteDataWriteOperation } from "@opengeni/contracts";
3
3
  import { type SiteDataFile, type SiteDataRecord } from "@opengeni/db";
4
- import { type SiteDataDeps, type SiteDataSurface } from "./service.js";
4
+ import { type SiteDataAuthority, type SiteDataDeps, type SiteDataSurface } from "./service.js";
5
5
  /** Shared Site Data operations for HTTP routes, the Site bridge and agent tools. */
6
6
  export declare const SITE_DATA_EXPORT_MAX_RECORDS = 10000;
7
7
  export declare const SITE_DATA_IMPORT_MAX_RECORDS = 1000;
@@ -11,24 +11,24 @@ export declare const SITE_DATA_IMPORT_MAX_COLUMNS = 1000;
11
11
  export declare const SITE_DATA_EXPORT_MAX_COLUMNS = 200;
12
12
  /** Exports stop adding records past this many bytes and report truncation. */
13
13
  export declare const SITE_DATA_EXPORT_MAX_BYTES: number;
14
- export declare function describeSiteData(deps: SiteDataDeps, grant: AccessGrant, siteId: string): Promise<SiteDataDescribeResponse>;
15
- export declare function defineSiteDataCollection(deps: SiteDataDeps, grant: AccessGrant, siteId: string, name: string, definition: SiteDataCollectionDefinitionRequest): Promise<{
14
+ export declare function describeSiteData(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string): Promise<SiteDataDescribeResponse>;
15
+ export declare function defineSiteDataCollection(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, name: string, definition: SiteDataCollectionDefinitionRequest): Promise<{
16
16
  collection: import("@opengeni/db").SiteDataCollection;
17
17
  created: boolean;
18
18
  }>;
19
- export declare function deleteSiteDataCollection(deps: SiteDataDeps, grant: AccessGrant, siteId: string, name: string): Promise<{
19
+ export declare function deleteSiteDataCollection(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, name: string): Promise<{
20
20
  deletedRecords: number;
21
21
  }>;
22
- export declare function resetSiteDataCollection(deps: SiteDataDeps, grant: AccessGrant, siteId: string, name: string): Promise<{
22
+ export declare function resetSiteDataCollection(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, name: string): Promise<{
23
23
  deletedRecords: number;
24
24
  }>;
25
- export declare function querySiteData(deps: SiteDataDeps, grant: AccessGrant, siteId: string, query: SiteDataQueryRequest, surface?: SiteDataSurface): Promise<import("@opengeni/db").SiteDataQueryResult>;
26
- export declare function getSiteDataRecord(deps: SiteDataDeps, grant: AccessGrant, siteId: string, request: {
25
+ export declare function querySiteData(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, query: SiteDataQueryRequest, surface?: SiteDataSurface): Promise<import("@opengeni/db").SiteDataQueryResult>;
26
+ export declare function getSiteDataRecord(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, request: {
27
27
  collection: string;
28
28
  id?: string | undefined;
29
29
  key?: string | undefined;
30
30
  }, surface?: SiteDataSurface): Promise<SiteDataRecord | null>;
31
- export declare function writeSiteData(deps: SiteDataDeps, grant: AccessGrant, siteId: string, operations: SiteDataWriteOperation[], surface?: SiteDataSurface): Promise<{
31
+ export declare function writeSiteData(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, operations: SiteDataWriteOperation[], surface?: SiteDataSurface): Promise<{
32
32
  results: import("@opengeni/db").SiteDataWriteResultItem[];
33
33
  summary: import("@opengeni/db").SiteDataWriteSummary;
34
34
  }>;
@@ -49,7 +49,7 @@ export declare function siteDataCsvCell(value: unknown): string;
49
49
  * record is built in one pass.
50
50
  */
51
51
  export declare function siteDataCsvRecords(csv: string): Record<string, unknown>[];
52
- export declare function importSiteData(deps: SiteDataDeps, grant: AccessGrant, siteId: string, collection: string, request: SiteDataImportRequest): Promise<{
52
+ export declare function importSiteData(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, collection: string, request: SiteDataImportRequest): Promise<{
53
53
  imported: number;
54
54
  }>;
55
55
  /**
@@ -63,14 +63,14 @@ export declare function siteDataImportFailure(error: unknown, imported: number):
63
63
  * repeated as field names on every row.
64
64
  */
65
65
  export declare function csvValidationBytes(csv: string): number;
66
- export declare function exportSiteData(deps: SiteDataDeps, grant: AccessGrant, siteId: string, collection: string, format: "json" | "csv"): Promise<{
66
+ export declare function exportSiteData(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, collection: string, format: "json" | "csv"): Promise<{
67
67
  collection: string;
68
68
  format: "json" | "csv";
69
69
  records: number;
70
70
  truncated: boolean;
71
71
  content: string;
72
72
  }>;
73
- export declare function uploadSiteDataFile(deps: SiteDataDeps & Pick<ApiRouteDeps, "objectStorage">, grant: AccessGrant, siteId: string, input: {
73
+ export declare function uploadSiteDataFile(deps: SiteDataDeps & Pick<ApiRouteDeps, "objectStorage">, grant: SiteDataAuthority, siteId: string, input: {
74
74
  name: string | null | undefined;
75
75
  contentType: string | null | undefined;
76
76
  /**
@@ -84,19 +84,19 @@ export declare function uploadSiteDataFile(deps: SiteDataDeps & Pick<ApiRouteDep
84
84
  };
85
85
  scope?: SiteDataFileScope | undefined;
86
86
  }, surface?: SiteDataSurface): Promise<SiteDataFile>;
87
- export declare function listSiteDataFiles(deps: SiteDataDeps, grant: AccessGrant, siteId: string, options: {
87
+ export declare function listSiteDataFiles(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, options: {
88
88
  limit?: number;
89
89
  cursor?: string | null;
90
90
  }, surface?: SiteDataSurface): Promise<{
91
91
  files: SiteDataFile[];
92
92
  nextCursor: string | null;
93
93
  }>;
94
- export declare function getSiteDataFileUrl(deps: SiteDataDeps & Pick<ApiRouteDeps, "objectStorage">, grant: AccessGrant, siteId: string, fileId: string, surface?: SiteDataSurface, audience?: "public" | "sandbox"): Promise<{
94
+ export declare function getSiteDataFileUrl(deps: SiteDataDeps & Pick<ApiRouteDeps, "objectStorage">, grant: SiteDataAuthority, siteId: string, fileId: string, surface?: SiteDataSurface, audience?: "public" | "sandbox"): Promise<{
95
95
  file: SiteDataFile;
96
96
  url: string;
97
97
  expiresAt: string;
98
98
  }>;
99
- export declare function deleteSiteDataFile(deps: SiteDataDeps & Pick<ApiRouteDeps, "objectStorage">, grant: AccessGrant, siteId: string, fileId: string, surface?: SiteDataSurface): Promise<{
99
+ export declare function deleteSiteDataFile(deps: SiteDataDeps & Pick<ApiRouteDeps, "objectStorage">, grant: SiteDataAuthority, siteId: string, fileId: string, surface?: SiteDataSurface): Promise<{
100
100
  deleted: {
101
101
  id: string;
102
102
  };
@@ -164,18 +164,38 @@ export type SiteDataSurface = {
164
164
  /** Management surfaces: describe, define, delete, reset, import, export. */
165
165
  management?: boolean;
166
166
  };
167
+ /**
168
+ * A viewer of a published Site, resolved and authorized by site-runtime (the
169
+ * gateway-signed API): a signed-in person (`user:<subject>`) or an anonymous
170
+ * guest (`guest:<visitor>`). Always a framed viewer of exactly this Site;
171
+ * guests reach only what each collection's guest rule allows.
172
+ */
173
+ export type PublishedSiteDataViewer = {
174
+ kind: "published_viewer";
175
+ accountId: string;
176
+ workspaceId: string;
177
+ site: SiteDataSite;
178
+ principal: string;
179
+ guest: boolean;
180
+ };
181
+ /** Who is calling Site Data: an access grant, or a published Site viewer. */
182
+ export type SiteDataAuthority = AccessGrant | PublishedSiteDataViewer;
167
183
  /**
168
184
  * Resolve the Site and caller. not_found when the caller cannot see the Site
169
185
  * (by audience); forbidden for an archived Site (viewers and Site frames) and
170
186
  * for management by anyone but a manager outside the Site frame.
171
187
  */
172
- export declare function resolveSiteDataAccess(deps: SiteDataDeps, grant: AccessGrant, siteId: string, surface?: SiteDataSurface): Promise<SiteDataAccess>;
188
+ export declare function resolveSiteDataAccess(deps: SiteDataDeps, authority: SiteDataAuthority, siteId: string, surface?: SiteDataSurface): Promise<SiteDataAccess>;
173
189
  /**
174
190
  * Usage metering in `usage_only` mode (docs/credit-boundaries-rollout.md): the
175
191
  * workspace pays for viewer-triggered usage; events are recorded in the write
176
- * transaction and never debit credits until a reviewed rate is enabled.
192
+ * transaction and never debit credits until a reviewed rate is enabled. The
193
+ * workspace's Site storage level (Site SQL plus Site Data) is refreshed in
194
+ * its platform usage in the same transaction; any charge for it settles with
195
+ * the next platform usage the API meters (a Site SQL call or a gateway
196
+ * request report).
177
197
  */
178
- export declare function meterSiteData(tx: Database, grant: AccessGrant, caller: SiteDataCaller, subjectId: string | null, kind: "write" | "upload", summary: SiteDataWriteSummary): Promise<void>;
198
+ export declare function meterSiteData(tx: Database, grant: Pick<AccessGrant, "accountId" | "workspaceId">, caller: SiteDataCaller, subjectId: string | null, kind: "write" | "upload", summary: SiteDataWriteSummary): Promise<void>;
179
199
  /** Normalize and check a declared upload type; images and PDFs must match their bytes. */
180
200
  export declare function siteDataFileContentType(declared: string | null | undefined, bytes: Uint8Array): string;
181
201
  export declare function siteDataFileName(name: string | null | undefined): string;
@@ -0,0 +1,32 @@
1
+ import { type ApiRouteDeps } from "@opengeni/core";
2
+ import type { Context, Next } from "hono";
3
+ import { ApiHttpError } from "./http/api-error.js";
4
+ /**
5
+ * Server-side boundary for requests a host forwarded from a Site frame (the
6
+ * console bridge, a Codemode preview). Hosts already hold Site code to the
7
+ * `SITE_OPERATIONS` allowlist; the API enforces it again for any request that
8
+ * carries the host's frame headers:
9
+ *
10
+ * - only allowlisted operations reach a handler;
11
+ * - Site Data only for the frame's own published Site (403, as the Site Data
12
+ * service's own frame clamp answers);
13
+ * - a session list names only the frame's own Site;
14
+ * - a per-session operation reaches only a session the same Site (or, for a
15
+ * frame without a published Site, the same mounted frame) started; anything
16
+ * else is the same 404 as a missing session;
17
+ * - a message, draft, queue or control body carries only the fields Site
18
+ * code may set (`siteFrameBodyRefusal`): text and how the model answers it.
19
+ * Approval decisions, answers to questions, resources, personal resource
20
+ * attachments, MCP credential updates, connection accounts and model
21
+ * context are refused with 403 `site_frame_field_forbidden`; the person
22
+ * gives those in the console. Session creates get the same treatment in
23
+ * the create route, which also applies the minimal Site profile;
24
+ * - a session operation runs inside its validated Site origin, so every
25
+ * session or turn it starts records which Site it came from.
26
+ *
27
+ * Ordinary handlers still authorize every allowed operation with the
28
+ * viewer's own authority.
29
+ */
30
+ export declare function siteFrameGuard(deps: ApiRouteDeps): (c: Context, next: Next) => Promise<void>;
31
+ /** 403 for a body field Site code may not send; names the field, never its value. */
32
+ export declare function siteFrameFieldForbidden(field: string): ApiHttpError;
@@ -0,0 +1,84 @@
1
+ import { type FirstPartyMcpToolName, type SiteLimitProfileKind } from "@opengeni/contracts";
2
+ import type { ApiRouteDeps } from "@opengeni/core";
3
+ import { type SiteRuntimeConversationViewerKind } from "@opengeni/db";
4
+ import type { PublishedSiteDataViewer } from "../site-data/service.js";
5
+ import { type SiteRuntimeHost } from "./runtime.js";
6
+ /**
7
+ * A published Site's own data tools for its agent. Every Site agent
8
+ * conversation (members, invited people and public visitors) gets them,
9
+ * pinned on the server to that Site and acting as the conversation's viewer:
10
+ * the same audience checks and row binding as the Site's page (per-viewer
11
+ * collections, owner binding, `:viewer` and query audiences such as
12
+ * `signed_in` or `managers`). Site management tools (publication, migrate,
13
+ * define, reset, import, export, enable, files and so on) are never given.
14
+ *
15
+ * - `site_data_query`, `site_data_write`: the Site's collections under the
16
+ * viewer's access rules (guests only what each collection's guest rule allows).
17
+ * - `site_sql_run`: the Site's named queries, when Site SQL is on.
18
+ * - `site_sql_query`: read-only statements, for workspace members only, when
19
+ * Site SQL is on.
20
+ */
21
+ export declare const SITE_AGENT_DATA_TOOLS: readonly ["site_data_query", "site_data_write"];
22
+ export declare const SITE_AGENT_SQL_TOOLS: readonly ["site_sql_run"];
23
+ export declare const SITE_AGENT_MEMBER_SQL_TOOLS: readonly ["site_sql_query"];
24
+ /** The first-party permissions those tools need (Site Data writes need publish). */
25
+ export declare const SITE_AGENT_DATA_TOOL_PERMISSIONS: readonly ["artifacts:read", "artifacts:publish"];
26
+ export declare const SITE_AGENT_OTHER_SITE_MESSAGE = "This Site's assistant can only use this Site's data";
27
+ export declare const SITE_AGENT_MANAGEMENT_MESSAGE = "This Site's assistant can use the Site's data, not manage the Site";
28
+ /** The data tools one viewer's Site agent conversation gets, within the deployment's tools. */
29
+ export declare function siteAgentDataToolNames(input: {
30
+ viewerKind: SiteRuntimeConversationViewerKind;
31
+ /** Site SQL is offered here and turned on for this Site. */
32
+ siteSql: boolean;
33
+ /** The deployment's first-party tool allowlist. */
34
+ allowed: readonly string[];
35
+ }): FirstPartyMcpToolName[];
36
+ /** Whether Site SQL is offered on this deployment and turned on for the Site. */
37
+ export declare function siteAgentSiteSqlOn(deps: Pick<ApiRouteDeps, "db" | "settings">, scope: {
38
+ accountId: string;
39
+ workspaceId: string;
40
+ }, siteId: string): Promise<boolean>;
41
+ /** The data tools for a new conversation of this viewer on this Site. */
42
+ export declare function siteAgentDataToolsForStart(deps: Pick<ApiRouteDeps, "db" | "settings">, scope: {
43
+ accountId: string;
44
+ workspaceId: string;
45
+ }, siteId: string, viewerKind: SiteRuntimeConversationViewerKind): Promise<FirstPartyMcpToolName[]>;
46
+ /** This Site's viewer (`user:<subject>` or `guest:<visitor>`) as Site Data and Site SQL see it. */
47
+ export declare function sitePublishedDataViewer(host: Pick<SiteRuntimeHost, "scope" | "site">, principal: string, guest: boolean): PublishedSiteDataViewer;
48
+ /**
49
+ * The Site agent's instructions: which Site and viewer it serves and what its
50
+ * data tools may do, then the owner's own instructions for the Site.
51
+ */
52
+ export declare function siteAgentInstructions(host: Pick<SiteRuntimeHost, "site">, viewer: {
53
+ kind: SiteRuntimeConversationViewerKind;
54
+ }, dataTools: readonly string[], ownerInstructions: string | null | undefined): string;
55
+ /** A Site agent conversation's data context: the pinned Site and the viewer it acts as. */
56
+ export type SiteAgentDataContext = {
57
+ kind: "site";
58
+ siteId: string;
59
+ viewerKind: SiteRuntimeConversationViewerKind;
60
+ viewer: PublishedSiteDataViewer;
61
+ /** The limit profile kind in force (Site SQL limits follow it). */
62
+ profileKind: SiteLimitProfileKind;
63
+ /**
64
+ * Count one write against the guest write limit (anonymous guests only);
65
+ * null when allowed, else the seconds to wait.
66
+ */
67
+ guestWrite: () => Promise<number | null>;
68
+ };
69
+ export type SiteAgentDataResolution = {
70
+ kind: "ordinary";
71
+ } | {
72
+ kind: "refused";
73
+ message: string;
74
+ } | SiteAgentDataContext;
75
+ /**
76
+ * Whether an agent session is a published Site's agent and, if so, the Site
77
+ * and viewer its data tools act for. Ordinary sessions resolve `ordinary`.
78
+ * A Site agent whose conversation, Site or publication cannot be confirmed,
79
+ * or whose member viewer has left the workspace, is refused (fail closed).
80
+ */
81
+ export declare function resolveSiteAgentDataContext(deps: Pick<ApiRouteDeps, "db" | "settings" | "objectStorage">, scope: {
82
+ accountId: string;
83
+ workspaceId: string;
84
+ }, sessionId: string): Promise<SiteAgentDataResolution>;
@@ -0,0 +1,58 @@
1
+ import type { Settings } from "@opengeni/config";
2
+ import { type OrganizationModelDefaults, type WorkspaceSessionDefaults } from "@opengeni/contracts";
3
+ import { type WorkspaceModelSelection } from "@opengeni/core";
4
+ import { type Database } from "@opengeni/db";
5
+ /**
6
+ * The model of a Site agent conversation by who the viewer is.
7
+ *
8
+ * People outside the workspace (invited people and public visitors) never
9
+ * use a subscription-billed model (a connected Codex, Claude or other
10
+ * subscription): Site limits measure real money, and visitors must not use
11
+ * up a subscription's rate limits or terms. When the Site agent's model is a
12
+ * subscription model (or the workspace default it falls back to is one),
13
+ * they get the workspace's default credit-billed model instead, chosen the
14
+ * same way as the workspace's ordinary default over the credit-billed models
15
+ * only. When the workspace has none, they are refused. Workspace members use
16
+ * the Site agent's model, subscriptions included.
17
+ */
18
+ export type SiteOutsideModelChoice =
19
+ /** The Site agent's model (or the workspace default it resolves to), not a subscription. */
20
+ {
21
+ kind: "same";
22
+ model: string;
23
+ } | {
24
+ kind: "fallback";
25
+ model: string;
26
+ } | {
27
+ kind: "unavailable";
28
+ };
29
+ /** Whether a model is billed through a subscription rather than credits. */
30
+ export declare function isSubscriptionBilledModel(selections: readonly WorkspaceModelSelection[], model: string): boolean;
31
+ /** The decision for people outside the workspace, from already-loaded selections. */
32
+ export declare function siteOutsideModelChoice(input: {
33
+ settings: Settings;
34
+ selections: readonly WorkspaceModelSelection[];
35
+ /** The Site agent's model; null uses the workspace default. */
36
+ agentModel: string | null;
37
+ workspaceDefaults: WorkspaceSessionDefaults | null;
38
+ organizationDefaults: OrganizationModelDefaults["sessionDefaults"] | null;
39
+ }): SiteOutsideModelChoice;
40
+ /** Actual catalog billing, not just provider-name heuristics, fences every admission. */
41
+ export declare function siteCreditModelIds(deps: {
42
+ db: Database;
43
+ settings: Settings;
44
+ }, scope: {
45
+ accountId: string;
46
+ workspaceId: string;
47
+ }, siteId: string): Promise<string[]>;
48
+ /** Load the workspace's model selection and decide for people outside the workspace. */
49
+ export declare function resolveSiteOutsideModel(deps: {
50
+ db: Database;
51
+ settings: Settings;
52
+ }, scope: {
53
+ accountId: string;
54
+ workspaceId: string;
55
+ }, input: {
56
+ siteId: string;
57
+ agentModel: string | null;
58
+ }): Promise<SiteOutsideModelChoice>;
@@ -0,0 +1,31 @@
1
+ import type { Settings } from "@opengeni/config";
2
+ /**
3
+ * Pluggable content scanning for published Sites. `none` is the default; the
4
+ * Google Web Risk scanner runs only with OPENGENI_SITES_WEB_RISK_API_KEY. A
5
+ * scan looks up the absolute URLs found in a Site's HTML when it is published
6
+ * and records findings for moderation. It never blocks publishing, and a
7
+ * disabled or failing scanner records nothing that blocks either.
8
+ */
9
+ export type SiteContentScanFinding = {
10
+ url: string;
11
+ threatTypes: string[];
12
+ };
13
+ export type SiteContentScanResult = {
14
+ status: "none" | "clean" | "flagged" | "error";
15
+ findings: SiteContentScanFinding[];
16
+ };
17
+ export type SiteContentScanner = {
18
+ readonly name: "none" | "web_risk";
19
+ scanHtml(html: string): Promise<SiteContentScanResult>;
20
+ };
21
+ /** Most distinct URLs one scan looks up (bounds cost per publish). */
22
+ export declare const SITE_SCAN_MAX_URLS = 20;
23
+ /** Distinct absolute http(s) URLs in the HTML, first seen first, at most `limit`. */
24
+ export declare function siteHtmlUrls(html: string, limit?: number): string[];
25
+ export declare const noneSiteContentScanner: SiteContentScanner;
26
+ export declare function createWebRiskSiteContentScanner(apiKey: string, options?: {
27
+ fetch?: typeof fetch;
28
+ }): SiteContentScanner;
29
+ export declare function createSiteContentScanner(settings: Pick<Settings, "sitesWebRiskApiKey">, options?: {
30
+ fetch?: typeof fetch;
31
+ }): SiteContentScanner;
@@ -0,0 +1,48 @@
1
+ import { SiteHostMapRecord } from "@opengeni/contracts";
2
+ import type { Settings } from "@opengeni/config";
3
+ /**
4
+ * Optional Cloudflare edge sync for published Sites. Postgres is the source
5
+ * of truth; the KV host map and the edge cache are rebuildable copies. With
6
+ * no Cloudflare settings every call is a no-op.
7
+ *
8
+ * Writes go through the Cloudflare REST API with plain fetch (no SDK, each
9
+ * call bounded by a 10 s timeout) and never block the database write: callers
10
+ * schedule them after commit, each is retried a few times and then logged.
11
+ * The caller reads what a hostname should hold in a short transaction under
12
+ * the hostname's lock and commits before any of these calls, so no database
13
+ * transaction or lock waits on Cloudflare; after writing it re-reads the
14
+ * hostname and writes again if it moved meanwhile. One process runs at most
15
+ * one sync per hostname at a time. A writer never replaces a newer
16
+ * generation (read, compare, write; KV has no compare-and-set, so writers in
17
+ * two processes racing within one round trip can still land out of order,
18
+ * until the entry's TTL ends it). Generations come from one database
19
+ * sequence shared by every hostname, so a later change to a label (a move,
20
+ * an unpublish tombstone, a takedown) always carries a higher generation
21
+ * than anything written before.
22
+ *
23
+ * Staleness bound: the API itself refuses a suspended or unpublished Site on
24
+ * the very next site-runtime call (it re-checks publication status and access
25
+ * every time). The edge copies lag behind: Cloudflare KV propagates a write
26
+ * to other locations within about 60 s, every KV entry expires after
27
+ * `sitesHostMapTtlSeconds` (default 300 s), and the gateway caches host
28
+ * lookups for up to 60 s and access checks for 30 s. A takedown also purges
29
+ * the host's edge cache when a zone id is configured. The after-commit sync
30
+ * runs in process, so a restart can lose a pending write; the next signed
31
+ * host lookup for that label re-syncs a stale record, and the TTL bounds the
32
+ * rest. A missed sync is therefore corrected within TTL + 60 s at worst.
33
+ */
34
+ export type SiteEdgeSyncSettings = Pick<Settings, "sitesCloudflareApiToken" | "sitesCloudflareAccountId" | "sitesCloudflareKvNamespaceId" | "sitesCloudflareZoneId" | "sitesHostMapTtlSeconds">;
35
+ export type SiteEdgeSync = {
36
+ readonly kvEnabled: boolean;
37
+ readonly purgeEnabled: boolean;
38
+ /** Write the host-map record unless the edge already holds a newer generation. */
39
+ putHostRecord(record: SiteHostMapRecord): Promise<"written" | "skipped_newer" | "disabled">;
40
+ /** Purge the edge cache for one hostname. */
41
+ purgeHost(hostname: string): Promise<"purged" | "disabled">;
42
+ };
43
+ export type SiteEdgeSyncOptions = {
44
+ fetch?: typeof fetch;
45
+ attempts?: number;
46
+ backoffMs?: number;
47
+ };
48
+ export declare function createSiteEdgeSync(settings: SiteEdgeSyncSettings, options?: SiteEdgeSyncOptions): SiteEdgeSync;
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Verification of gateway-signed site-runtime requests. The gateway HMACs
3
+ * `siteGatewayCanonicalString` with the shared secret; the API accepts the
4
+ * current or the previous secret (rotation), within 30 s of its clock. The
5
+ * signed body hash travels in its own header, so the signature is checked
6
+ * from the headers alone, before the body is read; the route then hashes the
7
+ * body as it reads it and refuses a body that does not match. Nothing else
8
+ * about the request is trusted before this passes.
9
+ */
10
+ export type SiteGatewayFields = {
11
+ host: string;
12
+ session: string;
13
+ visitor: string;
14
+ clientIp: string;
15
+ human: boolean;
16
+ };
17
+ export type SiteGatewayVerification = {
18
+ ok: true;
19
+ fields: SiteGatewayFields;
20
+ /** The signed hex SHA-256 the body read afterwards must match. */
21
+ bodySha256: string;
22
+ } | {
23
+ ok: false;
24
+ reason: "not_configured" | "missing_headers" | "bad_timestamp" | "skew" | "bad_body_hash" | "bad_signature" | "body_mismatch" | "credentials";
25
+ };
26
+ /** Request headers that carry Opengeni app credentials; site-runtime refuses them. */
27
+ export declare const SITE_RUNTIME_REFUSED_HEADERS: readonly string[];
28
+ export declare function sha256Hex(bytes: Uint8Array): string;
29
+ export declare function siteGatewaySignature(secret: string, canonical: string): string;
30
+ /**
31
+ * Verify a signed request from its headers alone; the body is not needed.
32
+ * On success the caller reads the body (capped) and checks it against
33
+ * `bodySha256` with `sameSha256Hex`, refusing a mismatch as `body_mismatch`.
34
+ */
35
+ export declare function verifySiteGatewayRequest(input: {
36
+ method: string;
37
+ pathWithQuery: string;
38
+ headers: Headers;
39
+ secrets: readonly (string | undefined)[];
40
+ nowMs?: number;
41
+ }): SiteGatewayVerification;
42
+ /** Whether two hex digests are equal, compared in constant time. */
43
+ export declare function sameSha256Hex(actual: string, signed: string): boolean;
44
+ /** Sign a request as the gateway does (tests and local tools). */
45
+ export declare function signSiteGatewayRequest(input: {
46
+ secret: string;
47
+ method: string;
48
+ pathWithQuery: string;
49
+ host: string;
50
+ body?: Uint8Array | string;
51
+ session?: string;
52
+ visitor?: string;
53
+ clientIp?: string;
54
+ human?: boolean;
55
+ nowMs?: number;
56
+ }): Record<string, string>;