dsh-mobile 0.8.5 → 0.8.7

package/lib/index.mjs

@@ -1210,6 +1210,39 @@ function parseGatewayConfig(raw) {
 	});
 }
 // src/exec-file.ts
+/**
+* Longest stream text attached to a failed subprocess result.
+*
+* The text exists for diagnostics only: a caller decides which part is safe to
+* show. It is bounded here so a chatty child cannot turn one failure into an
+* unbounded buffer in every future consumer of that rejection.
+*/
+const MAX_SUBPROCESS_ERROR_STREAM_CHARS = 8192;
+function boundedStream(value) {
+	if (typeof value !== "string" || value === "") return void 0;
+	return value.length <= 8192 ? value : value.slice(0, MAX_SUBPROCESS_ERROR_STREAM_CHARS);
+}
+/**
+* Attach the captured streams to a subprocess failure, best effort.
+*
+* `execFile` reports a non-zero exit as an Error whose only text is the command
+* line with stderr merged into `message`; the raw stream strings are handed to
+* the callback and otherwise discarded, so a caller cannot read them from the
+* rejection. They are copied onto it when it accepts properties. A frozen,
+* exotic or primitive rejection value must keep `message` as its diagnostic
+* rather than turn one failure into a different error, so every write is
+* guarded and an existing property is never overwritten.
+*/
+function attachCapturedStreams(error, stdout, stderr) {
+	if (typeof error !== "object" || error === null) return;
+	const target = error;
+	try {
+		const capturedStderr = boundedStream(stderr);
+		const capturedStdout = boundedStream(stdout);
+		if (target.stderr === void 0 && capturedStderr !== void 0) target.stderr = capturedStderr;
+		if (target.stdout === void 0 && capturedStdout !== void 0) target.stdout = capturedStdout;
+	} catch {}
+}
 /** Capture both output streams even when a desktop host wraps execFile without Node's promisify metadata. */
 function execFileText(file, args, options = {}) {
 	return new Promise((resolve, reject) => {
@@ -1219,6 +1252,7 @@ function execFileText(file, args, options = {}) {
 			encoding: "utf8"
 		}, (error, stdout, stderr) => {
 			if (error !== null) {
+				attachCapturedStreams(error, stdout, stderr);
 				reject(error);
 				return;
 			}
@@ -2122,6 +2156,8 @@ function requestPathCategory(path) {
 		case "/mobile-access/events": return path;
 		default:
 			if (path.startsWith("/api/")) return "/api/*";
+			if (path.startsWith("/plugins/")) return "/plugins/*";
+			if (path.startsWith("/assets/")) return "/assets/*";
 			if (path.startsWith("/mobile-access/extensions/")) return "/mobile-access/extensions/*";
 			if (/^\/mobile-access\/compat-[a-f\d]{64}\.js$/u.test(path)) return "/mobile-access/compat.js";
 			if (path.startsWith("/mobile-access/")) return "/mobile-access/*";
@@ -3244,7 +3280,7 @@ function forwardableClose(code) {
 * @param upstreamCookie - gateway's signed upstream cookie; browser cookies are discarded.
 * @param options - resolved message, queue, and compression limits.
 * @param handshakeTimeoutMs - maximum handshake and close-handshake duration.
-* @returns fulfillment after both HTTP upgrades are accepted, or rejection before acceptance.
+* @returns the close handle after both HTTP upgrades are accepted, or rejection before acceptance.
 */
 function bridgeCompressedWebSocket(request, client, upstream, head, target, upstreamCookie, options, handshakeTimeoutMs) {
 	return new Promise((resolve, reject) => {
@@ -3433,7 +3469,7 @@ function bridgeCompressedWebSocket(request, client, upstream, head, target, upst
 						accepted = true;
 						clearTimeout(handshakeTimer);
 						incoming.resume();
-						resolve();
+						resolve({ close: beginClose });
 					});
 				} catch (error) {
 					stop(error instanceof Error ? error : /* @__PURE__ */ new Error("Client WebSocket upgrade failed"));
@@ -5703,6 +5739,7 @@ const MOBILE_PUSH_PREFERENCES_PATH = `${AUTH_PREFIX}/push/preferences`;
 const MOBILE_PUSH_DISABLE_PATH = `${AUTH_PREFIX}/push/disable`;
 const MOBILE_PUSH_TEST_PATH = `${AUTH_PREFIX}/push/test`;
 const MOBILE_PUSH_RESOLVE_PATH = `${AUTH_PREFIX}/push/resolve`;
+const BACKGROUND_EVENT_PATH = `${AUTH_PREFIX}/background-events`;
 const MOBILE_PUSH_PREFERENCE_KEYS = [
 	"question",
 	"plan",
@@ -6448,6 +6485,12 @@ function sanitizeRequestHeaders(request, upstream) {
 		const value = request.headers[name];
 		if (value !== void 0) headers[name] = value;
 	}
+	for (const name of Object.keys(request.headers)) {
+		const lower = name.toLowerCase();
+		if (!lower.startsWith("x-dsh-") || lower.startsWith("x-dsh-mobile-") || lower === "x-dsh-auth-token") continue;
+		const value = request.headers[name];
+		if (value !== void 0) headers[name] = Array.isArray(value) ? value[0] : value;
+	}
 	return headers;
 }
 const BLOCKED_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
@@ -7601,6 +7644,7 @@ var MobileAccessGateway = class {
 		const computerImage = request.method === "GET" && target.decodedPathname === `/mobile-access/computer-image`;
 		const workspaceDirectories = (request.method === "GET" || request.method === "POST") && target.decodedPathname === `/mobile-access/workspace-directories`;
 		const clientModules = target.decodedPathname === `${AUTH_PREFIX}/client-modules`;
+		const backgroundEvents = target.decodedPathname === BACKGROUND_EVENT_PATH;
 		const mobilePushRoute = [
 			MOBILE_PUSH_CONFIG_PATH,
 			MOBILE_PUSH_SUBSCRIPTION_PATH,
@@ -7634,7 +7678,7 @@ var MobileAccessGateway = class {
 			fallback: void 0,
 			digest: requestedCompatRevision
 		} : void 0;
-		if (customAsset === void 0 && requestedMobileBootBatch === void 0 && !computerImages && !computerImage && !workspaceDirectories && !clientModules && !mobilePushRoute && extensionTarget(target.decodedPathname) === void 0 && (target.decodedPathname === "/mobile-access" || target.decodedPathname.startsWith(`/mobile-access/`))) throw new HttpError(404, "not_found");
+		if (customAsset === void 0 && requestedMobileBootBatch === void 0 && !computerImages && !computerImage && !workspaceDirectories && !clientModules && !backgroundEvents && !mobilePushRoute && extensionTarget(target.decodedPathname) === void 0 && (target.decodedPathname === "/mobile-access" || target.decodedPathname.startsWith(`/mobile-access/`))) throw new HttpError(404, "not_found");
 		if (![
 			"GET",
 			"HEAD",
@@ -7675,6 +7719,11 @@ var MobileAccessGateway = class {
 			await this.handleMobilePushRequest(target, request, response, authorization);
 			return;
 		}
+		if (backgroundEvents) {
+			if (request.method !== "GET" || target.search !== "") throw new HttpError(request.method === "GET" ? 400 : 405, request.method === "GET" ? "bad_request" : "method_not_allowed");
+			this.openBackgroundEventStream(request, response, authorization);
+			return;
+		}
 		if (clientModules) {
 			if (target.search !== "") throw new HttpError(400, "bad_request");
 			if (request.method !== "GET" && request.method !== "POST") throw new HttpError(405, "method_not_allowed");
@@ -9415,6 +9464,54 @@ var MobileAccessGateway = class {
 		request.once("aborted", close);
 		response.once("close", close);
 	}
+	/**
+	* Native background notifications need only Host task and revocation events.
+	* They use the paired session cookie but no mobile document view, because the
+	* App has no live WebView while this stream is serving a suspended page.
+	*/
+	openBackgroundEventStream(request, response, authorization) {
+		const operation = this.allocateRequest(authorization, response, {});
+		let closed = false;
+		let heartbeat;
+		const close = () => {
+			if (closed) return;
+			closed = true;
+			if (heartbeat !== void 0) clearInterval(heartbeat);
+			this.taskEventListeners.delete(sendTask);
+			const deviceListeners = this.deviceEventListeners.get(authorization.deviceId);
+			deviceListeners?.delete(sendDevice);
+			if (deviceListeners?.size === 0) this.deviceEventListeners.delete(authorization.deviceId);
+			request.removeListener("aborted", close);
+			response.removeListener("close", close);
+			operation.release();
+		};
+		const sendTask = (payload) => {
+			if (closed || response.destroyed || response.writableEnded) return;
+			response.write(`event: task-notify\ndata: ${payload}\n\n`);
+		};
+		const sendDevice = (payload) => {
+			if (closed || response.destroyed || response.writableEnded) return;
+			response.write(`event: device-revoked\ndata: ${payload}\n\n`);
+		};
+		setSecurityHeaders(response, this.tlsEnabled);
+		response.writeHead(200, {
+			"Content-Type": "text/event-stream; charset=utf-8",
+			"Cache-Control": "no-store",
+			Connection: "keep-alive",
+			"X-Accel-Buffering": "no"
+		});
+		response.write("retry: 2000\n: ready\n\n");
+		this.taskEventListeners.add(sendTask);
+		const deviceListeners = this.deviceEventListeners.get(authorization.deviceId) ?? /* @__PURE__ */ new Set();
+		deviceListeners.add(sendDevice);
+		this.deviceEventListeners.set(authorization.deviceId, deviceListeners);
+		heartbeat = setInterval(() => {
+			if (!closed && !response.destroyed && !response.writableEnded) response.write(": heartbeat\n\n");
+		}, EXTENSION_EVENT_HEARTBEAT_MS);
+		heartbeat.unref();
+		request.once("aborted", close);
+		response.once("close", close);
+	}
 	async readUpgradeResponse(upstream, expectedAccept) {
 		return new Promise((resolve, reject) => {
 			let buffer = Buffer.alloc(0);
@@ -9528,9 +9625,31 @@ var MobileAccessGateway = class {
 			client.destroy();
 			upstream.destroy();
 		};
+		let closeCompressedBridge;
+		const finishGracefully = () => {
+			if (closeCompressedBridge !== void 0) closeCompressedBridge(1e3, "session expired");
+			else {
+				upstream.unpipe(client);
+				client.unpipe(upstream);
+				upstream.pause();
+				const sendCloseFrame = (socket) => {
+					if (socket.destroyed || !socket.writable) return;
+					try {
+						socket.write(Buffer.from([
+							136,
+							2,
+							3,
+							232
+						]));
+					} catch {}
+				};
+				sendCloseFrame(client);
+			}
+			setTimeout(closeBoth, 50).unref();
+		};
 		client.on("error", closeBoth);
 		upstream.on("error", closeBoth);
-		const timer = setTimeout(closeBoth, Math.max(1, authorization.expiresAt - Date.now()));
+		const timer = setTimeout(finishGracefully, Math.max(1, authorization.expiresAt - Date.now()));
 		timer.unref();
 		const record = Object.freeze({
 			...authorization,
@@ -9559,7 +9678,10 @@ var MobileAccessGateway = class {
 				const compressionTarget = new URL(this.config.upstreamOrigin.href);
 				compressionTarget.pathname = target.pathname;
 				compressionTarget.search = target.search;
-				await bridgeCompressedWebSocket(request, client, upstream, head, compressionTarget, upstreamCookie, this.config.websocketCompression, this.config.upstreamTimeoutMs);
+				const bridge = await bridgeCompressedWebSocket(request, client, upstream, head, compressionTarget, upstreamCookie, this.config.websocketCompression, this.config.upstreamTimeoutMs);
+				closeCompressedBridge = (code, reason) => {
+					bridge.close(code, reason);
+				};
 				return;
 			}
 			await new Promise((resolve, reject) => {
@@ -9903,6 +10025,26 @@ var MemoryDeviceStore = class {
 		return structuredClone(this.snapshot);
 	}
 };
+// src/mobile-push/service.ts
+/**
+* Small Cordis service exposed to trusted Host plugins. The provider owns the
+* runtime lifetime and all recipient, category, session, and expiry checks.
+*/
+var MobilePushService = class extends Service {
+	send;
+	constructor(ctx, send) {
+		super(ctx, "mobilePush");
+		this.send = send;
+	}
+	/**
+	* Queue a notification for enabled web-push recipients.
+	* @param input - Session, text, optional category and optional expiry.
+	* @returns The number of newly queued recipient deliveries and the applied expiry.
+	*/
+	async notify(input) {
+		return await this.send(input);
+	}
+};
 // src/managed-files.ts
 /** Refuse link-shaped ancestors inside an owned state root before accessing a child. */
 async function assertManagedParents(root, target, prefix) {
@@ -15961,6 +16103,79 @@ var IrohIdentityProbeError = class extends Error {
 function publicStatus$2(status) {
 	return Object.freeze({ ...status });
 }
+function diagnosticText(value, dataDir) {
+	const text = value.toString("utf8").replaceAll(dataDir, "<data-dir>").trim().replace(/\s+/gu, " ");
+	return text === "" ? void 0 : text.slice(0, IDENTITY_DIAGNOSTIC_MAX_BYTES);
+}
+/** The wrapper `tls-prepare` prints when it discards the underlying native cause. */
+const HOST_TLS_PREPARATION_FAILURE = "Error: host TLS preparation failed";
+/**
+* Whether the wrapper is the only explanation stderr carries.
+*
+* Compare lines, never the whole buffer: the probe collapses whitespace for
+* reporting, and a preceding warning or a CRLF terminator must not hide the
+* fact that no cause chain was printed. A `Caused by:` section means the
+* native explanation already reached us, so the extra host run cannot add
+* anything the caller does not already have.
+*/
+function isBareHostTlsPreparationFailure(value, dataDir) {
+	const lines = value.toString("utf8").replaceAll(dataDir, "<data-dir>").split(/\r?\n/gu).map((line) => line.trim()).filter((line) => line !== "");
+	return lines.includes(HOST_TLS_PREPARATION_FAILURE) && !lines.some((line) => /^Caused by:/u.test(line));
+}
+/**
+* Ask the host entry point for the cause chain when `tls-prepare` reports only
+* its top-level wrapper. The command is local-only and bounded; it never
+* downloads a component or enables relay/discovery.
+*/
+async function hostIdentityDiagnostic(executable, dataDir, launch, onSpawn) {
+	const args = [
+		"--lang",
+		"en",
+		"host",
+		"--data-dir",
+		dataDir,
+		"--local-only"
+	];
+	const child = launch === void 0 ? spawn(executable, args, {
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		windowsHide: true
+	}) : launch(executable, args);
+	onSpawn?.(child);
+	let stderrOutput = Buffer.alloc(0);
+	let settled = false;
+	let deadline;
+	return await new Promise((resolve) => {
+		const finish = (value) => {
+			if (settled) return;
+			settled = true;
+			if (deadline !== void 0) clearTimeout(deadline);
+			resolve(value);
+		};
+		deadline = setTimeout(() => {
+			terminateRemoteProcess(child).then(() => {
+				finish(diagnosticText(stderrOutput, dataDir));
+			}, () => {
+				finish(diagnosticText(stderrOutput, dataDir));
+			});
+		}, 5e3);
+		deadline.unref?.();
+		child.stderr?.on("data", (chunk) => {
+			const remaining = IDENTITY_DIAGNOSTIC_MAX_BYTES - stderrOutput.length;
+			if (remaining > 0) stderrOutput = Buffer.concat([stderrOutput, chunk.subarray(0, remaining)]);
+		});
+		child.once("error", () => {
+			finish(diagnosticText(stderrOutput, dataDir));
+		});
+		child.once("close", () => {
+			finish(diagnosticText(stderrOutput, dataDir));
+		});
+		child.stdin?.end();
+	});
+}
 /**
 * Prepare the sidecar's private identity/TLS state and resolve its endpoint.
 *
@@ -16030,6 +16245,15 @@ async function defaultResolveIdentity(executable, dataDir, options = {}) {
 			if (settled) return;
 			settled = true;
 			const probeDiagnostic = diagnostic();
+			if (code !== 0 && probeDiagnostic !== void 0 && isBareHostTlsPreparationFailure(stderrOutput, dataDir)) {
+				hostIdentityDiagnostic(executable, dataDir, options.launch, options.onSpawn).then((detail) => {
+					const resolvedDiagnostic = detail ?? probeDiagnostic;
+					reject(new IrohIdentityProbeError(/private (?:Windows )?data directory is not secure|private path ACL grants/iu.test(resolvedDiagnostic) ? "iroh_data_directory_insecure" : "iroh_identity_invalid", resolvedDiagnostic));
+				}, () => {
+					reject(new IrohIdentityProbeError("iroh_identity_invalid", probeDiagnostic));
+				});
+				return;
+			}
 			if (code !== 0 && probeDiagnostic !== void 0 && /private (?:Windows )?data directory is not secure|private path ACL grants/iu.test(probeDiagnostic)) {
 				reject(new IrohIdentityProbeError("iroh_data_directory_insecure", probeDiagnostic));
 				return;
@@ -16939,23 +17163,36 @@ function remoteSuffix(origin) {
 		return "地址格式无效";
 	}
 }
+/**
+* Read-only PowerShell that reports whether both managed LAN rules are usable.
+*
+* The verdict mirrors `windowsFirewallSetupScript`'s post-condition: enabled,
+* inbound, allow, and `Profile` exactly `Any`. A Domain/Private-scoped rule is
+* active only on those networks, so reporting it as ready would tell a user on
+* a Public network that nothing needs fixing. The script only reads: it never
+* enables, creates or deletes a rule, and the caller keeps its 3s budget.
+* @param port - managed LAN listener port the rules must cover.
+*/
+function windowsFirewallProbeScript(port) {
+	return [
+		"$specs = @(@{ Name = 'DSH Mobile HTTPS'; Protocol = 'TCP' }, @{ Name = 'DSH Mobile Discovery'; Protocol = 'UDP' })",
+		"$ready = $true",
+		"$specs | ForEach-Object {",
+		"  $spec = $_",
+		"  $rule = Get-NetFirewallRule -DisplayName $spec.Name -ErrorAction SilentlyContinue | Where-Object { $_.Enabled -eq 'True' -and $_.Direction -eq 'Inbound' -and $_.Action -eq 'Allow' -and $_.Profile -eq 'Any' } | Select-Object -First 1",
+		"  if ($null -eq $rule) { $ready = $false; return }",
+		"  $filters = @($rule | Get-NetFirewallPortFilter -ErrorAction SilentlyContinue)",
+		`  $matching = @($filters | Where-Object { $_.Protocol -eq $spec.Protocol -and ($_.LocalPort -eq 'Any' -or $_.LocalPort -eq '${String(port)}') })`,
+		"  if ($matching.Count -eq 0) { $ready = $false }",
+		"}",
+		"if ($ready) { 'ready' } else { 'missing' }"
+	].join("; ");
+}
 function defaultFirewallProbe(platform = process.platform) {
 	return async (port) => {
 		if (platform !== "win32") return { state: "not-applicable" };
 		if (port === void 0) return { state: "unknown" };
-		const script = [
-			"$specs = @(@{ Name = 'DSH Mobile HTTPS'; Protocol = 'TCP' }, @{ Name = 'DSH Mobile Discovery'; Protocol = 'UDP' })",
-			"$ready = $true",
-			"$specs | ForEach-Object {",
-			"  $spec = $_",
-			"  $rule = Get-NetFirewallRule -DisplayName $spec.Name -ErrorAction SilentlyContinue | Where-Object { $_.Enabled -eq 'True' -and $_.Direction -eq 'Inbound' -and $_.Action -eq 'Allow' } | Select-Object -First 1",
-			"  if ($null -eq $rule) { $ready = $false; return }",
-			"  $filters = @($rule | Get-NetFirewallPortFilter -ErrorAction SilentlyContinue)",
-			`  $matching = @($filters | Where-Object { $_.Protocol -eq $spec.Protocol -and ($_.LocalPort -eq 'Any' -or $_.LocalPort -eq '${String(port)}') })`,
-			"  if ($matching.Count -eq 0) { $ready = $false }",
-			"}",
-			"if ($ready) { 'ready' } else { 'missing' }"
-		].join("; ");
+		const script = windowsFirewallProbeScript(port);
 		try {
 			return { state: (await execFileText("powershell.exe", [
 				"-NoProfile",
@@ -22109,7 +22346,8 @@ function validSource(value) {
 		"lifetime",
 		"turn",
 		"callId",
-		"goal"
+		"goal",
+		"custom"
 	])) return false;
 	return [
 		value.sourceId,
@@ -22126,7 +22364,7 @@ function validSource(value) {
 		"live",
 		"projected",
 		"committed"
-	].includes(String(value.lifetime)) && (value.turn === void 0 || Number.isSafeInteger(value.turn)) && (value.callId === void 0 || typeof value.callId === "string") && (value.goal === void 0 || object(value.goal) && only(value.goal, ["id", "revision"]) && typeof value.goal.id === "string" && Number.isSafeInteger(value.goal.revision));
+	].includes(String(value.lifetime)) && (value.turn === void 0 || Number.isSafeInteger(value.turn)) && (value.callId === void 0 || typeof value.callId === "string") && (value.goal === void 0 || object(value.goal) && only(value.goal, ["id", "revision"]) && typeof value.goal.id === "string" && Number.isSafeInteger(value.goal.revision)) && (value.custom === void 0 || object(value.custom) && only(value.custom, ["title", "body"]) && typeof value.custom.title === "string" && value.custom.title.length > 0 && value.custom.title.length <= 80 && !/[\u0000-\u001f\u007f]/u.test(value.custom.title) && typeof value.custom.body === "string" && value.custom.body.length > 0 && value.custom.body.length <= 200 && !/[\u0000-\u001f\u007f]/u.test(value.custom.body));
 }
 function scopedCounts(rows, scope, maximum = 1024) {
 	const counts = /* @__PURE__ */ new Map();
@@ -22742,10 +22980,11 @@ function validateNavigate(navigate, category) {
 	if (typeof navigate !== "string" || !/^\/\?mobile-push=[A-Za-z0-9_-]{1,256}$/u.test(navigate)) throw new TypeError("push_navigation_invalid");
 }
 /** Build Apple's declarative Web Push schema with generic, locale-owned text. */
-function buildDeclarativePayload(category, locale, navigate, tag) {
+function buildDeclarativePayload(category, locale, navigate, tag, custom) {
 	validateNavigate(navigate, category);
 	if (!(locale in messages) || !(category in messages[locale]) || typeof tag !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/u.test(tag)) throw new TypeError("push_payload_invalid");
-	const [title, body] = messages[locale][category];
+	if (custom !== void 0 && (typeof custom.title !== "string" || custom.title.length === 0 || custom.title.length > 80 || typeof custom.body !== "string" || custom.body.length === 0 || custom.body.length > 200)) throw new TypeError("push_payload_invalid");
+	const [title, body] = custom === void 0 ? messages[locale][category] : [custom.title, custom.body];
 	const payload = JSON.stringify({
 		web_push: 8030,
 		notification: {
@@ -23085,6 +23324,12 @@ function sameKey(a, b) {
 function isPreferenceEnabled(preferences, category) {
 	return preferences[category] === true;
 }
+function notificationText(value, maximum, label) {
+	if (typeof value !== "string") throw new TypeError(`push_${label}_invalid`);
+	const text = value.trim().replace(/[\u0000-\u001f\u007f]+/gu, " ");
+	if (text.length === 0 || text.length > maximum) throw new TypeError(`push_${label}_invalid`);
+	return text;
+}
 function pendingHas(snapshot, intent) {
 	return snapshot.pending.some((item) => item.id === intent.id && sameKey(item.key, intent.key));
 }
@@ -23198,6 +23443,51 @@ var PushDelivery = class {
 			this.#kick();
 		});
 	}
+	/**
+	* Queue trusted Host-plugin text for every enabled web-push recipient that
+	* opted into the selected notification category. The source keeps its own
+	* short expiry; a restart may still retry it only inside that window.
+	*/
+	async notifyCustom(input) {
+		if (!this.#started || this.#closed || !this.#admitting) throw new Error("push_unavailable");
+		const sessionId = typeof input.sessionId === "string" ? input.sessionId.trim() : "";
+		if (sessionId === "" || sessionId.length > 4096) throw new TypeError("push_session_id_invalid");
+		const title = notificationText(input.title, 80, "title");
+		const body = notificationText(input.body, 200, "body");
+		const category = input.category ?? "response";
+		if (![
+			"question",
+			"plan",
+			"approval",
+			"response",
+			"goal",
+			"failure"
+		].includes(category)) throw new TypeError("push_category_invalid");
+		const now = this.#now();
+		const maximumExpiry = now + OUTCOME_TTL_MS;
+		if (input.expiresAt !== void 0 && (!Number.isSafeInteger(input.expiresAt) || input.expiresAt <= now)) throw new TypeError("push_expiry_invalid");
+		const expiresAt = Math.min(input.expiresAt ?? maximumExpiry, maximumExpiry);
+		if (!await this.#host.sessionExists(sessionId)) throw new Error("push_session_unavailable");
+		const source = {
+			sourceId: `custom:${randomUUID()}`,
+			sessionId,
+			targetSessionId: sessionId,
+			category,
+			createdAt: now,
+			expiresAt,
+			lifetime: "committed",
+			custom: {
+				title,
+				body
+			}
+		};
+		const queued = await this.#admit(source);
+		this.#kick();
+		return {
+			queued,
+			expiresAt
+		};
+	}
 	async resolve(owner, reference) {
 		if (this.#closed || !reference) return void 0;
 		let snapshot;
@@ -23237,14 +23527,15 @@ var PushDelivery = class {
 		this.#origins.clear();
 	}
 	async #admit(source) {
-		if (!this.#admitting || source.expiresAt <= this.#now()) return;
+		if (!this.#admitting || source.expiresAt <= this.#now()) return 0;
 		let eligible = false;
 		try {
-			eligible = this.#host.available && await this.#host.eligible(source);
+			eligible = source.custom === void 0 ? this.#host.available && await this.#host.eligible(source) : this.#host.available && await this.#host.sessionExists(source.sessionId);
 		} catch {
 			eligible = false;
 		}
-		if (!eligible || source.expiresAt <= this.#now()) return;
+		if (!eligible || source.expiresAt <= this.#now()) return 0;
+		let queued = 0;
 		for (const origin of this.#origins.values()) {
 			if (!origin.active || this.#closed) continue;
 			const devices = await this.#readAuthorized(origin);
@@ -23253,7 +23544,7 @@ var PushDelivery = class {
 			try {
 				snapshot = this.#registry.snapshot();
 			} catch {
-				return;
+				return queued;
 			}
 			const registrations = snapshot.registrations.filter((reg) => reg.scopeId === origin.scopeId && reg.origin === origin.origin && devices.has(reg.deviceId) && reg.enabled && reg.health === "ready" && isPreferenceEnabled(reg.preferences, source.category) && snapshot.keys?.fingerprint === reg.keyFingerprint);
 			if (registrations.length === 0) continue;
@@ -23282,6 +23573,7 @@ var PushDelivery = class {
 						attempts: 0,
 						nextAttemptAt: this.#now()
 					});
+					queued += 1;
 				}
 				return {
 					...clean,
@@ -23290,6 +23582,7 @@ var PushDelivery = class {
 			});
 		}
 		this.#kick();
+		return queued;
 	}
 	async #reconcileKnownScopes() {
 		let snapshot;
@@ -23474,7 +23767,7 @@ var PushDelivery = class {
 			await this.#removeIntent(intent);
 			return;
 		}
-		const payload = buildDeclarativePayload(intent.source.category, registration.locale, `/?mobile-push=${reference}`, intent.source.sourceId.replace(/[^A-Za-z0-9._:-]/gu, "_").slice(0, 128) || "push");
+		const payload = buildDeclarativePayload(intent.source.category, registration.locale, `/?mobile-push=${reference}`, intent.source.sourceId.replace(/[^A-Za-z0-9._:-]/gu, "_").slice(0, 128) || "push", intent.source.custom);
 		let result;
 		try {
 			result = await this.#sender.send({
@@ -23584,6 +23877,11 @@ var PushDelivery = class {
 	/** Maps the Host tri-state for durable-work decisions; boolean eligible() would collapse transient uncertainty into denial. */
 	async #sourceGuard(source) {
 		if (!this.#host.available) return "unverifiable";
+		if (source.custom !== void 0) try {
+			return await this.#host.sessionExists(source.sessionId) ? "allowed" : "denied";
+		} catch {
+			return "unverifiable";
+		}
 		let result;
 		try {
 			result = await this.#host.reconcile(source);
@@ -23937,6 +24235,10 @@ var PushGatewayCoordinator = class {
 			installationId
 		});
 	}
+	async notifyCustom(input) {
+		if (!this.host.available) throw new Error("push_unavailable");
+		return await this.delivery.notifyCustom(input);
+	}
 	async resolve(owner, reference) {
 		if (!this.host.available || !await this.authorize(owner, true)) return void 0;
 		return this.delivery.resolve(owner, reference);
@@ -24059,16 +24361,71 @@ const MAX_MANAGED_PORT = 65535;
 function assertManagedPort(port, name) {
 	if (!Number.isSafeInteger(port) || port < MIN_MANAGED_PORT || port > MAX_MANAGED_PORT) throw new Error(`${name} must be from ${String(MIN_MANAGED_PORT)} through ${String(MAX_MANAGED_PORT)}`);
 }
-function powerShellFailureDetail(error) {
+/** Longest failure detail carried in the thrown message. */
+const MAX_FAILURE_DETAIL_CHARS = 512;
+/**
+* Strip the elevated invocation and filesystem locations from PowerShell text.
+*
+* The launcher's stderr quotes the command it ran, including the base64
+* `-EncodedCommand` payload, and the elevated script quotes its own scratch
+* path. Neither helps an operator, and both can push the one useful line past
+* the length bound, so they are replaced before the detail is bounded.
+*/
+function redactPowerShellDetail(value) {
+	return value.replace(/EncodedCommand\s+\S+/giu, "EncodedCommand <redacted>").replace(/\b[A-Za-z0-9+/]{64,}={0,2}\b/gu, "<redacted>").replace(/(?<![A-Za-z])[A-Za-z]:[\\/][^\s'"]*/gu, "<path>");
+}
+/** Bounded, redacted detail for a failed elevated Windows operation. */
+function powerShellFailureDetail(error, innerError = "") {
 	if (!(error instanceof Error)) return "unknown failure";
-	const code = "code" in error && typeof error.code === "string" ? ` (${error.code})` : "";
-	const stderr = "stderr" in error && typeof error.stderr === "string" ? error.stderr.trim().replace(/\s+/gu, " ").slice(0, 512) : "";
-	return `${code}${stderr === "" ? "" : `: ${stderr}`}`;
+	const code = "code" in error && (typeof error.code === "string" || typeof error.code === "number") ? ` (${String(error.code)})` : "";
+	const detail = redactPowerShellDetail(innerError.trim() === "" && "stderr" in error && typeof error.stderr === "string" ? error.stderr : innerError).trim().replace(/\s+/gu, " ").slice(0, MAX_FAILURE_DETAIL_CHARS);
+	return `${code}${detail === "" ? "" : `: ${detail}`}`;
+}
+/** Default sink for a scratch directory that could not be removed. */
+function warnFirewallCleanupFailure(detail) {
+	process.emitWarning(`Windows firewall temporary cleanup failed (${detail})`, { code: "DSH_MOBILE_FIREWALL_CLEANUP_FAILED" });
+}
+/**
+* Remove the elevated helper's scratch directory without touching the run's outcome.
+*
+* The directory is created before elevation and removed in a `finally`, so a
+* cleanup failure must not replace the firewall error that explains the
+* failure, and must not fail a run that already succeeded. It stays observable
+* instead: the removal error's code is reported to the warning sink, whose own
+* failure is ignored for the same reason.
+* @param directory - scratch path created for this run.
+* @param options - injectable removal and warning sink for tests.
+*/
+async function discardFirewallScratch(directory, options = {}) {
+	const remove = options.remove ?? ((path) => rm(path, {
+		recursive: true,
+		force: true
+	}));
+	try {
+		await remove(directory);
+	} catch (error) {
+		const code = error !== null && typeof error === "object" && "code" in error && typeof error.code === "string" ? error.code : "unknown";
+		const warn = options.warn ?? warnFirewallCleanupFailure;
+		try {
+			warn(code);
+		} catch {}
+	}
 }
 async function runElevatedPowerShell(script) {
+	const temporary = await mkdtemp(join(tmpdir(), "dsh-mobile-firewall-"));
+	const errorFile = join(temporary, "error.log");
+	const wrapped = [
+		`$__dshMobileErrorFile = '${errorFile.replaceAll("'", "''")}'`,
+		"try {",
+		script,
+		"} catch {",
+		"  try { [IO.File]::WriteAllText($__dshMobileErrorFile, ($_ | Out-String)) } catch {}",
+		"  throw",
+		"}"
+	].join("\n");
 	const launch = [
 		"$ErrorActionPreference = 'Stop'; $process = Start-Process -FilePath 'powershell.exe' -Verb RunAs -WindowStyle Hidden -Wait -PassThru",
-		`  -ArgumentList @('-NoProfile','-NonInteractive','-EncodedCommand','${Buffer.from(script, "utf16le").toString("base64")}')`,
+		`  -ArgumentList @('-NoProfile','-NonInteractive','-EncodedCommand','${Buffer.from(wrapped, "utf16le").toString("base64")}')`,
 		"; exit $process.ExitCode"
 	].join(" ");
 	try {
@@ -24079,7 +24436,13 @@ async function runElevatedPowerShell(script) {
 			launch
 		], { windowsHide: true });
 	} catch (error) {
-		throw new Error(`Windows firewall operation failed${powerShellFailureDetail(error)}`, { cause: error });
+		let innerError = "";
+		try {
+			innerError = (await readFile(errorFile, "utf8")).replace(/^\uFEFF/u, "");
+		} catch {}
+		throw new Error(`Windows firewall operation failed${powerShellFailureDetail(error, innerError)}`, { cause: error });
+	} finally {
+		await discardFirewallScratch(temporary);
 	}
 }
 function firewallRuleScript(name, protocol, port) {
@@ -24094,7 +24457,7 @@ function firewallRuleScript(name, protocol, port) {
 		"    $rule | Get-NetFirewallAddressFilter | Set-NetFirewallAddressFilter -RemoteAddress LocalSubnet",
 		"  }",
 		"}",
-		`$verified = @(Get-NetFirewallRule -DisplayName '${name}' -Enabled True -Direction Inbound -Action Allow -Profile Any -ErrorAction Stop)`,
+		`$verified = @(Get-NetFirewallRule -DisplayName '${name}' -ErrorAction Stop | Where-Object { $_.Enabled -eq 'True' -and $_.Direction -eq 'Inbound' -and $_.Action -eq 'Allow' -and $_.Profile -eq 'Any' })`,
 		`$matchingPort = @($verified | Get-NetFirewallPortFilter | Where-Object { $_.Protocol -eq '${protocol}' -and $_.LocalPort -contains '${String(port)}' })`,
 		`$matchingAddress = @($verified | Get-NetFirewallAddressFilter | Where-Object { $_.RemoteAddress -contains 'LocalSubnet' })`,
 		`if ($verified.Count -eq 0 -or $matchingPort.Count -eq 0 -or $matchingAddress.Count -eq 0) { throw "DSH Mobile firewall rule '${name}' is not active with the expected scope" }`
@@ -24590,6 +24953,7 @@ async function apply(ctx, config) {
 		if (service === void 0) throw new Error("push_unavailable");
 		return service;
 	};
+	new MobilePushService(ctx, async (input) => (await requiredPushGatewayService()).notifyCustom(input));
 	const queueDeviceInvalidations = (scopeId, deviceIds) => {
 		let queued = pendingDeviceInvalidations.get(scopeId);
 		if (queued === void 0) pendingDeviceInvalidations.set(scopeId, queued = /* @__PURE__ */ new Set());
@@ -24664,6 +25028,11 @@ async function apply(ctx, config) {
 		async test(owner, installationId) {
 			await (await requiredPushGatewayService()).test(owner, installationId);
 		},
+		async notifyCustom(input) {
+			const service = await requiredPushGatewayService();
+			if (service.notifyCustom === void 0) throw new Error("push_unavailable");
+			return await service.notifyCustom(input);
+		},
 		async resolve(owner, reference) {
 			return (await requiredPushGatewayService()).resolve(owner, reference);
 		}
@@ -25999,6 +26368,6 @@ async function apply(ctx, config) {
 		};
 	}, "dsh-mobile: independent LAN and selectable remote providers with /mobile command");
 }
-export { AUTH_PREFIX, AccessController, AccessError, BlockedUpgradePathLog, BoundedRateLimiter, CERT_EXPIRING_DAYS, CLOUDFLARED_COMPONENT_RELEASE, CLOUDFLARED_COMPONENT_RELEASES, CPOLAR_COMPONENT_RELEASE, CPOLAR_COMPONENT_RELEASES, CSRF_COOKIE, CSRF_HEADER, ClientModuleConflictError, ClientModulePreferenceStore, CloudflaredComponentManager, CloudflaredController, CloudflaredTunnelStore, Config, CpolarComponentManager, DEFAULT_IROH_LOCAL_PORT, DEFAULT_ORIGIN_LISTEN_PORT, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, EXTENSION_LIMITS, FRP_ATTACH_DISCOVERY_PATH, FRP_ATTACH_LOCAL_DECLARATION, FRP_ATTACH_SELF_SIGNED_DECLARATION, FRP_ATTACH_VPS_DECLARATION, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FRP_DEFAULT_PROXY_NAME, FRP_DEFAULT_PUBLIC_PORT, FRP_RESERVED_PORTS, FrpComponentManager, FrpConfigStore, FrpController, IROH_COMPONENT_RELEASES, IROH_LEAF_RENEW_BEFORE_DAYS, IROH_LEAF_VALIDITY_DAYS, IROH_VERSION, IrohComponentManager, IrohController, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_PAIRING_DESCRIPTOR_BYTES, MAX_PAIRING_LIFETIME_MS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, MobileAccessGateway, MobileAccessGatewayController, MobileAccessService, MobileExtensionError, OriginConfigStore, OriginController, PAIRING_DESCRIPTOR_LOCAL_PORT, PAIRING_DESCRIPTOR_TYPE, PAIRING_DESCRIPTOR_VERSION, REMOTE_PROVIDERS, RequestTrustPolicy, SESSION_COOKIE, TASK_EVENT_DEBOUNCE_MS, TaskEventHub, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpAttachPlan, createFrpAttachTemplate, createFrpAttachTemplateParts, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, decodePairingDescriptor, encodePairingDescriptor, ensureFrpIngressCertificate, ensureIrohTls, evaluateCertificateLifetime, frpAttachVpsParts, frpIngressPaths, frpIngressSelfCheck, frpProxyName, inject, irohGatewayConfig, irohHostname, irohOrigin, irohTlsPaths, isCloudflaredRegistration, isFrpSelfSignedIngress, isGloballyRoutableIpv4, isLoopbackAddress, issueServerCertificate, mergeSavedCloudflaredTunnelSettings, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, originGatewayConfig, parseAuthority, parseCidr, parseCloudflaredOrigin, parseCloudflaredTunnelSettings, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseOriginSettings, parseRemoteProviderState, probeOriginCertificate, readCertificateRenewal, resolveAuthority, resolveFrpEntryTls, resolveFrpMode, resolveFrpPublicPort, resolveFrpVhostHttpPort, resolveHostExecution, rewriteMobileIndex, validateAttachSettings, validateCloudflaredTunnelHostname, validateCloudflaredTunnelPort, validateCloudflaredTunnelToken, validateFrpEntryTls, validateFrpMode, validateFrpProxyName, validateFrpPublicOrigin, validateFrpPublicPort, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateFrpVhostHttpPort, validateIrohOrigin, validateOriginAllowedCidrs, validateOriginListenHost, validateOriginListenPort, validateOriginPublicOrigin, validatePairingDescriptor, validateWebSocketPath, watchTaskCompletions };
+export { AUTH_PREFIX, AccessController, AccessError, BlockedUpgradePathLog, BoundedRateLimiter, CERT_EXPIRING_DAYS, CLOUDFLARED_COMPONENT_RELEASE, CLOUDFLARED_COMPONENT_RELEASES, CPOLAR_COMPONENT_RELEASE, CPOLAR_COMPONENT_RELEASES, CSRF_COOKIE, CSRF_HEADER, ClientModuleConflictError, ClientModulePreferenceStore, CloudflaredComponentManager, CloudflaredController, CloudflaredTunnelStore, Config, CpolarComponentManager, DEFAULT_IROH_LOCAL_PORT, DEFAULT_ORIGIN_LISTEN_PORT, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, EXTENSION_LIMITS, FRP_ATTACH_DISCOVERY_PATH, FRP_ATTACH_LOCAL_DECLARATION, FRP_ATTACH_SELF_SIGNED_DECLARATION, FRP_ATTACH_VPS_DECLARATION, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FRP_DEFAULT_PROXY_NAME, FRP_DEFAULT_PUBLIC_PORT, FRP_RESERVED_PORTS, FrpComponentManager, FrpConfigStore, FrpController, IROH_COMPONENT_RELEASES, IROH_LEAF_RENEW_BEFORE_DAYS, IROH_LEAF_VALIDITY_DAYS, IROH_VERSION, IrohComponentManager, IrohController, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_PAIRING_DESCRIPTOR_BYTES, MAX_PAIRING_LIFETIME_MS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, MobileAccessGateway, MobileAccessGatewayController, MobileAccessService, MobileExtensionError, MobilePushService, OriginConfigStore, OriginController, PAIRING_DESCRIPTOR_LOCAL_PORT, PAIRING_DESCRIPTOR_TYPE, PAIRING_DESCRIPTOR_VERSION, REMOTE_PROVIDERS, RequestTrustPolicy, SESSION_COOKIE, TASK_EVENT_DEBOUNCE_MS, TaskEventHub, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpAttachPlan, createFrpAttachTemplate, createFrpAttachTemplateParts, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, decodePairingDescriptor, encodePairingDescriptor, ensureFrpIngressCertificate, ensureIrohTls, evaluateCertificateLifetime, frpAttachVpsParts, frpIngressPaths, frpIngressSelfCheck, frpProxyName, inject, irohGatewayConfig, irohHostname, irohOrigin, irohTlsPaths, isCloudflaredRegistration, isFrpSelfSignedIngress, isGloballyRoutableIpv4, isLoopbackAddress, issueServerCertificate, mergeSavedCloudflaredTunnelSettings, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, originGatewayConfig, parseAuthority, parseCidr, parseCloudflaredOrigin, parseCloudflaredTunnelSettings, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseOriginSettings, parseRemoteProviderState, probeOriginCertificate, readCertificateRenewal, resolveAuthority, resolveFrpEntryTls, resolveFrpMode, resolveFrpPublicPort, resolveFrpVhostHttpPort, resolveHostExecution, rewriteMobileIndex, validateAttachSettings, validateCloudflaredTunnelHostname, validateCloudflaredTunnelPort, validateCloudflaredTunnelToken, validateFrpEntryTls, validateFrpMode, validateFrpProxyName, validateFrpPublicOrigin, validateFrpPublicPort, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateFrpVhostHttpPort, validateIrohOrigin, validateOriginAllowedCidrs, validateOriginListenHost, validateOriginListenPort, validateOriginPublicOrigin, validatePairingDescriptor, validateWebSocketPath, watchTaskCompletions };
 
 //# sourceMappingURL=index.mjs.map