@astralyn/sash 0.1.0

package/dist/sysproxy/windows.js

@@ -0,0 +1,216 @@
+import { windowsSystemExecutable } from "../process.js";
+import { formatHostPort, normalizeEnableOptions, parseProxyString, runCmd } from "./common.js";
+import { windowsSnapshot } from "./snapshot.js";
+import { DEFAULT_BYPASS_LIST, SYSTEM_PROXY_SNAPSHOT_VERSION } from "./types.js";
+const WIN_REG_PATH = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings";
+const REGISTRY_HEADERS = new Set([WIN_REG_PATH, WIN_REG_PATH.replace(/^HKCU/, "HKEY_CURRENT_USER")].map((header) => header.toLowerCase()));
+const MANAGED_VALUE_LINE = /^[^\S\r\n]*(ProxyEnable|ProxyServer|ProxyOverride|AutoConfigURL|AutoDetect)[^\S\r\n]+(REG_[A-Z0-9_]+)(?:[^\S\r\n]+(.*))?[^\S\r\n]*$/i;
+const MANAGED_VALUE_PREFIX = /^[^\S\r\n]*(?:ProxyEnable|ProxyServer|ProxyOverride|AutoConfigURL|AutoDetect)(?:[^\S\r\n]|$)/i;
+const GENERIC_REGISTRY_VALUE_LINE = /^[^\S\r\n]*.+?[^\S\r\n]+REG_[A-Z0-9_]+(?:[^\S\r\n]+.*)?[^\S\r\n]*$/i;
+export function formatWindowsBypass(list = DEFAULT_BYPASS_LIST) {
+    return list.join(";");
+}
+function emptyWindowsRegistryProxyValues() {
+    return {
+        proxyEnable: null,
+        proxyServer: null,
+        proxyOverride: null,
+        autoConfigUrl: null,
+        autoDetect: null,
+    };
+}
+function setWindowsRegistryProxyValue(values, seen, name, type, rawValue) {
+    if (seen.has(name)) {
+        throw new Error(`Invalid Windows registry output: duplicate ${name} value`);
+    }
+    seen.add(name);
+    if (name === "proxyenable" || name === "autodetect") {
+        if (type !== "REG_DWORD") {
+            throw new Error(`Invalid Windows registry output: ${name} must be REG_DWORD`);
+        }
+        const text = rawValue.trim();
+        if (!/^(?:0x[0-9a-f]+|\d+)$/i.test(text)) {
+            throw new Error(`Invalid Windows registry output: ${name} has an invalid DWORD value`);
+        }
+        const value = Number.parseInt(text, text.toLowerCase().startsWith("0x") ? 16 : 10);
+        if (!Number.isInteger(value) || value < 0 || value > 0xffff_ffff) {
+            throw new Error(`Invalid Windows registry output: ${name} is outside DWORD range`);
+        }
+        if (name === "proxyenable")
+            values.proxyEnable = value;
+        else
+            values.autoDetect = value;
+        return;
+    }
+    if (type !== "REG_SZ") {
+        throw new Error(`Invalid Windows registry output: ${name} must be REG_SZ`);
+    }
+    const value = parseProxyString(rawValue.replace(/\r$/, ""), name);
+    if (name === "proxyserver") {
+        values.proxyServer = value;
+    }
+    else if (name === "proxyoverride") {
+        values.proxyOverride = value;
+    }
+    else {
+        values.autoConfigUrl = value;
+    }
+}
+function parseManagedWindowsRegistryValue(line, values, seen) {
+    const match = line.match(MANAGED_VALUE_LINE);
+    if (!match)
+        return false;
+    const name = match[1]?.toLowerCase();
+    const type = match[2]?.toUpperCase();
+    if (!name || !type) {
+        throw new Error("Invalid Windows registry output: malformed managed value");
+    }
+    setWindowsRegistryProxyValue(values, seen, name, type, match[3] ?? "");
+    return true;
+}
+export function parseWindowsRegistryProxyValues(output) {
+    const lines = output.split(/\r\n?|\n/);
+    let headerIndex = 0;
+    while (headerIndex < lines.length && (lines[headerIndex] ?? "").trim().length === 0) {
+        headerIndex++;
+    }
+    if (!REGISTRY_HEADERS.has((lines[headerIndex] ?? "").trim().toLowerCase())) {
+        throw new Error("Invalid Windows registry output: missing Internet Settings registry header");
+    }
+    const values = emptyWindowsRegistryProxyValues();
+    const seen = new Set();
+    const headerText = (lines[headerIndex] ?? "").trim().toLowerCase();
+    for (let index = headerIndex + 1; index < lines.length; index++) {
+        const line = lines[index] ?? "";
+        if (line.trim().length === 0)
+            continue;
+        if (!line.startsWith(" ") && !line.startsWith("\t")) {
+            if (line.trim().toLowerCase().startsWith(`${headerText}\\`))
+                break;
+            throw new Error("Invalid Windows registry output: unexpected line in registry response");
+        }
+        if (parseManagedWindowsRegistryValue(line, values, seen))
+            continue;
+        if (MANAGED_VALUE_PREFIX.test(line)) {
+            throw new Error("Invalid Windows registry output: malformed managed value");
+        }
+        if (!GENERIC_REGISTRY_VALUE_LINE.test(line)) {
+            throw new Error("Invalid Windows registry output: unexpected line in registry response");
+        }
+    }
+    if (seen.size === 0) {
+        throw new Error("Invalid Windows registry output: missing managed proxy values");
+    }
+    return values;
+}
+export async function captureWindowsSnapshot(run = runCmd) {
+    const values = parseWindowsRegistryProxyValues(await run("reg.exe", ["query", WIN_REG_PATH]));
+    return {
+        version: SYSTEM_PROXY_SNAPSHOT_VERSION,
+        platform: "win32",
+        proxyEnable: values.proxyEnable,
+        proxyServer: values.proxyServer,
+        proxyOverride: values.proxyOverride,
+        autoConfigUrl: values.autoConfigUrl,
+        autoDetect: values.autoDetect,
+    };
+}
+async function refreshWindowsWinINet(run) {
+    const script = [
+        '$signature = @"',
+        '[DllImport("wininet.dll", SetLastError = true)]',
+        "public static extern bool InternetSetOption(IntPtr hInternet, int dwOption, IntPtr lpBuffer, int dwBufferLength);",
+        '"@',
+        "$type = Add-Type -MemberDefinition $signature -Name WinINet -Namespace Interop -PassThru -ErrorAction SilentlyContinue",
+        "if ($type) {",
+        "  [Interop.WinINet]::InternetSetOption([IntPtr]::Zero, 39, [IntPtr]::Zero, 0) | Out-Null",
+        "  [Interop.WinINet]::InternetSetOption([IntPtr]::Zero, 37, [IntPtr]::Zero, 0) | Out-Null",
+        "}",
+    ].join("\n");
+    try {
+        await run(windowsSystemExecutable("WindowsPowerShell/v1.0/powershell.exe"), [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            script,
+        ]);
+    }
+    catch {
+    }
+}
+function windowsSnapshotValue(snapshot, name) {
+    switch (name) {
+        case "ProxyEnable":
+            return snapshot.proxyEnable;
+        case "ProxyServer":
+            return snapshot.proxyServer;
+        case "ProxyOverride":
+            return snapshot.proxyOverride;
+        case "AutoConfigURL":
+            return snapshot.autoConfigUrl;
+        case "AutoDetect":
+            return snapshot.autoDetect;
+    }
+}
+async function deleteWindowsValue(name, run) {
+    try {
+        await run("reg.exe", ["delete", WIN_REG_PATH, "/v", name, "/f"]);
+    }
+    catch (err) {
+        const current = await captureWindowsSnapshot(run);
+        if (windowsSnapshotValue(current, name) !== null)
+            throw err;
+    }
+}
+async function applyWindowsValue(name, type, value, run) {
+    if (value === null) {
+        await deleteWindowsValue(name, run);
+        return;
+    }
+    await run("reg.exe", ["add", WIN_REG_PATH, "/v", name, "/t", type, "/d", String(value), "/f"]);
+}
+export async function applyWindowsSnapshot(value, run = runCmd) {
+    const snapshot = windowsSnapshot(value);
+    try {
+        await applyWindowsValue("AutoConfigURL", "REG_SZ", snapshot.autoConfigUrl, run);
+        await applyWindowsValue("ProxyServer", "REG_SZ", snapshot.proxyServer, run);
+        await applyWindowsValue("ProxyOverride", "REG_SZ", snapshot.proxyOverride, run);
+        await applyWindowsValue("ProxyEnable", "REG_DWORD", snapshot.proxyEnable, run);
+    }
+    finally {
+        await refreshWindowsWinINet(run);
+    }
+}
+export function createWindowsTarget(original, opts) {
+    windowsSnapshot(original);
+    const normalized = normalizeEnableOptions(opts);
+    return {
+        version: SYSTEM_PROXY_SNAPSHOT_VERSION,
+        platform: "win32",
+        proxyEnable: 1,
+        proxyServer: formatHostPort(normalized.host, normalized.port),
+        proxyOverride: formatWindowsBypass(normalized.bypass),
+        autoConfigUrl: null,
+        autoDetect: null,
+    };
+}
+export function windowsState(value) {
+    const snapshot = windowsSnapshot(value);
+    const enabled = snapshot.proxyEnable === 1;
+    if (enabled) {
+        return snapshot.proxyServer
+            ? { supported: true, enabled: true, server: snapshot.proxyServer }
+            : { supported: true, enabled: true, details: "manual proxy has no server" };
+    }
+    if (snapshot.autoConfigUrl || snapshot.autoDetect === 1) {
+        return {
+            supported: true,
+            enabled: true,
+            ...(snapshot.autoConfigUrl ? { server: snapshot.autoConfigUrl } : {}),
+            details: snapshot.autoConfigUrl
+                ? "automatic proxy configuration is enabled"
+                : "automatic proxy detection is enabled",
+        };
+    }
+    return { supported: true, enabled: false };
+}

package/dist/sysproxy.js

@@ -0,0 +1,8 @@
+export { isSystemProxySupported } from "./sysproxy/common.js";
+export { parseDarwinAutoProxySetting, parseDarwinProxySetting, parseDarwinServices, } from "./sysproxy/darwin.js";
+export { createSystemProxyBackend } from "./sysproxy/factory.js";
+export { parseGSettingsPort, parseGSettingsString } from "./sysproxy/gnome.js";
+export { createLegacyProxyCleanup, disableLegacySystemProxyIfOwned, } from "./sysproxy/legacy.js";
+export { isSystemProxySnapshot, parseSystemProxySnapshot } from "./sysproxy/snapshot.js";
+export { DEFAULT_BYPASS_LIST, SYSTEM_PROXY_SNAPSHOT_VERSION } from "./sysproxy/types.js";
+export { formatWindowsBypass, parseWindowsRegistryProxyValues, } from "./sysproxy/windows.js";

package/dist/system-proxy-manager.js

@@ -0,0 +1,460 @@
+import fs from "node:fs";
+import { errnoCode, errorMessage } from "./error-utils.js";
+import { atomicWriteFileSync } from "./fs-atomic.js";
+import { hasExactOwnKeys, isCanonicalIsoTimestamp, isPlainObject } from "./json-shape.js";
+import { sashLayout } from "./paths.js";
+import { withStateLock } from "./state-lock.js";
+import { createSystemProxyBackend, isSystemProxySupported, parseSystemProxySnapshot, } from "./sysproxy.js";
+const MAX_JOURNAL_BYTES = 256 * 1024;
+function journalError(message) {
+    return new Error(`Invalid system proxy journal: ${message}`);
+}
+function hasExactKeys(value, keys) {
+    if (!isPlainObject(value))
+        throw journalError("root must be a plain object");
+    if (!hasExactOwnKeys(value, keys))
+        throw journalError("root has unexpected fields");
+    return value;
+}
+function sameDarwinServiceCollection(a, b) {
+    if (a.platform !== "darwin" || b.platform !== "darwin")
+        return false;
+    if (a.services.length !== b.services.length)
+        return false;
+    return a.services.every((service, index) => service.service === b.services[index]?.service);
+}
+function journalSnapshotsHaveSameStructure(original, target) {
+    if (original.platform !== target.platform)
+        return false;
+    if (original.platform === "darwin" && target.platform === "darwin") {
+        return sameDarwinServiceCollection(original, target);
+    }
+    return true;
+}
+function parseCreatedAt(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 128) {
+        throw journalError("createdAt must be a non-empty ISO timestamp");
+    }
+    if (!isCanonicalIsoTimestamp(value)) {
+        throw journalError("createdAt must be a canonical ISO timestamp");
+    }
+    return value;
+}
+export function parseSystemProxyJournal(value) {
+    const record = hasExactKeys(value, [
+        "schemaVersion",
+        "phase",
+        "ownerPid",
+        "createdAt",
+        "original",
+        "target",
+    ]);
+    if (record.schemaVersion !== 1 && record.schemaVersion !== 2) {
+        throw journalError("schemaVersion must be 1 or 2");
+    }
+    if (record.phase !== "prepared" &&
+        record.phase !== "applied" &&
+        !(record.schemaVersion === 2 && record.phase === "restoring")) {
+        throw journalError("phase must be prepared, applied, or restoring");
+    }
+    if (typeof record.ownerPid !== "number" ||
+        !Number.isSafeInteger(record.ownerPid) ||
+        record.ownerPid <= 0) {
+        throw journalError("ownerPid must be a positive integer");
+    }
+    let original;
+    let target;
+    try {
+        original = parseSystemProxySnapshot(record.original);
+        target = parseSystemProxySnapshot(record.target);
+    }
+    catch (err) {
+        throw journalError(errorMessage(err));
+    }
+    if (!journalSnapshotsHaveSameStructure(original, target)) {
+        throw journalError("original and target have different platform structures");
+    }
+    return {
+        schemaVersion: 2,
+        phase: record.phase,
+        ownerPid: record.ownerPid,
+        createdAt: parseCreatedAt(record.createdAt),
+        original,
+        target,
+    };
+}
+function sameJournal(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function sameJournalOwnership(a, b) {
+    return (a.schemaVersion === b.schemaVersion &&
+        a.ownerPid === b.ownerPid &&
+        a.createdAt === b.createdAt &&
+        JSON.stringify(a.original) === JSON.stringify(b.original) &&
+        JSON.stringify(a.target) === JSON.stringify(b.target));
+}
+function combinedError(primary, recovery) {
+    return new Error(`${errorMessage(primary)}; conditional restoration failed: ${errorMessage(recovery)}`);
+}
+export class SystemProxyManager {
+    layout;
+    backend;
+    operationLockFile;
+    operationQueue = Promise.resolve();
+    inspectionGeneration = 0;
+    inspectionCache;
+    inspectionInFlight;
+    constructor(options = {}, ...unexpected) {
+        if (typeof options !== "object" ||
+            options === null ||
+            Array.isArray(options) ||
+            unexpected.length > 0 ||
+            "systemProxyStateFile" in options) {
+            throw new Error("SystemProxyManager requires an options object with layout and backend fields");
+        }
+        this.layout = options.layout ?? sashLayout();
+        this.backend = options.backend ?? createSystemProxyBackend();
+        if (!this.layout.systemProxyStateFile) {
+            throw new Error("System proxy journal requires a systemProxyStateFile path");
+        }
+        this.operationLockFile = `${this.layout.systemProxyStateFile}.lock`;
+    }
+    apply(opts) {
+        this.invalidateInspection();
+        return this.enqueue(async () => {
+            try {
+                await withStateLock(this.operationLockFile, { purpose: "apply system proxy", timeoutMs: 30_000 }, () => this.applyUnlocked(opts));
+            }
+            finally {
+                this.invalidateInspection();
+            }
+        });
+    }
+    release() {
+        this.invalidateInspection();
+        return this.enqueue(async () => {
+            try {
+                await withStateLock(this.operationLockFile, { purpose: "restore system proxy", timeoutMs: 30_000 }, () => this.recoverUnlocked());
+            }
+            finally {
+                this.invalidateInspection();
+            }
+        });
+    }
+    inspect(fresh = false) {
+        const generation = this.inspectionGeneration;
+        if (!fresh &&
+            this.inspectionCache?.generation === generation &&
+            this.inspectionCache.expiresAt > Date.now()) {
+            return Promise.resolve(this.inspectionCache.inspection);
+        }
+        if (this.inspectionInFlight?.generation === generation) {
+            return this.inspectionInFlight.promise;
+        }
+        const promise = this.enqueue(async () => {
+            const result = await this.inspectUncached();
+            if (result.journalStable && this.inspectionGeneration === generation) {
+                this.inspectionCache = {
+                    generation,
+                    expiresAt: Date.now() + 3000,
+                    inspection: result.inspection,
+                };
+            }
+            return result.inspection;
+        });
+        this.inspectionInFlight = { generation, promise };
+        const clearInFlight = () => {
+            if (this.inspectionInFlight?.generation === generation &&
+                this.inspectionInFlight.promise === promise) {
+                this.inspectionInFlight = undefined;
+            }
+        };
+        void promise.then(clearInFlight, clearInFlight);
+        return promise;
+    }
+    async isApplied() {
+        return (await this.inspect()).applied;
+    }
+    async getState() {
+        return (await this.inspect()).state;
+    }
+    invalidateInspection() {
+        this.inspectionGeneration += 1;
+        this.inspectionCache = undefined;
+    }
+    observeJournal() {
+        try {
+            return { kind: "read", journal: this.readJournal() };
+        }
+        catch (error) {
+            return { kind: "error", error };
+        }
+    }
+    sameJournalObservation(left, right) {
+        if (left.kind === "error" || right.kind === "error") {
+            return (left.kind === "error" &&
+                right.kind === "error" &&
+                errorMessage(left.error) === errorMessage(right.error));
+        }
+        if (!left.journal || !right.journal)
+            return left.journal === right.journal;
+        return sameJournal(left.journal, right.journal);
+    }
+    inspectionMessages(before, after, captureError) {
+        const messages = [];
+        const add = (error) => {
+            const message = errorMessage(error) || "unknown error";
+            if (!messages.includes(message))
+                messages.push(message);
+        };
+        if (before.kind === "error")
+            add(before.error);
+        if (after.kind === "error")
+            add(after.error);
+        if (!this.sameJournalObservation(before, after)) {
+            add(new Error("System proxy journal changed during inspection"));
+        }
+        if (captureError)
+            add(captureError.error);
+        return messages;
+    }
+    async inspectAttempt() {
+        const before = this.observeJournal();
+        let current;
+        let state;
+        try {
+            current = await this.captureCurrent();
+            state = this.backend.state(current);
+        }
+        catch (error) {
+            const after = this.observeJournal();
+            const messages = this.inspectionMessages(before, after, { caught: true, error });
+            const queryError = messages.join("; ");
+            return {
+                journalStable: this.sameJournalObservation(before, after),
+                inspection: {
+                    applied: false,
+                    state: {
+                        supported: this.backend.supported ?? isSystemProxySupported(),
+                        enabled: false,
+                        details: queryError,
+                    },
+                    appliedKnown: false,
+                    stateKnown: false,
+                    queryError,
+                },
+            };
+        }
+        const after = this.observeJournal();
+        const journalStable = this.sameJournalObservation(before, after);
+        const messages = this.inspectionMessages(before, after);
+        if (messages.length > 0) {
+            state.details = [state.details, ...messages].filter(Boolean).join("; ");
+        }
+        const journal = journalStable && before.kind === "read" && after.kind === "read" ? after.journal : undefined;
+        const appliedKnown = journalStable && messages.length === 0;
+        const queryError = messages.join("; ");
+        return {
+            journalStable,
+            inspection: {
+                applied: appliedKnown &&
+                    journal?.phase === "applied" &&
+                    this.backend.equivalent(current, journal.target),
+                state,
+                appliedKnown,
+                stateKnown: true,
+                ...(queryError ? { queryError } : {}),
+            },
+        };
+    }
+    async inspectUncached() {
+        const first = await this.inspectAttempt();
+        return first.journalStable ? first : this.inspectAttempt();
+    }
+    enqueue(operation) {
+        const next = this.operationQueue.then(operation, operation);
+        this.operationQueue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    readJournal() {
+        const file = this.layout.systemProxyStateFile;
+        let stats;
+        try {
+            stats = fs.lstatSync(file);
+        }
+        catch (err) {
+            if (errnoCode(err) === "ENOENT")
+                return undefined;
+            throw new Error(`Could not inspect system proxy journal ${file}: ${errorMessage(err)}`);
+        }
+        if (!stats.isFile()) {
+            throw new Error(`System proxy journal is not a regular file: ${file}`);
+        }
+        if (stats.size > MAX_JOURNAL_BYTES) {
+            throw new Error(`System proxy journal is too large: ${file}`);
+        }
+        let text;
+        try {
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch (err) {
+            if (errnoCode(err) === "ENOENT")
+                return undefined;
+            throw new Error(`Could not read system proxy journal ${file}: ${errorMessage(err)}`);
+        }
+        let document;
+        try {
+            document = JSON.parse(text);
+        }
+        catch (err) {
+            throw new Error(`System proxy journal is invalid: ${file}: ${errorMessage(err)}`);
+        }
+        try {
+            return parseSystemProxyJournal(document);
+        }
+        catch (err) {
+            throw new Error(`System proxy journal is invalid: ${file}: ${errorMessage(err)}`);
+        }
+    }
+    writeNewJournal(journal) {
+        const existing = this.readJournal();
+        if (existing) {
+            throw new Error(`System proxy journal already exists: ${this.layout.systemProxyStateFile}`);
+        }
+        const canonical = parseSystemProxyJournal(journal);
+        this.writeJournal(canonical);
+    }
+    writeJournal(journal) {
+        const text = `${JSON.stringify(journal, null, 2)}\n`;
+        if (Buffer.byteLength(text) > MAX_JOURNAL_BYTES) {
+            throw new Error(`System proxy journal exceeds its size limit: ${this.layout.systemProxyStateFile}`);
+        }
+        atomicWriteFileSync(this.layout.systemProxyStateFile, text, 0o600);
+    }
+    replaceJournal(expected, next) {
+        const existing = this.readJournal();
+        if (!existing || !sameJournal(existing, expected)) {
+            throw new Error(`System proxy journal changed while applying: ${this.layout.systemProxyStateFile}`);
+        }
+        const canonical = parseSystemProxyJournal(next);
+        this.writeJournal(canonical);
+    }
+    clearJournal(expected) {
+        const existing = this.readJournal();
+        if (!existing || !sameJournalOwnership(existing, expected)) {
+            throw new Error(`System proxy journal changed while restoring: ${this.layout.systemProxyStateFile}`);
+        }
+        try {
+            fs.unlinkSync(this.layout.systemProxyStateFile);
+        }
+        catch (err) {
+            if (errnoCode(err) === "ENOENT") {
+                throw new Error(`System proxy journal changed while restoring: ${this.layout.systemProxyStateFile}`);
+            }
+            throw new Error(`Could not remove system proxy journal: ${errorMessage(err)}`);
+        }
+    }
+    async captureCurrent() {
+        return parseSystemProxySnapshot(await this.backend.capture());
+    }
+    async applyUnlocked(opts) {
+        const previous = this.readJournal();
+        if (previous) {
+            const desiredTarget = parseSystemProxySnapshot(this.backend.createTarget(previous.original, opts));
+            const current = await this.captureCurrent();
+            if (previous.phase === "applied" &&
+                this.backend.equivalent(previous.target, desiredTarget) &&
+                this.backend.equivalent(current, previous.target)) {
+                return;
+            }
+            await this.restoreJournal(previous);
+        }
+        const original = await this.captureCurrent();
+        const target = parseSystemProxySnapshot(this.backend.createTarget(original, opts));
+        if (!journalSnapshotsHaveSameStructure(original, target)) {
+            throw new Error("System proxy backend produced a target with a different platform structure");
+        }
+        const prepared = {
+            schemaVersion: 2,
+            phase: "prepared",
+            ownerPid: process.pid,
+            createdAt: new Date().toISOString(),
+            original,
+            target,
+        };
+        this.writeNewJournal(prepared);
+        const beforeApply = await this.captureCurrent();
+        if (!this.backend.equivalent(beforeApply, original)) {
+            this.clearJournal(prepared);
+            throw new Error("System proxy settings changed while Sash was preparing ownership; refusing to overwrite them");
+        }
+        let activeJournal = prepared;
+        try {
+            await this.backend.apply(target);
+            const current = await this.captureCurrent();
+            if (!this.backend.equivalent(current, target)) {
+                throw new Error("System proxy target verification failed after apply");
+            }
+            const applied = { ...prepared, phase: "applied" };
+            this.replaceJournal(prepared, applied);
+            activeJournal = applied;
+        }
+        catch (err) {
+            try {
+                await this.restoreJournal(activeJournal);
+            }
+            catch (restoreErr) {
+                throw combinedError(err, restoreErr);
+            }
+            throw err;
+        }
+    }
+    async recoverUnlocked() {
+        const journal = this.readJournal();
+        if (!journal)
+            return;
+        await this.restoreJournal(journal);
+    }
+    async restoreJournal(journal) {
+        const current = await this.captureCurrent();
+        if (this.backend.equivalent(current, journal.original)) {
+            this.clearJournal(journal);
+            return;
+        }
+        const canRestore = this.backend.equivalent(current, journal.target) ||
+            ((journal.phase === "prepared" || journal.phase === "restoring") &&
+                this.backend.compatible(current, journal.original, journal.target));
+        if (!canRestore) {
+            throw new Error("System proxy journal refuses to restore because current settings were modified outside Sash");
+        }
+        const restoring = journal.phase === "restoring" ? journal : { ...journal, phase: "restoring" };
+        if (restoring !== journal)
+            this.replaceJournal(journal, restoring);
+        let applyResult = {
+            ok: true,
+        };
+        try {
+            await this.backend.apply(restoring.original);
+        }
+        catch (error) {
+            applyResult = { ok: false, error };
+        }
+        let restored;
+        try {
+            restored = await this.captureCurrent();
+        }
+        catch (err) {
+            const verificationError = new Error(`Could not verify system proxy restoration: ${errorMessage(err)}`);
+            throw applyResult.ok
+                ? verificationError
+                : combinedError(applyResult.error, verificationError);
+        }
+        if (!this.backend.equivalent(restored, restoring.original)) {
+            const verificationError = new Error("System proxy restoration verification failed");
+            throw applyResult.ok
+                ? verificationError
+                : combinedError(applyResult.error, verificationError);
+        }
+        this.clearJournal(restoring);
+    }
+}

package/dist/tun-guidance.js

@@ -0,0 +1,11 @@
+function quotePosix(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export function tunPrivilegeGuidance(context, options) {
+    const platform = options.platform ?? process.platform;
+    const prepare = context === "activation-rolled-back" ? 'Run "sash config set tun on" first. ' : "";
+    if (platform === "win32") {
+        return `${prepare}Open PowerShell as Administrator and run "sash restart". If SASH_HOME was explicitly customized, set the same value in that shell first. If Sash was already elevated, inspect the Core error log.`;
+    }
+    return `${prepare}Restart Sash with root privileges using the same data directory: sudo env SASH_HOME=${quotePosix(options.root)} "$(command -v sash)" restart. If Sash was already elevated, inspect the Core error log.`;
+}