wiki-viewer 1.0.0 → 1.1.0

package/.next/standalone/src/lib/proof/pending.ts

@@ -0,0 +1,97 @@
+/**
+ * In-memory store for pending agent registration requests.
+ *
+ * Cleared on server restart. The registrationId itself acts as the
+ * agent's secret for polling (no separate PIN needed).
+ */
+import { randomBytes } from "node:crypto";
+import type { AgentScope } from "./registry";
+
+export type RegistrationStatus =
+	| "pending"
+	| "approved" // token has been minted but not yet picked up
+	| "consumed" // token was picked up (one-shot)
+	| "denied";
+
+export interface PendingRegistration {
+	registrationId: string;
+	agentId: string;
+	displayName: string;
+	requestedScope: AgentScope;
+	requestedAt: string; // ISO-8601
+	status: RegistrationStatus;
+	/** Plaintext token, present only after approval and before pickup. */
+	tokenPlaintext?: string;
+	/** ISO-8601 timestamp of approval/denial */
+	resolvedAt?: string;
+}
+
+// Module-level singleton (survives Next.js HMR via globalThis)
+const g = globalThis as typeof globalThis & {
+	__wvPendingRegs?: Map<string, PendingRegistration>;
+};
+if (!g.__wvPendingRegs) {
+	g.__wvPendingRegs = new Map();
+}
+const store: Map<string, PendingRegistration> = g.__wvPendingRegs;
+
+export function createRegistration(opts: {
+	agentId: string;
+	displayName: string;
+	requestedScope?: AgentScope;
+}): PendingRegistration {
+	const registrationId = `reg_${randomBytes(16).toString("hex")}`;
+	const reg: PendingRegistration = {
+		registrationId,
+		agentId: opts.agentId,
+		displayName: opts.displayName,
+		requestedScope: opts.requestedScope ?? {
+			paths: ["**/*"],
+			ops: ["read", "mutate"],
+		},
+		requestedAt: new Date().toISOString(),
+		status: "pending",
+	};
+	store.set(registrationId, reg);
+	return reg;
+}
+
+export function getRegistration(id: string): PendingRegistration | undefined {
+	return store.get(id);
+}
+
+export function listPendingRegistrations(): PendingRegistration[] {
+	return [...store.values()].filter((r) => r.status === "pending");
+}
+
+export function listAllRegistrations(): PendingRegistration[] {
+	return [...store.values()];
+}
+
+/** Mark as approved and stash one-shot token. */
+export function approveRegistration(id: string, tokenPlaintext: string): boolean {
+	const reg = store.get(id);
+	if (!reg || reg.status !== "pending") return false;
+	reg.status = "approved";
+	reg.tokenPlaintext = tokenPlaintext;
+	reg.resolvedAt = new Date().toISOString();
+	return true;
+}
+
+/** Consume (pick up) the one-shot token. Returns plaintext then clears it. */
+export function consumeRegistration(id: string): string | null {
+	const reg = store.get(id);
+	if (!reg || reg.status !== "approved" || !reg.tokenPlaintext) return null;
+	const token = reg.tokenPlaintext;
+	reg.status = "consumed";
+	reg.tokenPlaintext = undefined;
+	return token;
+}
+
+export function denyRegistration(id: string): boolean {
+	const reg = store.get(id);
+	if (!reg || reg.status !== "pending") return false;
+	reg.status = "denied";
+	reg.resolvedAt = new Date().toISOString();
+	return true;
+}

package/.next/standalone/src/lib/proof/proof-span.ts

@@ -0,0 +1,141 @@
+import type { SpanAttrs } from "./types";
+
+export type { SpanAttrs };
+
+function escapeAttr(value: string): string {
+	return value.replace(/&/g, "&").replace(/"/g, """);
+}
+
+function buildAttrs(attrs: SpanAttrs): string {
+	const parts: string[] = [
+		`id="${escapeAttr(attrs.spanId)}"`,
+		`origin="${attrs.origin}"`,
+	];
+	if (attrs.basis) parts.push(`basis="${escapeAttr(attrs.basis)}"`);
+	if (attrs.basisDetail) parts.push(`basis-detail="${escapeAttr(attrs.basisDetail)}"`);
+	parts.push(`by="${escapeAttr(attrs.by)}"`);
+	parts.push(`at="${escapeAttr(attrs.at)}"`);
+	if (attrs.inResponseTo) parts.push(`in-response-to="${escapeAttr(attrs.inResponseTo)}"`);
+	return parts.join(" ");
+}
+
+/**
+ * Wrap the text content of a markdown block in a <proof-span>.
+ *
+ * Wrap rules:
+ *   paragraph    -> wrap full markdown text
+ *   heading      -> wrap text after the leading "#"s
+ *   bulletList / orderedList / taskList -> wrap each list item's text line
+ *   blockquote   -> wrap text content (after "> " prefix)
+ *   codeBlock / table / hr / html -> return null (caller records in sidecar.blockProvenance)
+ */
+export function wrapAsProofSpan(
+	markdown: string,
+	attrs: SpanAttrs,
+): string | null {
+	const a = buildAttrs(attrs);
+
+	// Detect block type from markdown shape
+	const trimmed = markdown.trim();
+
+	// code block
+	if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) return null;
+
+	// html block
+	if (trimmed.startsWith("<") && !trimmed.startsWith("<proof-span")) return null;
+
+	// hr
+	if (/^[-*_]{3,}\s*$/.test(trimmed)) return null;
+
+	// table (contains | pipes in first line)
+	const firstLine = trimmed.split("\n")[0];
+	if (firstLine.includes("|") && /^\|.*\|/.test(firstLine)) return null;
+
+	// heading: "# text" -> "# <proof-span ...>text</proof-span>"
+	const headingMatch = trimmed.match(/^(#{1,6})\s+(.+)$/);
+	if (headingMatch) {
+		const hashes = headingMatch[1];
+		const text = headingMatch[2].trimEnd();
+		return `${hashes} <proof-span ${a}>${text}</proof-span>`;
+	}
+
+	// blockquote: each line starts with "> "
+	if (trimmed.startsWith(">")) {
+		return trimmed
+			.split("\n")
+			.map((line) => {
+				const bqMatch = line.match(/^(>\s?)(.*)/);
+				if (!bqMatch) return line;
+				const prefix = bqMatch[1];
+				const content = bqMatch[2];
+				if (!content.trim()) return line;
+				return `${prefix}<proof-span ${a}>${content}</proof-span>`;
+			})
+			.join("\n");
+	}
+
+	// list items (bullet/ordered/task)
+	// Each item starts with "- ", "* ", "+ ", or "N. "
+	// Task items: "- [ ] " or "- [x] "
+	const listItemRe = /^(\s*(?:[-*+]|\d+\.)\s+(?:\[[ xX]\]\s+)?)(.*)/;
+	if (listItemRe.test(trimmed.split("\n")[0])) {
+		return trimmed
+			.split("\n")
+			.map((line) => {
+				const m = line.match(/^(\s*(?:[-*+]|\d+\.)\s+(?:\[[ xX]\]\s+)?)(.*)/);
+				if (!m) return line;
+				const prefix = m[1];
+				const content = m[2];
+				if (!content.trim()) return line;
+				return `${prefix}<proof-span ${a}>${content}</proof-span>`;
+			})
+			.join("\n");
+	}
+
+	// paragraph: wrap the whole thing
+	return `<proof-span ${a}>${trimmed}</proof-span>`;
+}
+
+/**
+ * Remove all <proof-span ...>...</proof-span> wrappers, keeping inner content.
+ * Used for "Accept" (keep text, drop attribution).
+ */
+export function unwrapProofSpans(markdown: string): string {
+	return markdown.replace(/<proof-span\b[^>]*>([\s\S]*?)<\/proof-span>/g, "$1");
+}
+
+/**
+ * Remove a specific <proof-span id="spanId">...</proof-span>, discarding content.
+ * Used for "Revert" (delete AI-authored text).
+ */
+export function revertProofSpan(markdown: string, spanId: string): string {
+	const escapedId = spanId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const re = new RegExp(
+		`<proof-span\\b[^>]*\\bid="${escapedId}"[^>]*>[\\s\\S]*?<\\/proof-span>`,
+		"g",
+	);
+	return markdown.replace(re, "");
+}
+
+/**
+ * Extract all span IDs from a markdown string.
+ */
+export function extractSpanIds(markdown: string): string[] {
+	const ids: string[] = [];
+	const re = /<proof-span\b[^>]*\bid="([^"]+)"/g;
+	let m: RegExpExecArray | null;
+	while ((m = re.exec(markdown)) !== null) {
+		ids.push(m[1]);
+	}
+	return ids;
+}
+
+/**
+ * Generate a unique span ID "p" + 4-hex.
+ */
+export function newSpanId(): string {
+	const hex = Math.floor(Math.random() * 0xffff)
+		.toString(16)
+		.padStart(4, "0");
+	return `p${hex}`;
+}

package/.next/standalone/src/lib/proof/rate-limit.ts

@@ -0,0 +1,53 @@
+import { OPS_PER_MINUTE } from "../proof-config";
+
+interface Bucket {
+	tokens: number;
+	lastRefill: number; // ms epoch
+}
+
+const buckets = new Map<string, Bucket>();
+
+/**
+ * Token-bucket rate limiter per `by` identity.
+ * Bucket size = OPS_PER_MINUTE (default 60).
+ * Refill rate: 1 token/sec (continuous approximation).
+ *
+ * Returns { ok: true } when tokens consumed, or
+ * { ok: false, retryAfterMs } when exhausted.
+ */
+export function checkAndConsume(
+	by: string,
+	n: number = 1,
+): { ok: true } | { ok: false; retryAfterMs: number } {
+	const now = Date.now();
+	const bucketSize = OPS_PER_MINUTE;
+
+	let bucket = buckets.get(by);
+	if (!bucket) {
+		bucket = { tokens: bucketSize, lastRefill: now };
+		buckets.set(by, bucket);
+	}
+
+	// Refill: 1 token per 1000 ms elapsed
+	const elapsed = now - bucket.lastRefill;
+	const refill = Math.floor(elapsed / 1000);
+	if (refill > 0) {
+		bucket.tokens = Math.min(bucketSize, bucket.tokens + refill);
+		bucket.lastRefill = bucket.lastRefill + refill * 1000;
+	}
+
+	if (bucket.tokens < n) {
+		// How long until we have n tokens?
+		const needed = n - bucket.tokens;
+		const retryAfterMs = needed * 1000 - (now - bucket.lastRefill);
+		return { ok: false, retryAfterMs: Math.max(1, retryAfterMs) };
+	}
+
+	bucket.tokens -= n;
+	return { ok: true };
+}
+
+/** Exposed for tests only — reset all buckets. */
+export function _resetBuckets(): void {
+	buckets.clear();
+}

package/.next/standalone/src/lib/proof/register-rate-limit.ts

@@ -0,0 +1,53 @@
+/**
+ * In-memory token bucket rate limiter for registration attempts.
+ *
+ * Bucket size: 10 requests
+ * Refill rate: 1 token per 6 seconds (= 10/min)
+ */
+
+interface Bucket {
+	tokens: number;
+	lastRefillAt: number;
+}
+
+const BUCKET_CAPACITY = 10;
+const REFILL_INTERVAL_MS = 6_000; // 1 token per 6s = 10/min
+
+// Module-level singleton keyed by IP (or "__global__" if no IP available)
+const g = globalThis as typeof globalThis & {
+	__wvRegBuckets?: Map<string, Bucket>;
+};
+if (!g.__wvRegBuckets) {
+	g.__wvRegBuckets = new Map();
+}
+const buckets: Map<string, Bucket> = g.__wvRegBuckets;
+
+function refill(bucket: Bucket): void {
+	const now = Date.now();
+	const elapsed = now - bucket.lastRefillAt;
+	const tokensToAdd = Math.floor(elapsed / REFILL_INTERVAL_MS);
+	if (tokensToAdd > 0) {
+		bucket.tokens = Math.min(BUCKET_CAPACITY, bucket.tokens + tokensToAdd);
+		bucket.lastRefillAt = now;
+	}
+}
+
+/** Returns true if request is allowed; false if rate limited. */
+export function checkRegisterRateLimit(key: string): boolean {
+	let bucket = buckets.get(key);
+	if (!bucket) {
+		bucket = { tokens: BUCKET_CAPACITY, lastRefillAt: Date.now() };
+		buckets.set(key, bucket);
+	}
+	refill(bucket);
+	if (bucket.tokens > 0) {
+		bucket.tokens--;
+		return true;
+	}
+	return false;
+}
+
+/** Reset all buckets — for tests only. */
+export function _resetRegisterBuckets(): void {
+	buckets.clear();
+}

package/.next/standalone/src/lib/proof/registry.ts

@@ -0,0 +1,190 @@
+/**
+ * Agent registry.
+ *
+ * Persists to ~/.wiki-viewer/agents.json (agent records).
+ * Human authentication is handled by Better Auth (see src/lib/auth/server.ts).
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { withFileMutex } from "./mutex";
+
+// Sentinel key for all registry write operations
+const REGISTRY_MUTEX_KEY = "__registry__";
+
+// Throttle updateLastSeen: skip if updated < 30s ago
+const lastSeenWriteAt: Map<string, number> = new Map();
+const LAST_SEEN_THROTTLE_MS = 30_000;
+
+export interface AgentScope {
+	paths: string[]; // glob patterns
+	ops: Array<"read" | "mutate">;
+}
+
+export interface Agent {
+	id: string;
+	displayName: string;
+	tokenHash: string; // sha256 hex of raw token
+	scope: AgentScope;
+	createdAt: string; // ISO-8601
+	lastSeen: string; // ISO-8601
+	/** Better Auth user.id of the owner who approved this agent. Undefined for legacy entries. */
+	ownerUserId?: string;
+}
+
+export interface Registry {
+	version: 1;
+	agents: Agent[];
+}
+
+// ── Path helpers ──────────────────────────────────────────────────────────────
+
+function wikiViewerDir(): string {
+	// Prefer HOME env var so tests can override by setting process.env.HOME.
+	const home = process.env.HOME ?? os.homedir();
+	return path.join(home, ".wiki-viewer");
+}
+
+function agentsJsonPath(): string {
+	return path.join(wikiViewerDir(), "agents.json");
+}
+
+
+// ── Hashing ───────────────────────────────────────────────────────────────────
+
+export function hashToken(token: string): string {
+	return createHash("sha256").update(token, "utf8").digest("hex");
+}
+
+function timingSafeEqualHex(a: string, b: string): boolean {
+	// Pad to equal length before comparing to avoid length-based timing leak
+	const bufA = Buffer.from(a.padEnd(64, "0"), "utf8");
+	const bufB = Buffer.from(b.padEnd(64, "0"), "utf8");
+	if (bufA.length !== bufB.length) return false;
+	return timingSafeEqual(bufA, bufB) && a.length === b.length;
+}
+
+// ── Read / Write ──────────────────────────────────────────────────────────────
+
+export async function readRegistry(): Promise<Registry | null> {
+	try {
+		const raw = await readFile(agentsJsonPath(), "utf8");
+		const parsed = JSON.parse(raw) as Record<string, unknown>;
+		// Migrate: silently drop legacy `owner` field if present
+		return {
+			version: 1,
+			agents: Array.isArray(parsed.agents) ? (parsed.agents as Agent[]) : [],
+		};
+	} catch {
+		return null;
+	}
+}
+
+/** Inner write — caller must already hold REGISTRY_MUTEX_KEY or be in single-writer context. */
+async function _writeRegistryUnsafe(r: Registry): Promise<void> {
+	await mkdir(wikiViewerDir(), { recursive: true });
+	const tmp = agentsJsonPath() + ".tmp";
+	await writeFile(tmp, JSON.stringify(r, null, 2), { encoding: "utf8", mode: 0o600 });
+	try {
+		await chmod(tmp, 0o600);
+	} catch {
+		// Non-fatal on Windows/some environments
+	}
+	await rename(tmp, agentsJsonPath());
+}
+
+export async function writeRegistry(r: Registry): Promise<void> {
+	await withFileMutex(REGISTRY_MUTEX_KEY, () => _writeRegistryUnsafe(r));
+}
+
+// ── Ensure registry (creates if missing) ─────────────────────────────────────
+
+/**
+ * Public: creates registry if missing. Acquires the mutex itself.
+ * Do NOT call from inside a mutex-held context.
+ */
+export async function ensureRegistry(): Promise<Registry> {
+	const existing = await readRegistry();
+	if (existing) return existing;
+
+	const r: Registry = { version: 1, agents: [] };
+	await writeRegistry(r); // acquires lock
+	return r;
+}
+
+/**
+ * Inner ensure — for use within a locked context.
+ * Creates registry if missing using unlocked write.
+ */
+async function _ensureRegistryUnsafe(): Promise<Registry> {
+	const existing = await readRegistry();
+	if (existing) return existing;
+
+	const r: Registry = { version: 1, agents: [] };
+	await _writeRegistryUnsafe(r);
+	return r;
+}
+
+// ── Agent lookups ─────────────────────────────────────────────────────────────
+
+export async function lookupAgentByToken(token: string): Promise<Agent | null> {
+	const r = await readRegistry();
+	if (!r) return null;
+	const candidate = hashToken(token);
+	for (const agent of r.agents) {
+		if (timingSafeEqualHex(agent.tokenHash, candidate)) {
+			return agent;
+		}
+	}
+	return null;
+}
+
+export async function lookupAgentById(id: string): Promise<Agent | null> {
+	const r = await readRegistry();
+	if (!r) return null;
+	return r.agents.find((a) => a.id === id) ?? null;
+}
+
+export async function addAgent(agent: Agent): Promise<void> {
+	await withFileMutex(REGISTRY_MUTEX_KEY, async () => {
+		const r = await _ensureRegistryUnsafe(); // no re-entrant lock
+		// Replace if id already present
+		const idx = r.agents.findIndex((a) => a.id === agent.id);
+		if (idx >= 0) {
+			r.agents[idx] = agent;
+		} else {
+			r.agents.push(agent);
+		}
+		await _writeRegistryUnsafe(r);
+	});
+}
+
+export async function removeAgent(id: string): Promise<boolean> {
+	return withFileMutex(REGISTRY_MUTEX_KEY, async () => {
+		const r = await readRegistry();
+		if (!r) return false;
+		const before = r.agents.length;
+		r.agents = r.agents.filter((a) => a.id !== id);
+		if (r.agents.length === before) return false;
+		await _writeRegistryUnsafe(r);
+		return true;
+	});
+}
+
+export async function updateLastSeen(id: string): Promise<void> {
+	// Throttle: skip if updated recently
+	const now = Date.now();
+	const last = lastSeenWriteAt.get(id) ?? 0;
+	if (now - last < LAST_SEEN_THROTTLE_MS) return;
+
+	await withFileMutex(REGISTRY_MUTEX_KEY, async () => {
+		const r = await readRegistry();
+		if (!r) return;
+		const agent = r.agents.find((a) => a.id === id);
+		if (!agent) return;
+		agent.lastSeen = new Date().toISOString();
+		lastSeenWriteAt.set(id, Date.now());
+		await _writeRegistryUnsafe(r);
+	});
+}

package/.next/standalone/src/lib/proof/sidecar.ts

@@ -0,0 +1,66 @@
+import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
+import path from "node:path";
+import type { Sidecar } from "./types";
+
+export function sidecarPath(rootDir: string, mdPath: string): string {
+	return path.join(rootDir, ".proof", mdPath + ".json");
+}
+
+export async function readSidecar(
+	rootDir: string,
+	mdPath: string,
+): Promise<Sidecar | null> {
+	const filePath = sidecarPath(rootDir, mdPath);
+	try {
+		const raw = await readFile(filePath, "utf-8");
+		const parsed = JSON.parse(raw) as Sidecar;
+		if (parsed.schemaVersion !== 1) {
+			throw new Error(
+				`Sidecar schema version mismatch: expected 1, got ${parsed.schemaVersion}`,
+			);
+		}
+		return parsed;
+	} catch (err: unknown) {
+		if (
+			err instanceof Error &&
+			"code" in err &&
+			(err as NodeJS.ErrnoException).code === "ENOENT"
+		) {
+			return null;
+		}
+		throw err;
+	}
+}
+
+export async function writeSidecar(
+	rootDir: string,
+	mdPath: string,
+	sc: Sidecar,
+): Promise<void> {
+	const dest = sidecarPath(rootDir, mdPath);
+	await mkdir(path.dirname(dest), { recursive: true });
+	const tmp = dest + ".tmp";
+	await writeFile(tmp, JSON.stringify(sc, null, 2), "utf-8");
+	await rename(tmp, dest);
+}
+
+export function emptySidecar(mdPath: string): Sidecar {
+	const now = new Date().toISOString();
+	return {
+		schemaVersion: 1,
+		path: mdPath,
+		revision: 0,
+		createdAt: now,
+		updatedAt: now,
+		refMap: {},
+		refAliases: {},
+		comments: [],
+		suggestions: [],
+		archivedSuggestions: [],
+		events: [],
+		nextEventId: 1,
+		lastAck: {},
+		fingerprint: "",
+		blockProvenance: {},
+	};
+}

package/.next/standalone/src/lib/proof/suggest-capture.ts

@@ -0,0 +1,69 @@
+import { authHeaders } from "./client-auth";
+import type { SuggestionKind } from "./types";
+
+interface PostResult {
+	ok: boolean;
+	stale: boolean;
+	newRevision?: number;
+}
+
+async function postSuggestionOp(
+	path: string,
+	baseRevision: number,
+	op: Record<string, unknown>,
+): Promise<PostResult> {
+	const encoded = encodeURIComponent(path).replace(/%2F/g, "/");
+	const res = await fetch(`/api/agent/files/${encoded}`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"Idempotency-Key": crypto.randomUUID(),
+			...authHeaders(),
+		},
+		body: JSON.stringify({ baseRevision, by: "human", ops: [op] }),
+	});
+	if (res.status === 409) {
+		const data = (await res.json()) as {
+			code?: string;
+			snapshot?: { revision?: number };
+		};
+		if (data.code === "STALE_REVISION" && data.snapshot?.revision !== undefined) {
+			return { ok: false, stale: true, newRevision: data.snapshot.revision };
+		}
+		return { ok: false, stale: false };
+	}
+	return { ok: res.ok, stale: false };
+}
+
+/**
+ * Emit a human suggestion for a block, retrying once on a stale-revision 409.
+ *
+ * `getRevision` returns the freshest known snapshot revision, `refresh`
+ * reloads the snapshot+sidecar so a retry can use the latest revision.
+ */
+export async function captureSuggestion(args: {
+	path: string;
+	ref: string;
+	kind: SuggestionKind;
+	markdown?: string;
+	basisDetail?: string;
+	getRevision: () => number;
+	refresh: () => Promise<void>;
+}): Promise<boolean> {
+	const { path, ref, kind, markdown, basisDetail, getRevision, refresh } = args;
+	const op: Record<string, unknown> = {
+		type: "suggestion.add",
+		ref,
+		kind,
+		basis: "suggested",
+	};
+	if (kind !== "delete") op.markdown = markdown ?? "";
+	if (basisDetail) op.basisDetail = basisDetail;
+
+	let result = await postSuggestionOp(path, getRevision(), op);
+	if (!result.ok && result.stale && result.newRevision !== undefined) {
+		await refresh();
+		result = await postSuggestionOp(path, result.newRevision, op);
+	}
+	return result.ok;
+}