tgo-wiki 0.1.0

package/packages/core/src/web/web-ingestion-service.ts

@@ -0,0 +1,335 @@
+import { createHash, randomBytes } from "node:crypto";
+import { link, lstat, mkdir, readFile, realpath, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { loadConfig } from "../config/config-loader.js";
+import { resolveWorkspacePaths, type WorkspacePaths } from "../config/workspace-resolver.js";
+import { WikiError, toWikiError } from "../errors.js";
+import { err, ok, type Result } from "../result.js";
+import { SessionStore } from "../session/session-store.js";
+import type { SessionMetadata } from "../session/session-types.js";
+import { assertValidSourceId } from "../sources/source-id.js";
+import type { WebSourceMetadata } from "../sources/source-types.js";
+import { assertNoExistingSourceForCreate, publishSource } from "../sources/source-writer.js";
+import { generateWebSourceId, type WebSourceIdGenerator } from "./web-id.js";
+import { htmlToRawMarkdown } from "./html-to-markdown.js";
+import { webHtmlBlobPath } from "./web-paths.js";
+import { staticWebFetch } from "./static-web-fetcher.js";
+import type { StaticWebFetchResult, WebFetchInput, WebFetchResult } from "./web-types.js";
+
+export type WebFetcher = (url: string) => Promise<StaticWebFetchResult>;
+
+export type WebIngestionServiceOptions = {
+  clock?: () => Date;
+  fetcher?: WebFetcher;
+};
+
+const fetcherName = "static-fetch";
+const fetcherVersion = "1.0.0";
+
+export class WebIngestionService {
+  private readonly paths: WorkspacePaths;
+  private readonly sessions: SessionStore;
+  private readonly clock: () => Date;
+  private readonly fetcher?: WebFetcher;
+
+  constructor(
+    workspaceRoot: string,
+    private readonly idGenerator: WebSourceIdGenerator = generateWebSourceId,
+    options: WebIngestionServiceOptions = {}
+  ) {
+    this.paths = resolveWorkspacePaths(workspaceRoot);
+    this.sessions = new SessionStore(this.paths);
+    this.clock = options.clock ?? (() => new Date());
+    this.fetcher = options.fetcher;
+  }
+
+  async fetch(input: WebFetchInput): Promise<Result<WebFetchResult>> {
+    try {
+      const session = await this.sessions.read(input.sessionId);
+      if (session.status !== "open") {
+        throw new WikiError("validation_failed", `Session is not open: ${input.sessionId}`, {
+          status: session.status
+        });
+      }
+
+      const worktreeRoot = await this.sessionWorktreeRoot(session);
+      const config = await loadConfig(this.paths);
+      const fetchResult = this.fetcher ? await this.fetcher(input.url) : await staticWebFetch(input.url, config.web);
+      const fetchedAtDate = this.clock();
+      const fetchedAt = fetchedAtDate.toISOString();
+      const sourceId = this.idGenerator({
+        finalUrl: fetchResult.finalUrl,
+        htmlBlobSha256: fetchResult.htmlBlobSha256,
+        fetchedAt: fetchedAtDate
+      });
+      assertValidSourceId(sourceId);
+      await assertNoExistingSourceForCreate(worktreeRoot, sourceId);
+      await this.writeHtmlBlob(fetchResult);
+
+      const converted = htmlToRawMarkdown({
+        html: fetchResult.htmlText,
+        requestedUrl: input.url,
+        finalUrl: fetchResult.finalUrl,
+        fetchedAt,
+        fetcherName
+      });
+
+      const rawMarkdownPath = sourceRelativePath(sourceId, "raw.md");
+      const metadataPath = sourceRelativePath(sourceId, "metadata.json");
+      const metadata: WebSourceMetadata = {
+        documentId: sourceId,
+        version: 1,
+        sourceType: "web",
+        url: input.url,
+        finalUrl: fetchResult.finalUrl,
+        title: converted.title,
+        contentType: fetchResult.contentType,
+        statusCode: fetchResult.statusCode,
+        htmlBlobSha256: fetchResult.htmlBlobSha256,
+        rawMarkdownPath,
+        fetcher: {
+          name: fetcherName,
+          version: fetcherVersion
+        },
+        fetchMetadata: {
+          htmlBytes: fetchResult.htmlBytes,
+          markdownBytes: Buffer.byteLength(converted.markdown, "utf8")
+        },
+        createdAt: fetchedAt,
+        updatedAt: fetchedAt,
+        createdBy: input.createdBy,
+        status: "fetched"
+      };
+
+      await publishSource({
+        worktreeRoot,
+        sourceId,
+        markdown: converted.markdown,
+        metadataJson: `${JSON.stringify(metadata, null, 2)}\n`,
+        mode: "create"
+      });
+
+      return ok({
+        source_id: sourceId,
+        version: metadata.version,
+        raw_markdown_path: rawMarkdownPath,
+        metadata_path: metadataPath,
+        html_blob_sha256: fetchResult.htmlBlobSha256,
+        status: "fetched",
+        title: converted.title,
+        warnings: []
+      });
+    } catch (error) {
+      return err(toWikiError(error, "validation_failed"));
+    }
+  }
+
+  private async writeHtmlBlob(fetchResult: StaticWebFetchResult): Promise<void> {
+    assertValidSha256(fetchResult.htmlBlobSha256);
+    const content = Buffer.from(fetchResult.htmlContent);
+    assertContentMatchesSha256(content, fetchResult.htmlBlobSha256);
+    await this.ensureWebBlobStoreRoot();
+    const blobPath = webHtmlBlobPath(this.paths, fetchResult.htmlBlobSha256);
+
+    try {
+      await writeAtomicallyNoOverwrite(this.paths.webBlobsPath, blobPath, content);
+    } catch (error) {
+      if (!isFileExists(error)) {
+        throw error;
+      }
+
+      await assertExistingBlobMatches(blobPath, fetchResult.htmlBlobSha256);
+    }
+  }
+
+  private async ensureWebBlobStoreRoot(): Promise<void> {
+    const realWorkspaceRoot = await realpath(this.paths.workspaceRoot);
+    await ensureDirectoryForWrite(this.paths.statePath, realWorkspaceRoot, "State directory");
+    const realStateRoot = await realpath(this.paths.statePath);
+
+    await ensureDirectoryForWrite(this.paths.webStatePath, realStateRoot, "Web state directory");
+    const realWebStateRoot = await realpath(this.paths.webStatePath);
+
+    const webBlobsParent = path.dirname(this.paths.webBlobsPath);
+    await ensureDirectoryForWrite(webBlobsParent, realWebStateRoot, "Web blobs directory");
+    const realWebBlobsParent = await realpath(webBlobsParent);
+
+    await ensureDirectoryForWrite(this.paths.webBlobsPath, realWebBlobsParent, "Web blob store");
+    const realWebBlobsRoot = await realpath(this.paths.webBlobsPath);
+    ensureInsideRealRoot(realWebStateRoot, realWebBlobsRoot, this.paths.webBlobsPath, "Web blob store escapes web state boundary");
+  }
+
+  private async sessionWorktreeRoot(metadata: SessionMetadata): Promise<string> {
+    const absolute = path.resolve(this.paths.workspaceRoot, metadata.worktree);
+    const sessionsRoot = path.resolve(this.paths.sessionsWorktreePath);
+
+    if (!absolute.startsWith(`${sessionsRoot}${path.sep}`)) {
+      throw new WikiError("session_metadata_invalid", `Session worktree escapes sessions root: ${metadata.sessionId}`);
+    }
+
+    const realWorkspaceRoot = await realpath(this.paths.workspaceRoot);
+    await ensureDirectoryForWrite(this.paths.worktreesPath, realWorkspaceRoot, "Worktrees boundary");
+    const realWorktreesRoot = await realpath(this.paths.worktreesPath);
+
+    await ensureDirectoryForWrite(this.paths.sessionsWorktreePath, realWorktreesRoot, "Sessions worktree boundary");
+    const realSessionsRoot = await realpath(this.paths.sessionsWorktreePath);
+
+    await ensureDescendantDirectoryForWrite(this.paths.sessionsWorktreePath, absolute, realSessionsRoot, "Session worktree root");
+    const realWorktreeRoot = await realpath(absolute);
+    ensureStrictDescendant(realWorktreesRoot, realSessionsRoot, this.paths.sessionsWorktreePath, "Sessions worktree boundary escapes worktrees boundary");
+    ensureStrictDescendant(realSessionsRoot, realWorktreeRoot, absolute, "Session worktree root escapes sessions boundary");
+    return realWorktreeRoot;
+  }
+}
+
+function sourceRelativePath(sourceId: string, fileName: "metadata.json" | "raw.md"): string {
+  return `sources/${sourceId}/${fileName}`;
+}
+
+async function ensureDescendantDirectoryForWrite(root: string, target: string, realBoundary: string, label: string): Promise<void> {
+  const relativePath = path.relative(root, target);
+  if (relativePath.length === 0 || relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    throw new WikiError("invalid_path", `${label} escapes boundary: ${target}`);
+  }
+
+  const segments = relativePath.split(path.sep).filter(segment => segment.length > 0 && segment !== ".");
+  let current = root;
+
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    await ensureDirectoryForWrite(current, realBoundary, label);
+  }
+}
+
+async function ensureDirectoryForWrite(directoryPath: string, realBoundary: string, label: string): Promise<void> {
+  try {
+    const stat = await lstat(directoryPath);
+
+    if (stat.isSymbolicLink()) {
+      throw new WikiError("invalid_path", `${label} is a symlink: ${directoryPath}`);
+    }
+
+    if (!stat.isDirectory()) {
+      throw new WikiError("invalid_path", `${label} is not a directory: ${directoryPath}`);
+    }
+  } catch (error) {
+    if (!isEnoent(error)) {
+      throw error;
+    }
+
+    await mkdir(directoryPath);
+    await ensureDirectoryNotSymlink(directoryPath, label);
+  }
+
+  const realDirectory = await realpath(directoryPath);
+  ensureInsideRealRoot(realBoundary, realDirectory, directoryPath, `${label} escapes boundary`);
+}
+
+async function ensureDirectoryNotSymlink(directoryPath: string, label: string): Promise<void> {
+  const stat = await lstat(directoryPath);
+
+  if (stat.isSymbolicLink()) {
+    throw new WikiError("invalid_path", `${label} is a symlink: ${directoryPath}`);
+  }
+
+  if (!stat.isDirectory()) {
+    throw new WikiError("invalid_path", `${label} is not a directory: ${directoryPath}`);
+  }
+}
+
+function ensureStrictDescendant(realRoot: string, target: string, originalPath: string, message: string): void {
+  if (!target.startsWith(`${realRoot}${path.sep}`)) {
+    throw new WikiError("invalid_path", `${message}: ${originalPath}`);
+  }
+}
+
+function ensureInsideRealRoot(realRoot: string, target: string, originalPath: string, message: string): void {
+  if (!target.startsWith(`${realRoot}${path.sep}`) && target !== realRoot) {
+    throw new WikiError("invalid_path", `${message}: ${originalPath}`);
+  }
+}
+
+function assertValidSha256(value: string): void {
+  if (!/^[0-9a-f]{64}$/.test(value)) {
+    throw new WikiError("validation_failed", `Invalid sha256: ${value}`);
+  }
+}
+
+function assertContentMatchesSha256(content: Uint8Array, expected: string): void {
+  const actual = createHash("sha256").update(content).digest("hex");
+
+  if (actual !== expected) {
+    throw new WikiError("validation_failed", `Blob content does not match sha256: ${expected}`, {
+      expected,
+      actual
+    });
+  }
+}
+
+async function writeAtomicallyNoOverwrite(directory: string, finalPath: string, content: Buffer): Promise<void> {
+  const tempPath = await writeUniqueTempFile(directory, path.basename(finalPath), content);
+
+  try {
+    await link(tempPath, finalPath);
+  } finally {
+    await unlinkIfExists(tempPath);
+  }
+}
+
+async function writeUniqueTempFile(directory: string, finalBaseName: string, content: Buffer): Promise<string> {
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    const tempPath = path.join(directory, `.${finalBaseName}.${randomBytes(8).toString("hex")}.tmp`);
+
+    try {
+      await writeFile(tempPath, content, { flag: "wx" });
+      return tempPath;
+    } catch (error) {
+      if (isFileExists(error)) {
+        continue;
+      }
+
+      throw error;
+    }
+  }
+
+  throw new WikiError("validation_failed", `Could not create unique temp file for: ${finalBaseName}`);
+}
+
+async function assertExistingBlobMatches(blobPath: string, blobSha256: string): Promise<void> {
+  const stat = await lstat(blobPath);
+  if (stat.isSymbolicLink()) {
+    throw new WikiError("invalid_path", `Existing web blob is a symlink: ${blobPath}`);
+  }
+
+  if (!stat.isFile()) {
+    throw new WikiError("invalid_path", `Existing web blob is not a file: ${blobPath}`);
+  }
+
+  const existing = await readFile(blobPath);
+  const actual = createHash("sha256").update(existing).digest("hex");
+
+  if (actual !== blobSha256) {
+    throw new WikiError("validation_failed", `Existing blob content does not match sha256 file name: ${blobSha256}`, {
+      expected: blobSha256,
+      actual
+    });
+  }
+}
+
+async function unlinkIfExists(filePath: string): Promise<void> {
+  try {
+    await unlink(filePath);
+  } catch (error) {
+    if (!isEnoent(error)) {
+      throw error;
+    }
+  }
+}
+
+function isEnoent(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+
+function isFileExists(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "EEXIST");
+}

package/packages/core/src/web/web-paths.ts

@@ -0,0 +1,6 @@
+import path from "node:path";
+import type { WorkspacePaths } from "../config/workspace-resolver.js";
+
+export function webHtmlBlobPath(paths: WorkspacePaths, sha256: string): string {
+  return path.join(paths.webBlobsPath, sha256);
+}

package/packages/core/src/web/web-types.ts

@@ -0,0 +1,33 @@
+export type WebFetchConfig = {
+  requestTimeoutMs: number;
+  maxResponseBytes: number;
+  allowedPrivateHosts?: string[];
+};
+
+export type StaticWebFetchResult = {
+  requestedUrl: string;
+  finalUrl: string;
+  contentType: string;
+  statusCode: number;
+  htmlBytes: number;
+  htmlContent: Uint8Array;
+  htmlText: string;
+  htmlBlobSha256: string;
+};
+
+export type WebFetchInput = {
+  sessionId: string;
+  url: string;
+  createdBy?: string;
+};
+
+export type WebFetchResult = {
+  source_id: string;
+  version: number;
+  raw_markdown_path: string;
+  metadata_path: string;
+  html_blob_sha256: string;
+  status: "fetched";
+  title?: string;
+  warnings: string[];
+};

package/packages/server/src/cli.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+import { WorkspaceService, type Role } from "../../core/src/index.js";
+
+function getArg(name: string): string | undefined {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+async function main(): Promise<void> {
+  const command = process.argv[2];
+  const workspace = getArg("--workspace");
+
+  if (!workspace) {
+    console.error("Missing required --workspace <path>");
+    process.exit(1);
+  }
+
+  if (command === "init") {
+    const result = await new WorkspaceService(workspace).init();
+
+    if (!result.ok) {
+      console.error(JSON.stringify({ error: result.error }, null, 2));
+      process.exit(1);
+    }
+
+    console.log(JSON.stringify(result.value, null, 2));
+    return;
+  }
+
+  if (command === "status") {
+    const result = await new WorkspaceService(workspace).status();
+
+    if (!result.ok) {
+      console.error(JSON.stringify({ error: result.error }, null, 2));
+      process.exit(1);
+    }
+
+    console.log(JSON.stringify(result.value, null, 2));
+    return;
+  }
+
+  if (command === "mcp") {
+    const role = (getArg("--role") ?? "reader") as Role;
+    const { startStdioMcpServer } = await import("./mcp-server.js");
+    await startStdioMcpServer({ workspaceRoot: workspace, role });
+    return;
+  }
+
+  console.error("Usage: tgo-wiki <init|status|mcp> --workspace <path> [--role <role>]");
+  process.exit(1);
+}
+
+main().catch(error => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/packages/server/src/context.ts

@@ -0,0 +1,7 @@
+import type { Role } from "../../core/src/index.js";
+
+export type ServerContext = {
+  workspaceRoot: string;
+  role: Role;
+  agentId?: string;
+};

package/packages/server/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./context.js";
+export * from "./mcp-server.js";

package/packages/server/src/mcp-server.ts

@@ -0,0 +1,111 @@
+import { McpServer, StdioServerTransport } from "@modelcontextprotocol/server";
+import type { ServerContext } from "./context.js";
+import { documentParseSchema, documentUploadSchema } from "./schemas/documents.js";
+import { vfsExecSchema, wikiChannelStatusSchema, wikiReadSchema } from "./schemas/read.js";
+import {
+  wikiSessionCommitSchema,
+  wikiSessionDiffSchema,
+  wikiSessionPatchSchema,
+  wikiSessionStartSchema,
+  wikiSessionValidateSchema
+} from "./schemas/session.js";
+import { sourceListSchema, sourceReadSchema } from "./schemas/sources.js";
+import { webFetchSchema } from "./schemas/web.js";
+import { callDocumentParse, callDocumentUpload } from "./tools/document-tools.js";
+import { callVfsExec, callWikiChannelStatus, callWikiRead } from "./tools/read-tools.js";
+import { callWikiPublishSession, wikiPublishSessionSchema } from "./tools/publish-tools.js";
+import { callSourceList, callSourceRead } from "./tools/source-tools.js";
+import { callWebFetch } from "./tools/web-tools.js";
+import {
+  callWikiSessionCommit,
+  callWikiSessionDiff,
+  callWikiSessionPatch,
+  callWikiSessionStart,
+  callWikiSessionValidate
+} from "./tools/session-tools.js";
+
+const instructions =
+  "Read stable wiki content before editing. All writes must happen in an isolated session. Uploaded documents become raw sources first. Read sources, create wiki pages in sessions, validate, commit, and publish with publisher role.";
+
+export function createMcpServer(ctx: ServerContext): McpServer {
+  const server = new McpServer({ name: "tgo-wiki", version: "0.0.0" }, { instructions });
+
+  server.registerTool(
+    "vfs_exec",
+    { description: "Run a read-only VFS command against stable wiki content.", inputSchema: vfsExecSchema },
+    input => callVfsExec(ctx, input)
+  );
+  server.registerTool(
+    "wiki_read",
+    { description: "Read a wiki Markdown page.", inputSchema: wikiReadSchema },
+    input => callWikiRead(ctx, input)
+  );
+  server.registerTool(
+    "wiki_channel_status",
+    { description: "Read stable channel status.", inputSchema: wikiChannelStatusSchema },
+    input => callWikiChannelStatus(ctx, input)
+  );
+  server.registerTool(
+    "document_upload",
+    { description: "Upload a document into an open session as a pending raw source.", inputSchema: documentUploadSchema },
+    input => callDocumentUpload(ctx, input)
+  );
+  server.registerTool(
+    "document_parse",
+    { description: "Parse an uploaded document into session source files.", inputSchema: documentParseSchema },
+    input => callDocumentParse(ctx, input)
+  );
+  server.registerTool(
+    "web_fetch",
+    { description: "Fetch one static web page into an open session as a raw source.", inputSchema: webFetchSchema },
+    input => callWebFetch(ctx, input)
+  );
+  server.registerTool(
+    "source_list",
+    { description: "List parsed document sources from stable or a session ref.", inputSchema: sourceListSchema },
+    input => callSourceList(ctx, input)
+  );
+  server.registerTool(
+    "source_read",
+    { description: "Read parsed source metadata and raw Markdown from stable or a session ref.", inputSchema: sourceReadSchema },
+    input => callSourceRead(ctx, input)
+  );
+  server.registerTool(
+    "wiki_session_start",
+    { description: "Create an isolated wiki edit session.", inputSchema: wikiSessionStartSchema },
+    input => callWikiSessionStart(ctx, input)
+  );
+  server.registerTool(
+    "wiki_session_patch",
+    { description: "Replace a Markdown page in a session worktree.", inputSchema: wikiSessionPatchSchema },
+    input => callWikiSessionPatch(ctx, input)
+  );
+  server.registerTool(
+    "wiki_session_validate",
+    { description: "Validate changed Markdown pages in a session.", inputSchema: wikiSessionValidateSchema },
+    input => callWikiSessionValidate(ctx, input)
+  );
+  server.registerTool(
+    "wiki_session_diff",
+    { description: "Show committed and working diff for a session.", inputSchema: wikiSessionDiffSchema },
+    input => callWikiSessionDiff(ctx, input)
+  );
+  server.registerTool(
+    "wiki_session_commit",
+    { description: "Commit validated session changes.", inputSchema: wikiSessionCommitSchema },
+    input => callWikiSessionCommit(ctx, input)
+  );
+  server.registerTool(
+    "wiki_publish_session",
+    { description: "Publish a committed session to the stable channel using ff-only merge.", inputSchema: wikiPublishSessionSchema },
+    input => callWikiPublishSession(ctx, input)
+  );
+
+  return server;
+}
+
+export async function startStdioMcpServer(ctx: ServerContext): Promise<void> {
+  const server = createMcpServer(ctx);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/packages/server/src/schemas/documents.ts

@@ -0,0 +1,17 @@
+import * as z from "zod/v4";
+
+const safeIdSchema = z.string().regex(/^[a-zA-Z0-9._-]+$/);
+
+export const documentUploadSchema = z.object({
+  session_id: safeIdSchema,
+  file_name: z.string().min(1),
+  mime_type: z.string().min(1),
+  content_base64: z.string().min(1)
+});
+
+export const documentParseSchema = z.object({
+  session_id: safeIdSchema,
+  document_id: safeIdSchema,
+  parser: z.string().min(1).optional(),
+  reparse: z.boolean().optional()
+});

package/packages/server/src/schemas/read.ts

@@ -0,0 +1,16 @@
+import * as z from "zod/v4";
+
+export const vfsExecSchema = z.object({
+  command: z.string().min(1),
+  ref: z.string().optional()
+});
+
+export const wikiReadSchema = z.object({
+  path: z.string().min(1),
+  ref: z.string().optional(),
+  include_frontmatter: z.boolean().optional()
+});
+
+export const wikiChannelStatusSchema = z.object({
+  channel: z.literal("stable").optional()
+});

package/packages/server/src/schemas/session.ts

@@ -0,0 +1,31 @@
+import * as z from "zod/v4";
+
+export const wikiSessionStartSchema = z.object({
+  base_ref: z.string().optional(),
+  purpose: z.string().optional(),
+  agent_id: z.string().optional()
+});
+
+export const wikiSessionPatchSchema = z
+  .object({
+    session_id: z.string().regex(/^[a-zA-Z0-9._-]+$/),
+    path: z.string().min(1),
+    content: z.string().min(1),
+    reason: z.string().optional()
+  })
+  .strict();
+
+export const wikiSessionValidateSchema = z.object({
+  session_id: z.string().regex(/^[a-zA-Z0-9._-]+$/),
+  paths: z.array(z.string()).optional()
+});
+
+export const wikiSessionDiffSchema = z.object({
+  session_id: z.string().regex(/^[a-zA-Z0-9._-]+$/),
+  paths: z.array(z.string()).optional()
+});
+
+export const wikiSessionCommitSchema = z.object({
+  session_id: z.string().regex(/^[a-zA-Z0-9._-]+$/),
+  message: z.string().min(1)
+});

package/packages/server/src/schemas/sources.ts

@@ -0,0 +1,12 @@
+import * as z from "zod/v4";
+
+const safeIdSchema = z.string().regex(/^[a-zA-Z0-9._-]+$/);
+
+export const sourceListSchema = z.object({
+  ref: z.string().min(1).optional()
+});
+
+export const sourceReadSchema = z.object({
+  document_id: safeIdSchema,
+  ref: z.string().min(1).optional()
+});

package/packages/server/src/schemas/web.ts

@@ -0,0 +1,23 @@
+import * as z from "zod/v4";
+
+const safeIdSchema = z.string().regex(/^[a-zA-Z0-9._-]+$/);
+
+export const webFetchSchema = z.object({
+  session_id: safeIdSchema,
+  url: z.string().url().superRefine((value, ctx) => {
+    let protocol: string;
+
+    try {
+      protocol = new URL(value).protocol;
+    } catch {
+      return;
+    }
+
+    if (protocol !== "http:" && protocol !== "https:") {
+      ctx.addIssue({
+        code: "custom",
+        message: "URL must use http or https"
+      });
+    }
+  })
+});