@astralyn/sash 0.1.0

package/dist/settings-service.js

@@ -0,0 +1,242 @@
+import { commitManagedStateTransaction } from "./managed-state-transaction.js";
+import { ProfileConflictError, } from "./profile-service.js";
+import { sameSettings, validateSettingsCandidate } from "./settings.js";
+import { tunPrivilegeGuidance } from "./tun-guidance.js";
+export class SettingsInputError extends Error {
+}
+export class CoreUnhealthyError extends Error {
+}
+const CORE_SETTING_KEYS = ["mixedPort", "controller", "secret", "tun", "allowLan"];
+export class SettingsService {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async apply(patch) {
+        const previous = { ...this.options.getCommitted() };
+        let candidate;
+        try {
+            candidate = validateSettingsCandidate(mergePatch(previous, patch));
+        }
+        catch (err) {
+            throw new SettingsInputError(err.message);
+        }
+        const restartRequired = candidate.daemonPort !== previous.daemonPort;
+        const proxyChanged = candidate.systemProxy !== previous.systemProxy;
+        const coreChanged = CORE_SETTING_KEYS.some((key) => candidate[key] !== previous[key]);
+        const daemonChanged = restartRequired || candidate.daemonSecret !== previous.daemonSecret;
+        let committed = previous;
+        if (coreChanged || daemonChanged) {
+            const staged = { ...candidate, systemProxy: previous.systemProxy };
+            committed = coreChanged
+                ? await this.commitCoreChange(previous, staged, {
+                    verifyTun: candidate.tun && !previous.tun,
+                })
+                : await this.commitSettingsOnly(previous, staged);
+        }
+        if (proxyChanged) {
+            committed = await this.commitSystemProxy(committed, candidate);
+        }
+        return { settings: committed, restartRequired };
+    }
+    async applyFileSettings(next) {
+        const current = this.options.getCommitted();
+        const patch = {};
+        if (next.mixedPort !== current.mixedPort)
+            patch.mixedPort = next.mixedPort;
+        if (next.controller !== current.controller)
+            patch.controller = next.controller;
+        if (next.secret !== current.secret)
+            patch.secret = next.secret;
+        if (next.tun !== current.tun)
+            patch.tun = next.tun;
+        if (next.allowLan !== current.allowLan)
+            patch.allowLan = next.allowLan;
+        if (next.systemProxy !== current.systemProxy)
+            patch.systemProxy = next.systemProxy;
+        if (next.daemonPort !== current.daemonPort)
+            patch.daemonPort = next.daemonPort;
+        if (next.daemonSecret !== current.daemonSecret)
+            patch.daemonSecret = next.daemonSecret;
+        return this.apply(patch);
+    }
+    async commitSettingsOnly(previous, candidate) {
+        return this.options.commit("update daemon settings", async () => {
+            this.assertCurrent(previous);
+            this.options.setRuntime(candidate);
+            try {
+                await commitManagedStateTransaction(this.options.layout, { settings: candidate }, undefined);
+            }
+            catch (err) {
+                this.options.setRuntime(previous);
+                throw err;
+            }
+            this.options.setCommitted(candidate);
+            return candidate;
+        });
+    }
+    async commitCoreChange(previous, candidate, opts) {
+        for (let attempt = 0;; attempt += 1) {
+            const prepared = await this.options.profiles.prepareActiveConfig(candidate, previous);
+            let retryableProfileConflict;
+            let callbackEntered = false;
+            try {
+                return await this.options.commit("update settings", async () => {
+                    this.assertCurrent(previous);
+                    try {
+                        return await this.options.profiles.withPreparedActivePublication(prepared, async (publication) => {
+                            callbackEntered = true;
+                            return this.commitCoreSettings(previous, candidate, opts, publication);
+                        });
+                    }
+                    catch (err) {
+                        if (err instanceof ProfileConflictError && !callbackEntered) {
+                            retryableProfileConflict = err;
+                        }
+                        throw err;
+                    }
+                });
+            }
+            catch (err) {
+                if (err !== retryableProfileConflict || attempt >= 1)
+                    throw err;
+            }
+        }
+    }
+    async commitSystemProxy(previous, candidate) {
+        if (!candidate.systemProxy) {
+            return this.options.commit("disable system proxy", async () => {
+                this.assertCurrent(previous);
+                this.options.setRuntime(candidate);
+                try {
+                    await commitManagedStateTransaction(this.options.layout, { settings: candidate }, undefined);
+                }
+                catch (err) {
+                    this.options.setRuntime(previous);
+                    throw err;
+                }
+                this.options.setCommitted(candidate);
+                if (this.options.lifecycle)
+                    await this.options.lifecycle.reconcileSystemProxy();
+                else
+                    await this.options.releaseSystemProxy?.();
+                return candidate;
+            });
+        }
+        const core = await this.options.supervisor?.status();
+        if (!core?.running || !core.healthy) {
+            throw new CoreUnhealthyError("Cannot enable system proxy: core is not healthy");
+        }
+        return this.options.commit("enable system proxy", async () => {
+            this.assertCurrent(previous);
+            this.options.setRuntime(candidate);
+            try {
+                await commitManagedStateTransaction(this.options.layout, {
+                    settings: candidate,
+                    applyRuntime: () => this.requireLifecycle().reconcileSystemProxy(),
+                }, undefined);
+                this.options.setCommitted(candidate);
+                return candidate;
+            }
+            catch (err) {
+                this.options.setRuntime(previous);
+                try {
+                    await this.requireLifecycle().reconcileSystemProxy();
+                }
+                catch (rollback) {
+                    throw new Error(`${err.message}; system proxy rollback failed: ${rollback.message}`);
+                }
+                throw err;
+            }
+        });
+    }
+    async commitCoreSettings(previous, candidate, opts, publication) {
+        const wasRunning = this.options.supervisor?.isRunning() ?? false;
+        this.options.setRuntime(candidate);
+        try {
+            await commitManagedStateTransaction(this.options.layout, {
+                ...(publication.index ? { index: publication.index } : {}),
+                ...(publication.profile
+                    ? {
+                        profile: {
+                            id: publication.profile.id,
+                            yamlText: publication.profile.yamlText,
+                        },
+                    }
+                    : {}),
+                config: publication.config,
+                settings: candidate,
+                reloadRuntime: false,
+                applyRuntime: async () => {
+                    if (!wasRunning)
+                        return;
+                    const result = await this.requireLifecycle().restart();
+                    if (opts.verifyTun && result.tunActive !== true) {
+                        throw new Error(result.tunActive === false
+                            ? `TUN did not become active. ${tunPrivilegeGuidance("activation-rolled-back", { root: this.options.layout.root })}`
+                            : `TUN activation could not be verified through the Core controller. ${tunPrivilegeGuidance("activation-rolled-back", { root: this.options.layout.root })}`);
+                    }
+                },
+            }, undefined);
+            this.options.setCommitted(candidate);
+            return candidate;
+        }
+        catch (err) {
+            this.options.setRuntime(previous);
+            const rollbackErrors = [];
+            try {
+                await this.options.profiles.commitPreparedActiveReload(publication.rollback, {
+                    reloadRuntime: false,
+                    boundary: "already-held",
+                });
+            }
+            catch (rollback) {
+                rollbackErrors.push(`config rollback failed: ${rollback.message}`);
+            }
+            if (wasRunning) {
+                try {
+                    if (this.options.supervisor?.isRunning())
+                        await this.requireLifecycle().restart();
+                    else
+                        await this.requireLifecycle().start();
+                }
+                catch (rollback) {
+                    rollbackErrors.push(`runtime rollback failed: ${rollback.message}`);
+                }
+            }
+            if (rollbackErrors.length)
+                throw new Error(`${err.message}; ${rollbackErrors.join("; ")}`);
+            throw err;
+        }
+    }
+    requireLifecycle() {
+        if (!this.options.lifecycle)
+            throw new Error("No runtime lifecycle is available for this settings mutation");
+        return this.options.lifecycle;
+    }
+    assertCurrent(previous) {
+        if (!sameSettings(this.options.getCommitted(), previous)) {
+            throw new Error("Settings changed while preparing configuration");
+        }
+    }
+}
+function mergePatch(previous, patch) {
+    const candidate = { ...previous };
+    if (patch.mixedPort !== undefined)
+        candidate.mixedPort = patch.mixedPort;
+    if (patch.controller !== undefined)
+        candidate.controller = patch.controller;
+    if (patch.secret !== undefined)
+        candidate.secret = patch.secret;
+    if (patch.tun !== undefined)
+        candidate.tun = patch.tun;
+    if (patch.allowLan !== undefined)
+        candidate.allowLan = patch.allowLan;
+    if (patch.systemProxy !== undefined)
+        candidate.systemProxy = patch.systemProxy;
+    if (patch.daemonPort !== undefined)
+        candidate.daemonPort = patch.daemonPort;
+    if (patch.daemonSecret !== undefined)
+        candidate.daemonSecret = patch.daemonSecret;
+    return candidate;
+}

package/dist/settings.js

@@ -0,0 +1,314 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { atomicWriteFileSync } from "./fs-atomic.js";
+import { isPlainObject } from "./json-shape.js";
+import { sashLayout } from "./paths.js";
+import { acquireStateLockSync } from "./state-lock.js";
+const PUBLIC_SETTINGS_KEYS = [
+    "mixedPort",
+    "controller",
+    "tun",
+    "allowLan",
+    "daemonPort",
+    "systemProxy",
+];
+function exhaustiveKeys() {
+    return (keys) => keys;
+}
+const CANONICAL_SETTINGS_KEYS = exhaustiveKeys()([
+    "schemaVersion",
+    "subscriptionUrl",
+    "mixedPort",
+    "controller",
+    "secret",
+    "tun",
+    "allowLan",
+    "daemonPort",
+    "daemonSecret",
+    "systemProxy",
+]);
+const LEGACY_SETTINGS_KEYS = ["coreVersion", "uiVersion"];
+const ACCEPTED_SETTINGS_KEYS = new Set([
+    ...CANONICAL_SETTINGS_KEYS,
+    ...LEGACY_SETTINGS_KEYS,
+]);
+export function publicSettings(settings) {
+    return {
+        mixedPort: settings.mixedPort,
+        controller: settings.controller,
+        tun: settings.tun,
+        allowLan: settings.allowLan,
+        daemonPort: settings.daemonPort,
+        systemProxy: settings.systemProxy,
+    };
+}
+export function sameSettings(a, b) {
+    return CANONICAL_SETTINGS_KEYS.every((key) => a[key] === b[key]);
+}
+export const DEFAULT_SETTINGS = {
+    schemaVersion: 1,
+    mixedPort: 7890,
+    controller: "127.0.0.1:9090",
+    secret: "",
+    tun: false,
+    allowLan: false,
+    daemonPort: 19090,
+    daemonSecret: "",
+    systemProxy: false,
+};
+function hasOwn(object, key) {
+    return Object.hasOwn(object, key);
+}
+function invalidSettings(file, message) {
+    return new Error(`Settings are invalid: ${file}: ${message}`);
+}
+function readRequiredField(source, key, defaultValue, allowMissing, file, parse) {
+    if (!hasOwn(source, key)) {
+        if (!allowMissing)
+            throw invalidSettings(file, `${key} is required`);
+        return { value: defaultValue, missing: true };
+    }
+    const value = source[key];
+    if (value === null)
+        throw invalidSettings(file, `${key} must not be null`);
+    return { value: parse(value, key, file), missing: false };
+}
+function readOptionalString(source, key, file) {
+    if (!hasOwn(source, key))
+        return undefined;
+    const value = source[key];
+    if (value === null)
+        throw invalidSettings(file, `${key} must not be null`);
+    return parseString(value, key, file);
+}
+function parseString(value, key, file) {
+    if (typeof value !== "string")
+        throw invalidSettings(file, `${key} must be a string`);
+    return value;
+}
+function hasSecretControlCharacter(secret) {
+    for (const char of secret) {
+        const code = char.charCodeAt(0);
+        if (code <= 31 || code === 127)
+            return true;
+    }
+    return false;
+}
+function parseSecret(value, key, file) {
+    const secret = parseString(value, key, file);
+    if (!secret.trim())
+        throw invalidSettings(file, `${key} must not be blank`);
+    if (hasSecretControlCharacter(secret)) {
+        throw invalidSettings(file, `${key} must not contain control characters`);
+    }
+    return secret;
+}
+function parseBoolean(value, key, file) {
+    if (typeof value !== "boolean")
+        throw invalidSettings(file, `${key} must be a boolean`);
+    return value;
+}
+function parsePort(value, key, file) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 65_535) {
+        throw invalidSettings(file, `${key} must be an integer from 1 to 65535`);
+    }
+    return value;
+}
+function parseController(value, key, file) {
+    const controller = parseString(value, key, file);
+    const address = parseControllerAddress(controller);
+    if (!address) {
+        throw invalidSettings(file, `${key} must be a loopback host:port controller address`);
+    }
+    return address.canonical;
+}
+function validateSettingsRelations(settings, file) {
+    const controller = parseControllerAddress(settings.controller);
+    if (!controller) {
+        throw invalidSettings(file, "controller must be a loopback host:port controller address");
+    }
+    const ports = [
+        ["mixedPort", settings.mixedPort],
+        ["daemonPort", settings.daemonPort],
+        ["controller", controller.port],
+    ];
+    for (let i = 0; i < ports.length; i++) {
+        for (let j = i + 1; j < ports.length; j++) {
+            if (ports[i]?.[1] === ports[j]?.[1]) {
+                throw invalidSettings(file, `${ports[i]?.[0]} and ${ports[j]?.[0]} must use different ports`);
+            }
+        }
+    }
+}
+function parseSchemaVersion(source, allowMissing, file) {
+    if (!hasOwn(source, "schemaVersion")) {
+        if (!allowMissing)
+            throw invalidSettings(file, "schemaVersion is required");
+        return { value: 0, missing: true };
+    }
+    const value = source.schemaVersion;
+    if (value === null)
+        throw invalidSettings(file, "schemaVersion must not be null");
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw invalidSettings(file, "schemaVersion must be an integer");
+    }
+    if (value === 0 || value === 1)
+        return { value, missing: false };
+    if (value > 1) {
+        throw invalidSettings(file, `schemaVersion ${value} is from a future version`);
+    }
+    throw invalidSettings(file, "schemaVersion must be 0 or 1");
+}
+function parseSettings(document, file, allowMissing) {
+    if (!isPlainObject(document)) {
+        throw invalidSettings(file, "JSON root must be a plain object");
+    }
+    for (const key of Object.keys(document)) {
+        if (!ACCEPTED_SETTINGS_KEYS.has(key)) {
+            throw invalidSettings(file, `unknown field ${JSON.stringify(key)}`);
+        }
+    }
+    const schemaVersion = parseSchemaVersion(document, allowMissing, file);
+    const subscriptionUrl = readOptionalString(document, "subscriptionUrl", file);
+    const mixedPort = readRequiredField(document, "mixedPort", DEFAULT_SETTINGS.mixedPort, allowMissing, file, parsePort);
+    const controller = readRequiredField(document, "controller", DEFAULT_SETTINGS.controller, allowMissing, file, parseController);
+    const secret = readRequiredField(document, "secret", DEFAULT_SETTINGS.secret, allowMissing, file, parseSecret);
+    const tun = readRequiredField(document, "tun", DEFAULT_SETTINGS.tun, allowMissing, file, parseBoolean);
+    const allowLan = readRequiredField(document, "allowLan", DEFAULT_SETTINGS.allowLan, allowMissing, file, parseBoolean);
+    const daemonPort = readRequiredField(document, "daemonPort", DEFAULT_SETTINGS.daemonPort, allowMissing, file, parsePort);
+    const daemonSecret = readRequiredField(document, "daemonSecret", DEFAULT_SETTINGS.daemonSecret, allowMissing, file, parseSecret);
+    const systemProxy = readRequiredField(document, "systemProxy", DEFAULT_SETTINGS.systemProxy, allowMissing, file, parseBoolean);
+    let needsRewrite = schemaVersion.missing ||
+        schemaVersion.value === 0 ||
+        mixedPort.missing ||
+        controller.missing ||
+        controller.value !== document.controller ||
+        secret.missing ||
+        tun.missing ||
+        allowLan.missing ||
+        daemonPort.missing ||
+        daemonSecret.missing ||
+        systemProxy.missing;
+    for (const key of LEGACY_SETTINGS_KEYS) {
+        if (!hasOwn(document, key))
+            continue;
+        const value = document[key];
+        if (value === null)
+            throw invalidSettings(file, `${key} must not be null`);
+        parseString(value, key, file);
+        needsRewrite = true;
+    }
+    const normalizedSecret = secret.missing ? generateSecret() : secret.value;
+    const normalizedDaemonSecret = daemonSecret.missing ? generateSecret() : daemonSecret.value;
+    const settings = {
+        schemaVersion: 1,
+        mixedPort: mixedPort.value,
+        controller: controller.value,
+        secret: normalizedSecret,
+        tun: tun.value,
+        allowLan: allowLan.value,
+        daemonPort: daemonPort.value,
+        daemonSecret: normalizedDaemonSecret,
+        systemProxy: systemProxy.value,
+    };
+    if (subscriptionUrl !== undefined)
+        settings.subscriptionUrl = subscriptionUrl;
+    validateSettingsRelations(settings, file);
+    return { settings, needsRewrite };
+}
+function readSettingsFile(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { exists: false, document: {} };
+        }
+        throw err;
+    }
+    try {
+        return { exists: true, document: JSON.parse(text) };
+    }
+    catch (err) {
+        throw new Error(`Settings file is invalid JSON: ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function canonicalSettings(settings) {
+    const canonical = {
+        schemaVersion: 1,
+        mixedPort: settings.mixedPort,
+        controller: settings.controller,
+        secret: settings.secret,
+        tun: settings.tun,
+        allowLan: settings.allowLan,
+        daemonPort: settings.daemonPort,
+        daemonSecret: settings.daemonSecret,
+        systemProxy: settings.systemProxy,
+    };
+    if (settings.subscriptionUrl !== undefined)
+        canonical.subscriptionUrl = settings.subscriptionUrl;
+    return canonical;
+}
+function writeCanonicalSettings(settings, layout) {
+    atomicWriteFileSync(layout.settingsFile, `${JSON.stringify(canonicalSettings(settings), null, 2)}\n`);
+}
+function loadSettingsUnlocked(layout) {
+    const source = readSettingsFile(layout.settingsFile);
+    const parsed = parseSettings(source.document, layout.settingsFile, true);
+    if (!source.exists || parsed.needsRewrite) {
+        writeCanonicalSettings(parsed.settings, layout);
+    }
+    return parsed.settings;
+}
+export function generateSecret() {
+    return crypto.randomBytes(24).toString("hex");
+}
+export function loadSettings(layout = sashLayout()) {
+    const lease = acquireStateLockSync(layout.settingsLockFile, { purpose: "settings" });
+    try {
+        return loadSettingsUnlocked(layout);
+    }
+    finally {
+        lease.release();
+    }
+}
+export function saveSettings(settings, layout = sashLayout()) {
+    const lease = acquireStateLockSync(layout.settingsLockFile, { purpose: "settings" });
+    try {
+        const parsed = parseSettings(settings, layout.settingsFile, false);
+        writeCanonicalSettings(parsed.settings, layout);
+        return parsed.settings;
+    }
+    finally {
+        lease.release();
+    }
+}
+export function parseSettingsText(text, file = "sash.json") {
+    let document;
+    try {
+        document = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`Settings file is invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return parseSettings(document, file, false).settings;
+}
+export function validateSettingsCandidate(candidate) {
+    return parseSettings(candidate, "candidate settings", false).settings;
+}
+export function parseControllerAddress(value) {
+    const match = value.trim().match(/^(127\.0\.0\.1|localhost|\[::1\]):(\d+)$/i);
+    const rawHost = match?.[1]?.toLowerCase();
+    const rawPort = match?.[2];
+    if (!rawHost || !rawPort)
+        return undefined;
+    const port = Number.parseInt(rawPort, 10);
+    if (port < 1 || port > 65_535 || String(port) !== rawPort)
+        return undefined;
+    if (rawHost === "[::1]") {
+        return { host: "::1", port, canonical: `[::1]:${port}` };
+    }
+    const host = rawHost === "localhost" ? "localhost" : "127.0.0.1";
+    return { host, port, canonical: `${host}:${port}` };
+}