@xopcai/xopc 0.0.222 → 0.0.224

package/dist/src/gateway/hono/routes/notes.js

@@ -1,7 +1,14 @@
 import { ObjectLinkService } from "../../../activity/service.js";
 import { buildSessionKey, init_session_key } from "../../../routing/session-key.js";
 import { agentExists, getDefaultAgentId, init_resolve_route } from "../../../routing/resolve-route.js";
+import { resolveGatewayEffectiveHost } from "../../../config/gateway-bind.js";
+import { getShareStore } from "../../../share/share-store.js";
+import { resolveShareUrl } from "../../../share/share-url.js";
+import { resolveReverseProxyPublicUrl } from "../../public-url.js";
+import { extractToken } from "../../auth.js";
+import { NoteShareService, NoteShareVersionConflictError } from "../../../share/note-share-service.js";
 import { createReadStream } from "node:fs";
+import { createHash } from "node:crypto";
 import { access, stat } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { stream } from "hono/streaming";
@@ -38,6 +45,9 @@ function noteNotFound() {
 		code: "note_not_found"
 	};
 }
+function readIdempotencyKey(value) {
+	return value?.trim() || void 0;
+}
 function parseCaptureSource(body) {
 	return {
 		channel: typeof body.channel === "string" && VALID_CHANNELS.has(body.channel) ? body.channel : "web",
@@ -63,6 +73,21 @@ function noteThreadName(note) {
 function registerNotesRoutes(authenticated, deps) {
 	const { service } = deps;
 	const objectLinks = new ObjectLinkService();
+	const shareConfig = () => {
+		const raw = (service.currentConfig?.gateway)?.share;
+		return raw && typeof raw === "object" ? raw : {};
+	};
+	const shareStore = () => {
+		const store = getShareStore(shareConfig());
+		store.updateConfig(shareConfig());
+		return store;
+	};
+	const noteShares = () => new NoteShareService(shareStore(), service.notesServiceInstance);
+	const shareUrlContext = () => ({
+		gatewayHost: resolveGatewayEffectiveHost(service.currentConfig),
+		gatewayPort: service.currentConfig?.gateway?.port ?? 18790,
+		reverseProxyPublicUrl: resolveReverseProxyPublicUrl(service.currentConfig)
+	});
 	const linkNoteToProject = (note, projectId) => {
 		if (!projectId) return;
 		const project = service.projects.get(projectId);
@@ -88,7 +113,7 @@ function registerNotesRoutes(authenticated, deps) {
 		const text = typeof body.text === "string" ? body.text.trim() : "";
 		if (!text) return c.json({ error: "Missing required field: text" }, 400);
 		const source = parseCaptureSource(body);
-		const idempotencyKey = c.req.header("idempotency-key")?.trim();
+		const idempotencyKey = readIdempotencyKey(c.req.header("idempotency-key"));
 		if (idempotencyKey && idempotencyKey.length > 200) return c.json({ error: "Idempotency-Key is too long" }, 400);
 		const note = await service.notesServiceInstance.quickCapture(text, source, idempotencyKey || void 0);
 		return c.json({ note }, 201);
@@ -119,7 +144,10 @@ function registerNotesRoutes(authenticated, deps) {
 		return c.json(result);
 	});
 	authenticated.post("/api/notes", async (c) => {
-		if ((c.req.header("content-type") || "").includes("multipart/form-data")) {
+		const contentType = c.req.header("content-type") || "";
+		const idempotencyKey = readIdempotencyKey(c.req.header("idempotency-key"));
+		if (idempotencyKey && idempotencyKey.length > 200) return c.json({ error: "Idempotency-Key is too long" }, 400);
+		if (contentType.includes("multipart/form-data")) {
 			let body;
 			try {
 				body = await c.req.parseBody({ all: true });
@@ -137,7 +165,7 @@ function registerNotesRoutes(authenticated, deps) {
 				kind: kindRaw && VALID_KINDS.has(kindRaw) ? kindRaw : void 0,
 				tags: tagsRaw ? tagsRaw.split(",").map((t) => t.trim()).filter(Boolean) : void 0,
 				capturedVia: source
-			});
+			}, idempotencyKey);
 			linkNoteToProject(note, projectId);
 			const file = body.file;
 			if (file && typeof file === "object") {
@@ -156,8 +184,9 @@ function registerNotesRoutes(authenticated, deps) {
 						name: fileName,
 						buffer: buf,
 						mimeType,
-						duration: Number.isFinite(duration) ? duration : void 0
-					});
+						duration: Number.isFinite(duration) ? duration : void 0,
+						retainWithoutReference: kindRaw === "voice"
+					}, idempotencyKey);
 				}
 			}
 			const full = await service.notesServiceInstance.getNote(note.id);
@@ -178,7 +207,7 @@ function registerNotesRoutes(authenticated, deps) {
 			tags: tagsRaw,
 			capturedVia: source,
 			pinned: body.pinned === true
-		});
+		}, idempotencyKey);
 		linkNoteToProject(note, projectId);
 		return c.json({ note }, 201);
 	});
@@ -335,6 +364,127 @@ function registerNotesRoutes(authenticated, deps) {
 		if (!note) return c.json(noteNotFound(), 404);
 		return c.json({ note });
 	});
+	authenticated.get("/api/notes/:id/shares", async (c) => {
+		const note = await service.notesServiceInstance.getNote(c.req.param("id"));
+		if (!note) return c.json(noteNotFound(), 404);
+		const shares = noteShares();
+		const now = Date.now();
+		const items = shares.list(note.id).map((record) => {
+			const resolved = resolveShareUrl(record.token, shareUrlContext());
+			return {
+				id: record.id,
+				kind: "note",
+				fileName: record.fileName,
+				shareUrl: resolved.shareUrl,
+				lanUrl: resolved.lanUrl,
+				reachability: resolved.reachability,
+				reachabilityHint: resolved.reachabilityHint,
+				createdAt: record.createdAt,
+				expiresAt: record.expiresAt,
+				viewCount: record.downloadCount,
+				maxViews: record.maxViews,
+				revoked: record.revoked,
+				expired: now >= new Date(record.expiresAt).getTime(),
+				description: record.description ?? null,
+				sourceVersion: record.sourceVersion,
+				snapshotRevision: record.snapshotRevision,
+				attachmentCount: record.attachmentCount,
+				stale: note.updatedAt > record.sourceVersion
+			};
+		});
+		return c.json({
+			items,
+			total: items.length,
+			noteVersion: note.updatedAt
+		});
+	});
+	authenticated.post("/api/notes/:id/shares", async (c) => {
+		const gatewayToken = extractToken({ authorization: c.req.header("authorization") ?? void 0 });
+		if (!gatewayToken) return c.json({
+			ok: false,
+			error: { message: "Token required" }
+		}, 401);
+		const body = await c.req.json().catch(() => ({}));
+		const shares = noteShares();
+		try {
+			const record = await shares.create(c.req.param("id"), {
+				expectedNoteVersion: typeof body.expectedNoteVersion === "number" ? body.expectedNoteVersion : void 0,
+				attachmentIds: Array.isArray(body.attachmentIds) ? body.attachmentIds.filter((id) => typeof id === "string") : void 0,
+				ttlMs: typeof body.ttlMs === "number" ? body.ttlMs : void 0,
+				maxViews: body.maxViews === null ? null : typeof body.maxViews === "number" ? body.maxViews : void 0,
+				description: typeof body.description === "string" ? body.description.trim() || void 0 : void 0,
+				gatewayTokenHash: createHash("sha256").update(gatewayToken, "utf8").digest("hex").slice(0, 12)
+			});
+			const resolved = resolveShareUrl(record.token, shareUrlContext());
+			return c.json({
+				ok: true,
+				payload: {
+					id: record.id,
+					kind: record.kind,
+					shareUrl: resolved.shareUrl,
+					lanUrl: resolved.lanUrl,
+					reachability: resolved.reachability,
+					reachabilityHint: resolved.reachabilityHint,
+					expiresAt: record.expiresAt,
+					maxViews: record.maxViews,
+					sourceNoteId: record.sourceNoteId,
+					sourceVersion: record.sourceVersion,
+					snapshotRevision: record.snapshotRevision,
+					attachmentCount: record.attachmentCount,
+					fileName: record.fileName
+				}
+			}, 201);
+		} catch (err) {
+			if (err instanceof NoteShareVersionConflictError) return c.json({
+				ok: false,
+				error: {
+					code: "note_version_conflict",
+					message: err.message,
+					currentVersion: err.currentVersion
+				}
+			}, 409);
+			const message = err instanceof Error ? err.message : String(err);
+			return c.json({
+				ok: false,
+				error: { message }
+			}, message === "Note not found" ? 404 : 400);
+		}
+	});
+	authenticated.post("/api/notes/:id/shares/:shareId/refresh", async (c) => {
+		const body = await c.req.json().catch(() => ({}));
+		const shares = noteShares();
+		try {
+			const record = await shares.refresh(c.req.param("id"), c.req.param("shareId"), {
+				expectedNoteVersion: typeof body.expectedNoteVersion === "number" ? body.expectedNoteVersion : void 0,
+				attachmentIds: Array.isArray(body.attachmentIds) ? body.attachmentIds.filter((id) => typeof id === "string") : void 0
+			});
+			const resolved = resolveShareUrl(record.token, shareUrlContext());
+			return c.json({
+				ok: true,
+				payload: {
+					id: record.id,
+					shareUrl: resolved.shareUrl,
+					sourceVersion: record.sourceVersion,
+					snapshotRevision: record.snapshotRevision,
+					attachmentCount: record.attachmentCount
+				}
+			});
+		} catch (err) {
+			if (err instanceof NoteShareVersionConflictError) return c.json({
+				ok: false,
+				error: {
+					code: "note_version_conflict",
+					message: err.message,
+					currentVersion: err.currentVersion
+				}
+			}, 409);
+			const message = err instanceof Error ? err.message : String(err);
+			return c.json({
+				ok: false,
+				error: { message }
+			}, message === "Note share not found" || message === "Note not found" ? 404 : 400);
+		}
+	});
 	authenticated.patch("/api/notes/:id", async (c) => {
 		const id = c.req.param("id");
 		const body = await c.req.json().catch(() => ({}));
@@ -346,8 +496,13 @@ function registerNotesRoutes(authenticated, deps) {
 	});
 	authenticated.delete("/api/notes/:id", async (c) => {
 		const id = c.req.param("id");
+		const body = await c.req.json().catch(() => ({}));
 		if (!await service.notesServiceInstance.deleteNote(id)) return c.json(noteNotFound(), 404);
-		return c.json({ deleted: true });
+		const revokedShares = body.revokeShares === false ? 0 : await noteShares().revokeForNote(id);
+		return c.json({
+			deleted: true,
+			revokedShares
+		});
 	});
 	authenticated.get("/api/notes/:id/history", async (c) => {
 		const id = c.req.param("id");

package/dist/src/gateway/hono/routes/shares.js

@@ -10,7 +10,8 @@ import { audienceDefaults, cleanupStagedSite, decideShareKind, forgetStagedSite,
 import { deleteThumbnail, placeholderSvg, readThumbnail, scheduleThumbnail, thumbnailContentType, thumbnailExists } from "../../../share/share-thumbnail.js";
 import { extractToken } from "../../auth.js";
 import { getClientIpFromHeaders } from "../../security/loopback.js";
-import { renderFolderLandingPage, renderShareExpiredPage, renderShareLandingPage } from "../../../share/share-landing.js";
+import { renderFolderLandingPage, renderNoteShareLandingPage, renderShareExpiredPage, renderShareLandingPage } from "../../../share/share-landing.js";
+import { NoteShareService } from "../../../share/note-share-service.js";
 import { consumeSharePublicLimit } from "../../../share/share-rate-limit.js";
 import { createZipStream, planDirectoryFiles } from "../../../share/share-zip.js";
 import { createReadStream } from "node:fs";
@@ -93,6 +94,7 @@ function rfc5987ContentDisposition(disposition, fileName) {
 }
 function registerSharePublicRoutes(app, service) {
 	const store = getShareStore(resolveShareConfig(service));
+	const noteShares = new NoteShareService(store, service.notesServiceInstance);
 	/** Landing page — does NOT consume downloadCount. */
 	app.get("/s/:token", async (c) => {
 		const clientIp = getClientIpFromHeaders({ get: (n) => c.req.header(n) ?? void 0 });
@@ -115,6 +117,13 @@ function registerSharePublicRoutes(app, service) {
 			return c.html(renderShareExpiredPage(validation.reason), 410);
 		}
 		if (record.kind === "directory") return renderDirectoryLanding(c, store, service, record, token);
+		if (record.kind === "note") {
+			const previewUrl = `/#/share/${encodeURIComponent(token)}`;
+			c.header("Content-Security-Policy", "default-src 'none'; script-src 'unsafe-inline'; base-uri 'none'; frame-ancestors 'none'");
+			c.header("X-Frame-Options", "DENY");
+			c.header("Referrer-Policy", "no-referrer");
+			return c.html(renderNoteShareLandingPage(record, previewUrl, { og: buildLandingOg(service, record) }));
+		}
 		if (c.req.query("dl") === "1") return handleFileDownload(c, store, record, clientIp);
 		if (c.req.query("inline") === "1") {
 			if ({
@@ -157,9 +166,105 @@ function registerSharePublicRoutes(app, service) {
 			}, `Share download denied: ${validation.reason}`);
 			return c.html(renderShareExpiredPage(validation.reason), 410);
 		}
-		if (record.kind === "directory") return c.html(renderShareExpiredPage("not_found"), 404);
+		if (record.kind !== "file") return c.html(renderShareExpiredPage("not_found"), 404);
 		return handleFileDownload(c, store, record, clientIp);
 	});
+	/** Claim one Note view. POST prevents social unfurlers from consuming maxViews. */
+	app.post("/s/:token/view", async (c) => {
+		const clientIp = getClientIpFromHeaders({ get: (n) => c.req.header(n) ?? void 0 });
+		const rateResult = consumeSharePublicLimit(clientIp);
+		if (!rateResult.allowed) {
+			c.header("Retry-After", String(Math.ceil(rateResult.retryAfterMs / 1e3)));
+			return c.json({
+				ok: false,
+				error: { message: "rate_limited" }
+			}, 429);
+		}
+		const token = c.req.param("token");
+		const record = store.getByToken(token);
+		if (!record || record.kind !== "note") return c.json({
+			ok: false,
+			error: { message: "not_found" }
+		}, 404);
+		const validation = store.validateAccess(record);
+		if (!validation.valid) return c.json({
+			ok: false,
+			error: { message: validation.reason }
+		}, 410);
+		try {
+			const manifest = await noteShares.readManifest(record);
+			const consumed = store.consumeAccess(record.id);
+			if (consumed.valid === false) return c.json({
+				ok: false,
+				error: { message: consumed.reason }
+			}, 410);
+			const ticket = noteShares.issueAssetTicket(record);
+			logShareAudit("share.access", {
+				shareId: record.id,
+				noteId: record.sourceNoteId,
+				tokenPrefix: token.slice(0, 8),
+				clientIp,
+				snapshotRevision: record.snapshotRevision
+			}, `Note share viewed: ${record.fileName}`);
+			return c.json({
+				ok: true,
+				payload: {
+					kind: "note",
+					title: manifest.title,
+					markdown: noteShares.publicMarkdown(record, manifest, ticket),
+					snapshotAt: manifest.snapshotAt,
+					expiresAt: record.expiresAt,
+					description: record.description ?? null,
+					sourceVersion: record.sourceVersion,
+					snapshotRevision: record.snapshotRevision,
+					attachments: manifest.attachments.map(({ artifactFileName: _artifactFileName, checksum: _checksum, ...attachment }) => attachment)
+				}
+			});
+		} catch (err) {
+			logShareAudit("share.access_denied", {
+				shareId: record.id,
+				noteId: record.sourceNoteId,
+				tokenPrefix: token.slice(0, 8),
+				clientIp,
+				reason: "artifact_missing"
+			}, "Note share artifact could not be read");
+			return c.json({
+				ok: false,
+				error: { message: err instanceof Error ? err.message : "artifact_missing" }
+			}, 410);
+		}
+	});
+	/** Serve one snapshotted Note attachment through a short-lived view ticket. */
+	app.get("/s/:token/assets/:attachmentId", async (c) => {
+		const rateResult = consumeSharePublicLimit(getClientIpFromHeaders({ get: (n) => c.req.header(n) ?? void 0 }));
+		if (!rateResult.allowed) {
+			c.header("Retry-After", String(Math.ceil(rateResult.retryAfterMs / 1e3)));
+			return c.text("Too many requests", 429);
+		}
+		const record = store.getByToken(c.req.param("token"));
+		if (!record || record.kind !== "note") return c.text("Not found", 404);
+		if (record.revoked || Date.now() >= new Date(record.expiresAt).getTime()) return c.text("Gone", 410);
+		const ticket = c.req.query("ticket") ?? "";
+		if (!noteShares.verifyAssetTicket(record, ticket)) return c.text("Forbidden", 403);
+		const resolved = await noteShares.resolveAsset(record, c.req.param("attachmentId")).catch(() => null);
+		if (!resolved) return c.text("Not found", 404);
+		const fileStat = await stat(resolved.path).catch(() => null);
+		if (!fileStat?.isFile()) return c.text("Not found", 404);
+		const inline = resolved.attachment.type !== "file";
+		const stream = createReadStream(resolved.path);
+		return new Response(Readable.toWeb(stream), {
+			status: 200,
+			headers: {
+				"Content-Type": shareResponseContentType(resolved.attachment.mimeType),
+				"Content-Disposition": rfc5987ContentDisposition(inline ? "inline" : "attachment", resolved.attachment.fileName),
+				"Content-Length": String(fileStat.size),
+				"Cache-Control": "private, no-store",
+				"X-Content-Type-Options": "nosniff",
+				"X-Frame-Options": "DENY",
+				"Referrer-Policy": "no-referrer"
+			}
+		});
+	});
 	/** Directory child file (GET — preview counts as download per product). */
 	app.get("/s/:token/file", async (c) => {
 		const clientIp = getClientIpFromHeaders({ get: (n) => c.req.header(n) ?? void 0 });
@@ -251,7 +356,12 @@ function registerSharePublicRoutes(app, service) {
 			expiresAt: record.expiresAt,
 			remainingViews,
 			valid: validation.valid,
-			directory: record.directory ?? null
+			directory: record.directory ?? null,
+			...record.kind === "note" ? {
+				sourceVersion: record.sourceVersion,
+				snapshotRevision: record.snapshotRevision,
+				attachmentCount: record.attachmentCount
+			} : {}
 		});
 	});
 	/** HEAD check. */
@@ -282,6 +392,17 @@ function registerSharePublicRoutes(app, service) {
 				"X-Content-Type-Options": "nosniff"
 			}
 		});
+		if (record.kind === "note") {
+			const placeholder = placeholderSvg(record.fileName, "text");
+			return new Response(placeholder, {
+				status: 200,
+				headers: {
+					"Content-Type": "image/svg+xml; charset=utf-8",
+					"Cache-Control": "public, max-age=60",
+					"X-Content-Type-Options": "nosniff"
+				}
+			});
+		}
 		scheduleThumbnail({
 			scope: "file",
 			token,
@@ -352,6 +473,7 @@ function registerSharePublicRoutes(app, service) {
 function registerShareRoutes(authenticated, deps) {
 	const { service } = deps;
 	const store = getShareStore(resolveShareConfig(service));
+	const noteShares = new NoteShareService(store, service.notesServiceInstance);
 	getSiteShareStore(resolveSiteShareConfig(service)).setCleanupHook((rec) => {
 		const dir = forgetStagedSite(rec.id);
 		if (dir) cleanupStagedSite(dir);
@@ -628,7 +750,13 @@ function registerShareRoutes(authenticated, deps) {
 				description: r.description ?? null,
 				fileSize: r.fileSize,
 				mimeType: r.mimeType,
-				directory: r.directory ?? null
+				directory: r.directory ?? null,
+				...r.kind === "note" ? {
+					sourceNoteId: r.sourceNoteId,
+					sourceVersion: r.sourceVersion,
+					snapshotRevision: r.snapshotRevision,
+					attachmentCount: r.attachmentCount
+				} : {}
 			};
 		});
 		return c.json({
@@ -646,11 +774,12 @@ function registerShareRoutes(authenticated, deps) {
 		const urlCtx = getShareUrlContext(service);
 		const resolved = resolveShareUrl(record.token, urlCtx);
 		const expired = Date.now() >= new Date(record.expiresAt).getTime();
+		const { token: _token, createdByTokenHash: _createdByTokenHash, ...safeRecord } = record;
+		if ("assetTicketSecret" in safeRecord) delete safeRecord.assetTicketSecret;
 		return c.json({
 			ok: true,
 			payload: {
-				...record,
-				token: void 0,
+				...safeRecord,
 				shareUrl: resolved.shareUrl,
 				lanUrl: resolved.lanUrl,
 				reachability: resolved.reachability,
@@ -660,10 +789,12 @@ function registerShareRoutes(authenticated, deps) {
 	});
 	authenticated.delete("/api/shares/:id", async (c) => {
 		const id = c.req.param("id");
+		const record = store.getById(id);
 		if (!store.revoke(id)) return c.json({
 			ok: false,
 			error: { message: "Not found" }
 		}, 404);
+		if (record?.kind === "note") await noteShares.removeArtifact(record.id);
 		return c.json({ ok: true });
 	});
 	authenticated.delete("/api/shares", async (c) => {
@@ -672,7 +803,9 @@ function registerShareRoutes(authenticated, deps) {
 			body = await c.req.json();
 		} catch {}
 		if (body.expired === true) {
+			const expiredNoteShares = store.getAllShares().filter((record) => record.kind === "note" && !record.revoked && Date.now() >= new Date(record.expiresAt).getTime());
 			const count = store.revokeExpired();
+			await Promise.all(expiredNoteShares.map((record) => noteShares.removeArtifact(record.id)));
 			return c.json({
 				ok: true,
 				payload: { revokedCount: count }
@@ -683,7 +816,9 @@ function registerShareRoutes(authenticated, deps) {
 			ok: false,
 			error: { message: "Provide ids array or expired: true" }
 		}, 400);
+		const noteRecords = ids.map((id) => store.getById(id)).filter((record) => record?.kind === "note");
 		const count = store.revokeMany(ids);
+		await Promise.all(noteRecords.map((record) => noteShares.removeArtifact(record.id)));
 		return c.json({
 			ok: true,
 			payload: { revokedCount: count }

package/dist/src/gateway/hono/routes/tunnel.js

@@ -4,12 +4,12 @@ import { loadTunnelState } from "../../../tunnel/tunnel-state.js";
 import { resolveReverseProxyPublicUrl } from "../../public-url.js";
 import { extractToken } from "../../auth.js";
 import { TUNNEL_CONSENT_REQUIRED_CODE, TunnelConsentError, assertTunnelMayStart, getTunnelConsentState } from "../../../tunnel/consent.js";
-import { getTunnelRegistrationSecretMeta, readTunnelRegistrationSecretFromConfigOnly, resolveTunnelBrokerUrl } from "../../../tunnel/env.js";
+import { TUNNEL_REGISTRATION_SECRET_REQUIRED_CODE, TunnelRegistrationSecretError, getTunnelRegistrationSecretMeta, readTunnelRegistrationSecretFromConfigOnly, resolveTunnelBrokerUrl } from "../../../tunnel/env.js";
 import { createPairingSecret, exchangePairingSecretOnce, getCachedPairingExchange } from "../../../tunnel/pairing.js";
 import { logTunnelAudit } from "../../../tunnel/tunnel-audit.js";
 import { getTunnelService, hashGatewayToken } from "../../../tunnel/tunnel-service.js";
 import { configureTunnelFromGatewayConfig } from "../../../tunnel/gateway-lifecycle.js";
-import { applyTunnelConsentToConfig, setTunnelEnabledInConfig } from "../../../tunnel/tunnel-config.js";
+import { applyTunnelConsentToConfig, mergeTunnelConfigPatch, setTunnelEnabledInConfig } from "../../../tunnel/tunnel-config.js";
 import { getClientIpFromHeaders } from "../../security/loopback.js";
 import { applyLanPairingGatewayPatch } from "../../../tunnel/enable-lan-pairing.js";
 import { consumeTunnelMutationLimit } from "../../../tunnel/tunnel-rate-limit.js";
@@ -17,6 +17,7 @@ import "../../../tunnel/index.js";
 import { buildMobileConnectUrlOrder, resolveMobilePairLanUrl, validateMobilePairBaseUrl } from "../../../tunnel/pair-url.js";
 import { buildMobilePairContext } from "../../../tunnel/pair-context.js";
 import { consumePairingExchangeFailLimit } from "../../../tunnel/pairing-rate-limit.js";
+import { provisionTunnelRegistrationKey } from "../../../tunnel/xopc-cloud-registration.js";
 //#region src/gateway/hono/routes/tunnel.ts
 init_public_url();
 async function configureTunnelFromService(deps, opts) {
@@ -28,6 +29,11 @@ function enrichTunnelStatus(config, status) {
 	const registrationSecret = getTunnelRegistrationSecretMeta(config, process.env, brokerUrl);
 	return {
 		...status,
+		config: {
+			...status.config,
+			autoStart: config.tunnel?.autoStart ?? false,
+			brokerUrl
+		},
 		consentRequired: consent.consentRequired,
 		consent: {
 			currentVersion: consent.currentVersion,
@@ -169,7 +175,6 @@ function registerTunnelRoutes(authenticated, deps) {
 	const tunnel = getTunnelService();
 	const tunnelMutationLimit = createTunnelMutationRateLimitMiddleware();
 	authenticated.get("/api/tunnel/pair/context", async (c) => {
-		await configureTunnelFromService(deps);
 		const config = deps.service.currentConfig;
 		const status = tunnel.getStatus();
 		const context = buildMobilePairContext({
@@ -222,7 +227,6 @@ function registerTunnelRoutes(authenticated, deps) {
 		});
 	});
 	authenticated.post("/api/tunnel/pair", tunnelMutationLimit, async (c) => {
-		await configureTunnelFromService(deps);
 		const token = requireGatewayToken(c);
 		if (!token) return c.json({ error: "Gateway token required" }, 401);
 		const { secret, expiresAt } = createPairingSecret();
@@ -314,7 +318,6 @@ function registerTunnelRoutes(authenticated, deps) {
 		});
 	});
 	authenticated.get("/api/tunnel/status", async (c) => {
-		await configureTunnelFromService(deps);
 		const config = deps.service.currentConfig;
 		return c.json(enrichTunnelStatus(config, tunnel.getStatus()));
 	});
@@ -343,6 +346,29 @@ function registerTunnelRoutes(authenticated, deps) {
 			}
 		});
 	});
+	authenticated.post("/api/tunnel/registration-key", tunnelMutationLimit, async (c) => {
+		const config = deps.service.currentConfig;
+		try {
+			const merged = mergeTunnelConfigPatch(config, { registrationSecret: await provisionTunnelRegistrationKey() });
+			if (merged.ok === false) return c.json({
+				ok: false,
+				error: merged.message
+			}, 400);
+			const saved = await deps.service.saveConfig(config);
+			if (!saved.saved) return c.json({
+				ok: false,
+				error: saved.error ?? "Failed to save tunnel registration key"
+			}, 500);
+			logTunnelAudit("tunnel.registration_authorized", { phase: "oauth_exchange" }, "Tunnel registration key created through XOPC OAuth");
+			return c.json({ ok: true });
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return c.json({
+				ok: false,
+				error: message
+			}, 502);
+		}
+	});
 	authenticated.post("/api/tunnel/start", tunnelMutationLimit, async (c) => {
 		await configureTunnelFromService(deps, { force: true });
 		const config = deps.service.currentConfig;
@@ -367,7 +393,12 @@ function registerTunnelRoutes(authenticated, deps) {
 		try {
 			const qr = await tunnel.start(port, token);
 			setTunnelEnabledInConfig(config, true);
-			await deps.service.saveConfig(config);
+			const saved = await deps.service.saveConfig(config);
+			if (!saved.saved) {
+				await tunnel.stop();
+				setTunnelEnabledInConfig(config, false);
+				return c.json({ error: saved.error ?? "Failed to save tunnel state" }, 500);
+			}
 			const status = tunnel.getStatus();
 			return c.json({
 				publicUrl: qr.publicUrl,
@@ -377,11 +408,18 @@ function registerTunnelRoutes(authenticated, deps) {
 			});
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
+			if (err instanceof TunnelRegistrationSecretError) return c.json({
+				error: message,
+				code: TUNNEL_REGISTRATION_SECRET_REQUIRED_CODE
+			}, 400);
 			return c.json({ error: message }, 500);
 		}
 	});
 	authenticated.post("/api/tunnel/stop", tunnelMutationLimit, async (c) => {
-		await configureTunnelFromService(deps);
+		await configureTunnelFromService(deps, {
+			force: true,
+			deferWellKnownFetch: true
+		});
 		const config = deps.service.currentConfig;
 		let release = false;
 		try {
@@ -391,14 +429,14 @@ function registerTunnelRoutes(authenticated, deps) {
 		}
 		const { released } = await tunnel.stop({ release });
 		setTunnelEnabledInConfig(config, false);
-		await deps.service.saveConfig(config);
+		const saved = await deps.service.saveConfig(config);
+		if (!saved.saved) return c.json({ error: saved.error ?? "Failed to save tunnel state" }, 500);
 		return c.json({
 			ok: true,
 			released
 		});
 	});
 	authenticated.get("/api/tunnel/qr", async (c) => {
-		await configureTunnelFromService(deps);
 		const port = deps.service.currentConfig.gateway.port ?? 18790;
 		const host = resolveGatewayEffectiveHost(deps.service.currentConfig);
 		if (!requireGatewayToken(c)) return c.json({ error: "Gateway token required" }, 401);
@@ -406,7 +444,6 @@ function registerTunnelRoutes(authenticated, deps) {
 		return c.json(qr);
 	});
 	authenticated.get("/api/tunnel/transport-status", async (c) => {
-		await configureTunnelFromService(deps);
 		return c.json({ transport: { tls: "broker_terminated" } });
 	});
 	/**

package/dist/src/gateway/hono/routes/voice.d.ts

@@ -1,12 +1,8 @@
 /**
  * Voice routes — POST /api/voice/transcriptions (multipart).
  *
- * The endpoints share one execution path that:
- *   1. Runs the configured STT provider and fallback chain
- *   2. Optionally runs LLM refine on the raw transcript
- *   3. Returns { raw, refined?, language }
- *
- * LLM refinement is opt-in through `voice.input.refinement`.
+ * Transcription returns the provider text immediately. Optional LLM cleanup
+ * uses a separate endpoint so it never delays the raw transcript.
  */
 import type { Hono } from 'hono';
 import type { AuthenticatedRouteDeps } from './deps.js';

package/dist/src/gateway/hono/routes/voice.js

@@ -493,14 +493,13 @@ function registerVoiceRoutes(authenticated, deps) {
 				fileName: input.fileName,
 				signal: c.req.raw.signal
 			});
-			const raw = result.text;
 			const detectedLanguage = result.language ?? input.language;
-			const refined = raw.trim() ? await refineTranscript(raw, config, c.req.raw.signal) : void 0;
+			const refinementAvailable = (config.voice?.input?.refinement?.mode ?? "off") !== "off";
 			return c.json({
 				ok: true,
 				payload: {
-					raw,
-					...refined ? { refined } : {},
+					text: result.text,
+					refinementAvailable,
 					...detectedLanguage ? { language: detectedLanguage } : {},
 					provider: result.provider,
 					attempts: result.attempts,
@@ -534,6 +533,23 @@ function registerVoiceRoutes(authenticated, deps) {
 			}, 502);
 		}
 	};
+	authenticated.post("/api/voice/transcriptions/refine", strictRateLimitMiddleware, async (c) => {
+		const body = await c.req.json().catch(() => null);
+		const text = typeof body?.text === "string" ? body.text.trim() : "";
+		if (!text) return c.json({
+			ok: false,
+			error: { message: "Missing transcript text" }
+		}, 400);
+		if (text.length > 2e4) return c.json({
+			ok: false,
+			error: { message: "Transcript text exceeds 20000 character limit" }
+		}, 413);
+		const refined = await refineTranscript(text, service.currentConfig, c.req.raw.signal);
+		return c.json({
+			ok: true,
+			payload: { text: refined ?? text }
+		});
+	});
 	/** Multipart endpoint used by browser and future native clients. */
 	authenticated.post("/api/voice/transcriptions", strictRateLimitMiddleware, async (c) => {
 		const contentLength = Number(c.req.header("content-length") ?? 0);