@oh-my-pi/pi-coding-agent 15.11.8 → 15.12.0

package/src/export/share.ts

@@ -0,0 +1,268 @@
+/**
+ * Session sharing.
+ *
+ * The session JSON is gzipped and sealed with a fresh AES-256-GCM key
+ * (`[12B IV][ciphertext+tag]`, same layout as collab frames), then pushed to
+ * one of two stores:
+ *
+ *   1. A secret GitHub gist (preferred — free, durable, no relay storage)
+ *      holding base64 of the sealed blob, when an authenticated `gh` exists.
+ *   2. The share server (`POST <serverUrl>` → `{"id":"…"}`), capped at 1 MB;
+ *      oversized sessions are truncated (images first, then long strings,
+ *      then oldest entries) until the sealed blob fits.
+ *
+ * Either way the link is `<serverUrl>/<id>#<base64url key>`. The viewer page
+ * served there fetches the blob (gist ids are hex; server ids never are),
+ * decrypts with the fragment key — which never leaves the browser — and
+ * renders the same template as `/export`.
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { AgentState } from "@oh-my-pi/pi-agent-core";
+import { $which, logger } from "@oh-my-pi/pi-utils";
+import { DEFAULT_SHARE_URL } from "@oh-my-pi/pi-wire";
+import { $ } from "bun";
+import type { SecretObfuscator } from "../secrets/obfuscator";
+import type { SessionManager } from "../session/session-manager";
+import { buildSessionData, type SessionData } from "./html";
+
+export { DEFAULT_SHARE_URL };
+
+/** Hard cap for blobs accepted by the share server (mirrors relay shareMaxBytes). */
+export const SERVER_MAX_SEALED_BYTES = 1_000_000;
+/** Gist raw fetches cap at 10 MB; keep base64 (×4/3) comfortably under it. */
+const GIST_MAX_SEALED_BYTES = 5_000_000;
+
+const IV_LENGTH = 12;
+const SHARE_KEY_BYTES = 32;
+/** The viewer picks the gist file by this suffix. */
+const GIST_FILENAME = "session.ompshare.txt";
+/** Gist ids are hex; the relay never issues pure-hex ids, so the viewer can route on shape. */
+const GIST_ID_RE = /^[0-9a-f]{20,64}$/;
+
+/** Progressively harsher per-string caps applied when the sealed blob is over budget. */
+const TEXT_CAPS = [32_768, 8_192, 2_048, 512];
+/** 1×1 transparent GIF; stands in for stripped data-URL images so <img> tags stay valid. */
+const BLANK_IMAGE_DATA_URL = "data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==";
+const IMAGE_OMITTED_TEXT = "[image omitted from share]";
+
+export interface ShareSessionOptions {
+	/** Share server/viewer base URL; defaults to {@link DEFAULT_SHARE_URL}. */
+	serverUrl?: string;
+	/** Agent state for system prompt + tool descriptions in the snapshot. */
+	state?: AgentState;
+	/**
+	 * Redacts the snapshot before sealing: deep-walks every string (entries,
+	 * header, system prompt, tool descriptions) through the obfuscator, so
+	 * secrets that landed in persisted entries (tool outputs reading .env,
+	 * etc.) never leave the machine. Pass undefined to skip.
+	 */
+	obfuscator?: SecretObfuscator;
+}
+
+export interface ShareSessionResult {
+	/** Viewer link: `<serverUrl>/<id>#<key>`. */
+	url: string;
+	method: "gist" | "server";
+	/** Underlying gist URL (gist method only). */
+	gistUrl?: string;
+	/** True when content was trimmed to fit the upload budget. */
+	truncated: boolean;
+	sealedBytes: number;
+}
+
+/** Build the snapshot that gets sealed and uploaded, redacted when an obfuscator is provided. */
+export function buildShareSnapshot(sm: SessionManager, options?: ShareSessionOptions): SessionData {
+	const data = buildSessionData(sm, options?.state);
+	return options?.obfuscator?.hasSecrets() ? options.obfuscator.obfuscateObject(data) : data;
+}
+
+/** Share the session; tries a secret gist first, then the share server. */
+export async function shareSession(sm: SessionManager, options?: ShareSessionOptions): Promise<ShareSessionResult> {
+	const data = buildShareSnapshot(sm, options);
+	const keyBytes = new Uint8Array(SHARE_KEY_BYTES);
+	crypto.getRandomValues(keyBytes);
+	const key = await crypto.subtle.importKey("raw", keyBytes, "AES-GCM", false, ["encrypt"]);
+	const keyText = Buffer.from(keyBytes).toString("base64url");
+	const base = normalizeShareServerUrl(options?.serverUrl);
+
+	const forGist = await sealToFit(key, data, GIST_MAX_SEALED_BYTES);
+	const gist = await tryCreateGist(forGist.sealed);
+	if (gist) {
+		return {
+			url: `${base}/${gist.id}#${keyText}`,
+			method: "gist",
+			gistUrl: gist.url,
+			truncated: forGist.truncated,
+			sealedBytes: forGist.sealed.byteLength,
+		};
+	}
+
+	const forServer =
+		forGist.sealed.byteLength <= SERVER_MAX_SEALED_BYTES
+			? forGist
+			: await sealToFit(key, data, SERVER_MAX_SEALED_BYTES);
+	const id = await uploadToServer(forServer.sealed, base);
+	return {
+		url: `${base}/${id}#${keyText}`,
+		method: "server",
+		truncated: forServer.truncated,
+		sealedBytes: forServer.sealed.byteLength,
+	};
+}
+
+/** Strip trailing slashes so `<base>/<id>` composes cleanly. */
+export function normalizeShareServerUrl(serverUrl?: string): string {
+	const base = (serverUrl ?? DEFAULT_SHARE_URL).trim().replace(/\/+$/, "");
+	return base || DEFAULT_SHARE_URL;
+}
+
+interface SealedSession {
+	sealed: Uint8Array<ArrayBuffer>;
+	truncated: boolean;
+}
+
+/** Seal `data`, trimming content until the sealed blob fits `maxBytes`. Exported for tests. */
+export async function sealToFit(key: CryptoKey, data: SessionData, maxBytes: number): Promise<SealedSession> {
+	let sealed = await sealSessionData(key, data);
+	if (sealed.byteLength <= maxBytes) return { sealed, truncated: false };
+
+	// Work on a deep copy; the caller may re-fit the original at another budget.
+	const working = structuredClone(data);
+	stripImagePayloads(working);
+	sealed = await sealSessionData(key, working);
+	if (sealed.byteLength <= maxBytes) return { sealed, truncated: true };
+
+	for (const cap of TEXT_CAPS) {
+		capLongStrings(working, cap);
+		sealed = await sealSessionData(key, working);
+		if (sealed.byteLength <= maxBytes) return { sealed, truncated: true };
+	}
+
+	// Last resort: drop oldest entries (orphaned children render as roots).
+	while (working.entries.length > 4) {
+		working.entries = working.entries.slice(Math.ceil(working.entries.length / 2));
+		sealed = await sealSessionData(key, working);
+		if (sealed.byteLength <= maxBytes) return { sealed, truncated: true };
+	}
+
+	throw new Error(`Session too large to share: ${sealed.byteLength} bytes sealed exceeds the ${maxBytes} byte limit`);
+}
+
+/** `[12B IV][AES-256-GCM(gzip(JSON))]` — decrypted and gunzipped by share-loader.js. */
+async function sealSessionData(key: CryptoKey, data: SessionData): Promise<Uint8Array<ArrayBuffer>> {
+	const compressed = Bun.gzipSync(new TextEncoder().encode(JSON.stringify(data)));
+	const iv = new Uint8Array(IV_LENGTH);
+	crypto.getRandomValues(iv);
+	const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, compressed));
+	const out = new Uint8Array(IV_LENGTH + ciphertext.byteLength);
+	out.set(iv, 0);
+	out.set(ciphertext, IV_LENGTH);
+	return out;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/** Replace inline image payloads (image blocks + data: URLs) with tiny placeholders, in place. */
+function stripImagePayloads(value: unknown): void {
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) {
+			const item: unknown = value[i];
+			if (isRecord(item) && item.type === "image" && typeof item.data === "string" && item.data.length > 1024) {
+				value[i] = { type: "text", text: IMAGE_OMITTED_TEXT };
+				continue;
+			}
+			stripImagePayloads(item);
+		}
+		return;
+	}
+	if (!isRecord(value)) return;
+	for (const k in value) {
+		const v = value[k];
+		if (typeof v === "string") {
+			if (v.length > 1024 && v.startsWith("data:")) value[k] = BLANK_IMAGE_DATA_URL;
+			continue;
+		}
+		stripImagePayloads(v);
+	}
+}
+
+/** Truncate every string longer than `cap`, in place. */
+function capLongStrings(value: unknown, cap: number): void {
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) {
+			const item: unknown = value[i];
+			if (typeof item === "string" && item.length > cap) value[i] = `${item.slice(0, cap)}\n…[truncated for share]`;
+			else capLongStrings(item, cap);
+		}
+		return;
+	}
+	if (!isRecord(value)) return;
+	for (const k in value) {
+		const v = value[k];
+		if (typeof v === "string") {
+			if (v.length > cap) value[k] = `${v.slice(0, cap)}\n…[truncated for share]`;
+			continue;
+		}
+		capLongStrings(v, cap);
+	}
+}
+
+/** Create a secret gist holding base64 of the sealed blob; null when `gh` is unusable. */
+async function tryCreateGist(sealed: Uint8Array): Promise<{ id: string; url: string } | null> {
+	if (!$which("gh")) return null;
+	const auth = await $`gh auth status`.quiet().nothrow();
+	if (auth.exitCode !== 0) {
+		logger.debug("share: gh present but not authenticated; falling back to share server");
+		return null;
+	}
+
+	const dir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-share-"));
+	try {
+		const file = path.join(dir, GIST_FILENAME);
+		await Bun.write(file, Buffer.from(sealed).toString("base64"));
+		const result = await $`gh gist create --public=false ${file}`.quiet().nothrow();
+		if (result.exitCode !== 0) {
+			logger.warn("share: gist creation failed; falling back to share server", {
+				stderr: result.stderr.toString("utf-8").trim().slice(0, 500),
+			});
+			return null;
+		}
+		const url = result.text().trim().split("\n").pop()?.trim() ?? "";
+		const id = url.split("/").pop() ?? "";
+		if (!GIST_ID_RE.test(id)) {
+			logger.warn("share: could not parse gist id from gh output", { url });
+			return null;
+		}
+		return { id, url };
+	} finally {
+		await fs.rm(dir, { recursive: true, force: true });
+	}
+}
+
+/** POST the sealed blob to the share server; returns the assigned id. */
+async function uploadToServer(sealed: Uint8Array, base: string): Promise<string> {
+	let res: Response;
+	try {
+		res = await fetch(base, {
+			method: "POST",
+			headers: { "Content-Type": "application/octet-stream" },
+			body: sealed,
+		});
+	} catch (err) {
+		throw new Error(`Share upload to ${base} failed: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!res.ok) {
+		const detail = (await res.text().catch(() => "")).trim().slice(0, 200);
+		throw new Error(`Share upload to ${base} failed: HTTP ${res.status}${detail ? ` (${detail})` : ""}`);
+	}
+	const body = (await res.json().catch(() => null)) as { id?: unknown } | null;
+	const id = body && typeof body.id === "string" ? body.id : "";
+	if (!/^[A-Za-z0-9_-]{10,64}$/.test(id)) {
+		throw new Error(`Share upload to ${base} failed: server returned no usable id`);
+	}
+	return id;
+}