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

package/src/site-session-origin.ts

@@ -1,16 +1,39 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import { SITE_PREVIEW_FRAME, type SiteFrameHeaders } from "@opengeni/contracts/site-session-http";
 import { getWorkspaceSiteSessionOrigin, WorkspaceArtifactNotFoundError } from "@opengeni/db";
-import type { ApiRouteDeps } from "@opengeni/core";
+import {
+  currentSiteSessionOrigin,
+  siteViewerForGrant,
+  withSiteSessionOrigin,
+  type ApiRouteDeps,
+  type SiteSessionOrigin,
+} from "@opengeni/core";
 import { HTTPException } from "hono/http-exception";
 import { z } from "zod";
 
-/** Validates a caller-asserted Site association, not browser execution or authority. */
+const FRAME_ID = /^[A-Za-z0-9_-]{1,64}$/u;
+
+/** The host-set frame marker and per-frame id a Site request carried. */
+export type SiteFrameMarker = {
+  marker?: string | null | undefined;
+  frameId?: string | null | undefined;
+};
+
+/**
+ * Validates a host-asserted Site association, not browser execution or
+ * authority. A published Site (id and version) must be visible to the caller.
+ * A request carrying only the host's frame marker came from a frame without a
+ * published Site (inline HTML, a Codemode preview): it is recorded as that
+ * frame (`siteId: null`, `frame`, `frameId`), never as a published Site.
+ */
 export async function resolveSiteSessionOrigin(
   db: ApiRouteDeps["db"],
-  workspaceId: string,
+  grant: AccessGrant,
   siteId?: string,
   versionId?: string,
-) {
-  if (!siteId && !versionId) return null;
+  frame?: SiteFrameMarker,
+): Promise<SiteSessionOrigin | null> {
+  if (!siteId && !versionId) return frameOnlyOrigin(frame);
   if (
     !z.string().uuid().safeParse(siteId).success ||
     !z.string().uuid().safeParse(versionId).success
@@ -19,10 +42,72 @@ export async function resolveSiteSessionOrigin(
   try {
     // Provenance is not a live-version fence: a response-loss retry still belongs
     // to the same Site after it publishes a new version or is archived.
-    return await getWorkspaceSiteSessionOrigin(db, workspaceId, siteId!, versionId!);
+    const origin = await getWorkspaceSiteSessionOrigin(
+      db,
+      grant.workspaceId,
+      await siteViewerForGrant(db, grant),
+      siteId!,
+      versionId!,
+    );
+    // Absence is reported by the not-found error; a fixture database may answer null.
+    return origin ? { siteId: origin.siteId, title: origin.title, versionId: versionId! } : null;
   } catch (error) {
     if (error instanceof WorkspaceArtifactNotFoundError)
       throw new HTTPException(404, { message: "Site origin not found" });
     throw error;
   }
 }
+
+function frameOnlyOrigin(frame: SiteFrameMarker | undefined): SiteSessionOrigin | null {
+  if (!frame?.marker) return null;
+  const frameId = frame.frameId && FRAME_ID.test(frame.frameId) ? frame.frameId : undefined;
+  return {
+    siteId: null,
+    title: "",
+    frame: frame.marker === SITE_PREVIEW_FRAME ? "preview" : "inline",
+    ...(frameId ? { frameId } : {}),
+  };
+}
+
+/**
+ * The strict origin of a request a host marked as coming from a Site frame:
+ * an unverifiable published Site fails the request (400/404) instead of
+ * running it without provenance.
+ */
+export async function resolveSiteRequestOrigin(
+  db: ApiRouteDeps["db"],
+  grant: AccessGrant,
+  frame: SiteFrameHeaders,
+): Promise<SiteSessionOrigin> {
+  const origin = await resolveSiteSessionOrigin(
+    db,
+    grant,
+    frame.siteId ?? undefined,
+    frame.versionId ?? undefined,
+    { marker: frame.marker ?? "1", frameId: frame.frameId },
+  );
+  // Unreachable: a frame always resolves to a published Site or a frame origin.
+  if (!origin) throw new HTTPException(400, { message: "Invalid Site origin" });
+  return origin;
+}
+
+/**
+ * Run a follow-up command (Send or Steer) inside the request's Site scope when
+ * the published Site bridge supplied a valid origin, so its turn records the
+ * `site` surface. Provenance only: a missing or unverifiable origin leaves the
+ * command unscoped instead of rejecting a message that is otherwise valid.
+ * Requests a host marked as Site frames already run inside their validated
+ * origin (apps/api/src/site-frame-guard.ts), which this keeps.
+ */
+export async function withOptionalSiteCommandOrigin<T>(
+  db: ApiRouteDeps["db"],
+  grant: AccessGrant,
+  siteId: string | undefined,
+  versionId: string | undefined,
+  run: () => Promise<T>,
+): Promise<T> {
+  if (currentSiteSessionOrigin()) return await run();
+  if (!siteId && !versionId) return await run();
+  const origin = await resolveSiteSessionOrigin(db, grant, siteId, versionId).catch(() => null);
+  return origin ? await withSiteSessionOrigin(origin, run) : await run();
+}

package/src/site-sql/format.ts

@@ -0,0 +1,134 @@
+import {
+  quoteSiteSqlIdentifier,
+  type SiteDbSchemaEntry,
+  type SiteSqlValue,
+} from "@opengeni/contracts";
+import { siteDataCsvCell } from "../site-data/operations";
+
+/**
+ * Site SQL export and import formats, so a Site's data can always leave
+ * Cloudflare: a SQL dump (schema, then INSERT statements), CSV for one table,
+ * and JSON rows per table. Blobs travel as `{ "$base64": "..." }` in JSON,
+ * X'..' literals in SQL and base64 text in CSV. SQL and JSON keep every value
+ * as stored; CSV turns every value into text (an empty cell is NULL on
+ * import) and blobs into base64.
+ */
+
+export type SiteSqlExportTable = { name: string; columns: string[]; rows: unknown[][] };
+
+/** Rows per INSERT statement of a SQL dump. */
+export const SITE_SQL_INSERT_ROWS = 500;
+/**
+ * Most bytes per INSERT statement of a SQL dump: Durable Object SQLite
+ * refuses statements over 100 KB. A single row past this still gets its own
+ * statement (and needs a JSON import to load back).
+ */
+export const SITE_SQL_INSERT_BYTES = 90_000;
+
+function isBlob(value: unknown): value is { $base64: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { $base64?: unknown }).$base64 === "string"
+  );
+}
+
+/** One value as a SQLite literal. */
+export function siteSqlLiteral(value: unknown): string {
+  if (value === null || value === undefined) return "NULL";
+  if (typeof value === "number") return Number.isFinite(value) ? String(value) : "NULL";
+  if (typeof value === "bigint") return value.toString();
+  if (typeof value === "boolean") return value ? "1" : "0";
+  if (isBlob(value)) return `X'${Buffer.from(value.$base64, "base64").toString("hex")}'`;
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  return `'${text.replaceAll("'", "''")}'`;
+}
+
+/** Schema entries that belong to one table (its own entry, its indexes and triggers), or all. */
+export function siteSqlSchemaEntries(
+  schema: readonly SiteDbSchemaEntry[],
+  table?: string,
+): SiteDbSchemaEntry[] {
+  return table === undefined ? [...schema] : schema.filter((entry) => entry.table === table);
+}
+
+/** The schema statements of a dump, tables first, each ending with a semicolon. */
+export function siteSqlSchemaStatements(schema: readonly SiteDbSchemaEntry[]): string[] {
+  const order = { table: 0, view: 1, index: 2, trigger: 3 } as const;
+  return [...schema]
+    .filter((entry) => entry.sql)
+    .sort((a, b) => order[a.type] - order[b.type])
+    .map((entry) => `${entry.sql!.trim().replace(/;+$/u, "")};`);
+}
+
+/**
+ * INSERT statements for one exported page of a table: up to
+ * SITE_SQL_INSERT_ROWS rows and SITE_SQL_INSERT_BYTES bytes each, one
+ * statement per line.
+ */
+export function siteSqlInsertStatements(table: SiteSqlExportTable): string[] {
+  if (table.rows.length === 0) return [];
+  const columns = table.columns.map(quoteSiteSqlIdentifier).join(", ");
+  const head = `INSERT INTO ${quoteSiteSqlIdentifier(table.name)} (${columns}) VALUES `;
+  const headBytes = Buffer.byteLength(head, "utf8") + 1;
+  const statements: string[] = [];
+  let tuples: string[] = [];
+  let bytes = headBytes;
+  for (const row of table.rows) {
+    const tuple = `(${row.map(siteSqlLiteral).join(", ")})`;
+    const size = Buffer.byteLength(tuple, "utf8") + 2;
+    if (
+      tuples.length > 0 &&
+      (tuples.length >= SITE_SQL_INSERT_ROWS || bytes + size > SITE_SQL_INSERT_BYTES)
+    ) {
+      statements.push(`${head}${tuples.join(", ")};`);
+      tuples = [];
+      bytes = headBytes;
+    }
+    tuples.push(tuple);
+    bytes += size;
+  }
+  if (tuples.length > 0) statements.push(`${head}${tuples.join(", ")};`);
+  return statements;
+}
+
+/** A CSV cell for an exported value (formula-safe, like Site Data exports). */
+export function siteSqlCsvCell(value: unknown): string {
+  if (isBlob(value)) return siteDataCsvCell(value.$base64);
+  return siteDataCsvCell(value);
+}
+
+export function siteSqlCsvLine(values: readonly unknown[]): string {
+  return values.map(siteSqlCsvCell).join(",");
+}
+
+/** Rows as objects keyed by column, for JSON exports. */
+export function siteSqlRowObjects(table: SiteSqlExportTable): Array<Record<string, unknown>> {
+  return table.rows.map((row) =>
+    Object.fromEntries(table.columns.map((column, index) => [column, row[index] ?? null])),
+  );
+}
+
+/**
+ * Rows of a JSON import as column lists and value rows: the columns are every
+ * key any row uses, in first-seen order; a missing key is NULL.
+ */
+export function siteSqlImportRows(rows: ReadonlyArray<Record<string, SiteSqlValue>>): {
+  columns: string[];
+  values: SiteSqlValue[][];
+} {
+  const columns: string[] = [];
+  const seen = new Set<string>();
+  for (const row of rows)
+    for (const key of Object.keys(row))
+      if (!seen.has(key)) {
+        seen.add(key);
+        columns.push(key);
+      }
+  return {
+    columns,
+    values: rows.map((row) =>
+      columns.map((column) => (Object.hasOwn(row, column) ? (row[column] ?? null) : null)),
+    ),
+  };
+}

package/src/site-sql/gateway.ts

@@ -0,0 +1,168 @@
+import { createHash, createHmac } from "node:crypto";
+import {
+  SITE_GATEWAY_SIGNATURE_HEADER,
+  SITE_GATEWAY_SIGNATURE_VERSION,
+  SITE_GATEWAY_TIMESTAMP_HEADER,
+  siteDbInternalPath,
+  siteGatewayCanonicalString,
+  type SiteDbErrorBody,
+  type SiteDbOperation,
+} from "@opengeni/contracts";
+import type { Settings } from "@opengeni/config";
+
+/**
+ * The API's client for a Site's Durable Object, through the Site gateway's
+ * internal route (`POST <origin>/_og/internal/site-db/<siteId>/<operation>`).
+ * Requests are signed like gateway -> API requests, in the other direction:
+ * HMAC-SHA256 with the shared gateway secret over `siteGatewayCanonicalString`
+ * (the internal path, the gateway's host, the body digest and the time; no
+ * viewer fields). Every request names a fresh id the Durable Object refuses
+ * to see twice. Nothing here decides who may do what: the service does that
+ * before calling.
+ */
+
+export type SiteSqlGatewayConfig = {
+  origin: string;
+  secret: string;
+  timeoutMs: number;
+};
+
+export type SiteSqlGatewaySettings = Pick<
+  Settings,
+  | "sitesCloudflareStorageEnabled"
+  | "sitesGatewayInternalOrigin"
+  | "sitesGatewaySecret"
+  | "sitesSqlTimeoutMs"
+>;
+
+/**
+ * The gateway to call, or null when no gateway origin and secret are
+ * configured. This alone lets the API reach Durable Objects that already
+ * exist (export, inspect, dropping data); offering Site SQL also needs the
+ * flag (siteSqlOffered).
+ */
+export function siteSqlGatewayConfig(
+  settings: SiteSqlGatewaySettings,
+): SiteSqlGatewayConfig | null {
+  if (!settings.sitesGatewayInternalOrigin || !settings.sitesGatewaySecret) return null;
+  return {
+    origin: new URL(settings.sitesGatewayInternalOrigin).origin,
+    secret: settings.sitesGatewaySecret,
+    timeoutMs: settings.sitesSqlTimeoutMs,
+  };
+}
+
+/**
+ * Whether this deployment offers Site SQL: the flag is on and the gateway is
+ * configured. Turning it on, migrating, rebuilding, importing and running
+ * SQL need this; export, inspect and dropping a database only need the
+ * gateway.
+ */
+export function siteSqlOffered(settings: SiteSqlGatewaySettings): boolean {
+  return settings.sitesCloudflareStorageEnabled && siteSqlGatewayConfig(settings) !== null;
+}
+
+/** A refusal or failure from the gateway or the Durable Object. */
+export class SiteDbCallError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+    /** True when the operation may have run (a timeout or lost response). */
+    readonly outcomeUnknown = false,
+  ) {
+    super(message);
+    this.name = "SiteDbCallError";
+  }
+}
+
+export type SiteDbFetch = (input: string, init: RequestInit) => Promise<Response>;
+
+/** Sign one internal request. Exported for tests. */
+export function signSiteDbRequest(
+  config: Pick<SiteSqlGatewayConfig, "origin" | "secret">,
+  siteId: string,
+  operation: SiteDbOperation,
+  body: string,
+  nowSeconds = Math.floor(Date.now() / 1000),
+): { url: string; headers: Record<string, string> } {
+  const path = siteDbInternalPath(siteId, operation);
+  const url = new URL(path, config.origin);
+  const canonical = siteGatewayCanonicalString({
+    method: "POST",
+    host: url.host,
+    pathWithQuery: url.pathname,
+    timestamp: nowSeconds,
+    bodySha256: createHash("sha256").update(body).digest("hex"),
+    session: "",
+    visitor: "",
+    clientIp: "",
+    human: "",
+  });
+  const mac = createHmac("sha256", config.secret).update(canonical).digest("base64url");
+  return {
+    url: url.toString(),
+    headers: {
+      "content-type": "application/json",
+      [SITE_GATEWAY_TIMESTAMP_HEADER]: String(nowSeconds),
+      [SITE_GATEWAY_SIGNATURE_HEADER]: `${SITE_GATEWAY_SIGNATURE_VERSION}=${mac}`,
+    },
+  };
+}
+
+/** Read-only operations: a lost response cannot have changed anything. */
+const READ_ONLY: ReadonlySet<SiteDbOperation> = new Set(["inspect", "export"]);
+
+/** Call one Durable Object operation and return its JSON. */
+export async function callSiteDb<T>(
+  config: SiteSqlGatewayConfig,
+  siteId: string,
+  operation: SiteDbOperation,
+  payload: Record<string, unknown>,
+  fetchImpl: SiteDbFetch = fetch,
+): Promise<T> {
+  const body = JSON.stringify({ requestId: crypto.randomUUID(), ...payload });
+  const signed = signSiteDbRequest(config, siteId, operation, body);
+  let response: Response;
+  try {
+    response = await fetchImpl(signed.url, {
+      method: "POST",
+      headers: signed.headers,
+      body,
+      redirect: "manual",
+      signal: AbortSignal.timeout(config.timeoutMs),
+    });
+  } catch (error) {
+    const timedOut = error instanceof DOMException && error.name === "TimeoutError";
+    throw new SiteDbCallError(
+      503,
+      "unavailable",
+      timedOut
+        ? "The Site database did not answer in time"
+        : "The Site database is temporarily unavailable",
+      !READ_ONLY.has(operation),
+    );
+  }
+  const text = await response.text();
+  let parsed: unknown = null;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch {
+    parsed = null;
+  }
+  if (response.ok && parsed !== null && typeof parsed === "object") return parsed as T;
+  const error = (parsed as Partial<SiteDbErrorBody> | null)?.error;
+  const code = typeof error?.code === "string" ? error.code : "unavailable";
+  const message =
+    typeof error?.message === "string" ? error.message : "The Site database request failed";
+  // The gateway's own refusals (signature, missing binding) are configuration
+  // problems, not the caller's: report them as unavailable.
+  if (response.status === 401 || response.status === 404 || response.status >= 500)
+    throw new SiteDbCallError(
+      503,
+      "unavailable",
+      response.status >= 500 ? message : "Site SQL is not reachable on this deployment",
+      response.status >= 500 && !READ_ONLY.has(operation),
+    );
+  throw new SiteDbCallError(response.status, code, message);
+}