@agimon-ai/po-core 0.0.0-alpha.0

package/dist/src/services/remoteAccessStore/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["os","path","poHomeDirectory","fs","DEFAULT_REMOTE_SETTINGS","parseRemoteAccessSettings","serializeRemoteAccessSettings"],"sources":["../../../../src/services/remoteAccessStore/index.ts"],"sourcesContent":["import fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\n\nimport { TRUSTED_DEVICE_LIMIT } from '../../constants/remote';\nimport type { RemoteAccessSettings, TrustedDeviceRecord } from '../../types/remote';\nimport { poHomeDirectory } from '../piSettings';\nimport {\n  DEFAULT_REMOTE_SETTINGS,\n  parseRemoteAccessSettings,\n  serializeRemoteAccessSettings,\n} from '../remoteAccessSettings';\nimport type { StoredCredential } from '../webauthnPolicy';\n\n/** Where the cockpit keeps machine-local state; `po sync` already writes its bundle here. */\nconst STATE_DIRECTORY = 'web';\nconst SETTINGS_FILE = 'remote-access.json';\nconst CREDENTIALS_FILE = 'credentials.json';\nconst TRUSTED_DEVICES_FILE = 'trusted-devices.json';\nconst TRUSTED_DEVICE_PLATFORMS: ReadonlySet<string> = new Set(['ios', 'android']);\nconst STORED_ID = /^[A-Za-z0-9_-]{1,64}$/u;\nconst STORED_KEY = /^[A-Za-z0-9_-]{1,512}$/u;\nconst MAX_STORED_LABEL = 200;\nconst DIRECTORY_MODE = 0o700;\nconst FILE_MODE = 0o600;\n/** Any bit set for group or other; a state file readable by another account is worth repairing. */\nconst LOOSE_MODE_MASK = 0o077;\n\nexport interface RemoteAccessStoreOptions {\n  /** Overridden by --state-dir and by tests; the default is ~/.po/web. */\n  stateDir?: string;\n  onNotice?: (message: string) => void;\n}\n\nexport interface RemoteAccessStore {\n  readonly directory: string;\n  settings(): RemoteAccessSettings;\n  save(settings: RemoteAccessSettings): void;\n  /**\n   * Registered passkeys. Public keys only, so the file is not a bearer secret\n   * and losing it costs a re-enrolment rather than an account.\n   */\n  credentials(): readonly StoredCredential[];\n  saveCredential(credential: StoredCredential): void;\n  removeCredential(id: string): boolean;\n  /** Registered native devices. Public keys only, at most `TRUSTED_DEVICE_LIMIT`. */\n  trustedDevices(): readonly TrustedDeviceRecord[];\n  /** Adds or replaces one record by id. False when a new record would exceed the limit. */\n  saveTrustedDevice(record: TrustedDeviceRecord): boolean;\n  removeTrustedDevice(id: string): boolean;\n}\n\nexport function defaultRemoteStateDir(homeDir: string = os.homedir()): string {\n  return path.join(poHomeDirectory(homeDir), STATE_DIRECTORY);\n}\n\n/**\n * Repairs a state file another account can read.\n *\n * Cheap, and it catches the cases a fresh write never would: a file restored\n * from a backup, copied with a permissive umask, or checked out of somewhere it\n * should not have been.\n */\nfunction tightenMode(filePath: string, notice: (message: string) => void): void {\n  try {\n    if ((fs.statSync(filePath).mode & LOOSE_MODE_MASK) === 0) return;\n    fs.chmodSync(filePath, FILE_MODE);\n    notice(`tightened permissions on ${filePath}`);\n  } catch {\n    // The file is missing or unreadable; the caller's own read reports that.\n  }\n}\n\n/** Whether one parsed entry is a complete trusted-device record; anything else is dropped. */\nfunction isTrustedDeviceRecord(value: unknown): value is TrustedDeviceRecord {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;\n  const record = value as Record<string, unknown>;\n  return (\n    typeof record.id === 'string' &&\n    STORED_ID.test(record.id) &&\n    typeof record.identityPublicKey === 'string' &&\n    STORED_KEY.test(record.identityPublicKey) &&\n    typeof record.stepUpPublicKey === 'string' &&\n    STORED_KEY.test(record.stepUpPublicKey) &&\n    record.identityPublicKey !== record.stepUpPublicKey &&\n    typeof record.label === 'string' &&\n    record.label.length <= MAX_STORED_LABEL &&\n    typeof record.platform === 'string' &&\n    TRUSTED_DEVICE_PLATFORMS.has(record.platform) &&\n    Number.isFinite(record.createdAt) &&\n    Number.isFinite(record.lastSeenAt)\n  );\n}\n\n/**\n * Settings and passkeys on disk. Sessions deliberately not.\n *\n * A session is revoked when remote access is switched off, and a hub restart is\n * a switch-off, so persisting one would buy nothing while creating a bearer\n * secret worth stealing. A passkey is the opposite: surviving is its whole\n * point, and what is stored is a public key.\n */\nexport function createRemoteAccessStore(options: RemoteAccessStoreOptions = {}): RemoteAccessStore {\n  const directory = options.stateDir ?? defaultRemoteStateDir();\n  const notice = options.onNotice ?? ((): void => {});\n  const settingsPath = path.join(directory, SETTINGS_FILE);\n  const credentialsPath = path.join(directory, CREDENTIALS_FILE);\n  const trustedDevicesPath = path.join(directory, TRUSTED_DEVICES_FILE);\n\n  let current = load();\n  let registered = loadCredentials();\n  let trusted = loadTrustedDevices();\n\n  function load(): RemoteAccessSettings {\n    let raw: string;\n    try {\n      raw = fs.readFileSync(settingsPath, 'utf8');\n    } catch {\n      // No file is the normal first run, so this is not worth a notice.\n      return DEFAULT_REMOTE_SETTINGS;\n    }\n    tightenMode(settingsPath, notice);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      // Left in place rather than rewritten: silently overwriting a file\n      // somebody hand-edited is worse than ignoring it for this run.\n      notice(`remote access settings at ${settingsPath} are not valid JSON; using defaults`);\n      return DEFAULT_REMOTE_SETTINGS;\n    }\n    const outcome = parseRemoteAccessSettings(parsed);\n    for (const warning of outcome.warnings) notice(`remote access settings: ${warning}`);\n    return outcome.settings;\n  }\n\n  function loadCredentials(): StoredCredential[] {\n    let raw: string;\n    try {\n      raw = fs.readFileSync(credentialsPath, 'utf8');\n    } catch {\n      return [];\n    }\n    tightenMode(credentialsPath, notice);\n    try {\n      const parsed: unknown = JSON.parse(raw);\n      return Array.isArray(parsed) ? (parsed as StoredCredential[]) : [];\n    } catch {\n      // Fails closed: a half-readable credential file means enrolling again,\n      // not guessing which entries survived.\n      notice(`registered passkeys at ${credentialsPath} are not valid JSON; none will load`);\n      return [];\n    }\n  }\n\n  function loadTrustedDevices(): TrustedDeviceRecord[] {\n    let raw: string;\n    try {\n      raw = fs.readFileSync(trustedDevicesPath, 'utf8');\n    } catch {\n      return [];\n    }\n    tightenMode(trustedDevicesPath, notice);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      // Fails closed like passkeys: a device signs in only from a record read whole.\n      notice(`trusted devices at ${trustedDevicesPath} are not valid JSON; none will load`);\n      return [];\n    }\n    if (!Array.isArray(parsed)) {\n      notice(`trusted devices at ${trustedDevicesPath} are not a list; none will load`);\n      return [];\n    }\n    const loaded: TrustedDeviceRecord[] = [];\n    for (const entry of parsed) {\n      if (!isTrustedDeviceRecord(entry) || loaded.some((held) => held.id === entry.id)) {\n        notice(`dropped an invalid trusted device record from ${trustedDevicesPath}`);\n        continue;\n      }\n      if (loaded.length >= TRUSTED_DEVICE_LIMIT) {\n        notice(\n          `dropped trusted devices beyond the limit of ${String(TRUSTED_DEVICE_LIMIT)} from ${trustedDevicesPath}`,\n        );\n        break;\n      }\n      loaded.push({\n        id: entry.id,\n        identityPublicKey: entry.identityPublicKey,\n        stepUpPublicKey: entry.stepUpPublicKey,\n        label: entry.label,\n        platform: entry.platform,\n        createdAt: entry.createdAt,\n        lastSeenAt: entry.lastSeenAt,\n      });\n    }\n    return loaded;\n  }\n\n  function writeJson(target: string, body: unknown): void {\n    const temporary = `${target}.${String(process.pid)}.tmp`;\n    try {\n      fs.mkdirSync(directory, { recursive: true, mode: DIRECTORY_MODE });\n      fs.writeFileSync(temporary, `${JSON.stringify(body, undefined, 2)}\\n`, { mode: FILE_MODE });\n      // Rename rather than write in place, so a crash mid-write leaves the\n      // previous contents rather than a truncated file.\n      fs.renameSync(temporary, target);\n    } catch (error) {\n      notice(`${target} could not be saved: ${error instanceof Error ? error.message : String(error)}`);\n      try {\n        fs.rmSync(temporary, { force: true });\n      } catch {\n        // Nothing further to do; the temp file is inert either way.\n      }\n    }\n  }\n\n  return {\n    directory,\n    settings: () => current,\n    credentials: () => registered,\n\n    saveCredential(credential) {\n      registered = [...registered.filter((held) => held.id !== credential.id), credential];\n      writeJson(credentialsPath, registered);\n    },\n\n    removeCredential(id) {\n      const next = registered.filter((held) => held.id !== id);\n      if (next.length === registered.length) return false;\n      registered = next;\n      writeJson(credentialsPath, registered);\n      return true;\n    },\n\n    trustedDevices: () => trusted,\n\n    saveTrustedDevice(record) {\n      const others = trusted.filter((held) => held.id !== record.id);\n      if (others.length === trusted.length && trusted.length >= TRUSTED_DEVICE_LIMIT) return false;\n      trusted = [...others, record];\n      writeJson(trustedDevicesPath, trusted);\n      return true;\n    },\n\n    removeTrustedDevice(id) {\n      const next = trusted.filter((held) => held.id !== id);\n      if (next.length === trusted.length) return false;\n      trusted = next;\n      writeJson(trustedDevicesPath, trusted);\n      return true;\n    },\n\n    save(settings) {\n      current = settings;\n      writeJson(settingsPath, serializeRemoteAccessSettings(settings));\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/src/services/remoteAccessStore/index.mjs

@@ -0,0 +1,192 @@
+import { poHomeDirectory } from "../../../runtimePiSettings.mjs";
+import "../../constants/remote.mjs";
+import { DEFAULT_REMOTE_SETTINGS, parseRemoteAccessSettings, serializeRemoteAccessSettings } from "../remoteAccessSettings/index.mjs";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+//#region src/services/remoteAccessStore/index.ts
+/** Where the cockpit keeps machine-local state; `po sync` already writes its bundle here. */
+const STATE_DIRECTORY = "web";
+const SETTINGS_FILE = "remote-access.json";
+const CREDENTIALS_FILE = "credentials.json";
+const TRUSTED_DEVICES_FILE = "trusted-devices.json";
+const TRUSTED_DEVICE_PLATFORMS = /* @__PURE__ */ new Set(["ios", "android"]);
+const STORED_ID = /^[A-Za-z0-9_-]{1,64}$/u;
+const STORED_KEY = /^[A-Za-z0-9_-]{1,512}$/u;
+const MAX_STORED_LABEL = 200;
+const DIRECTORY_MODE = 448;
+const FILE_MODE = 384;
+/** Any bit set for group or other; a state file readable by another account is worth repairing. */
+const LOOSE_MODE_MASK = 63;
+function defaultRemoteStateDir(homeDir = os.homedir()) {
+	return path.join(poHomeDirectory(homeDir), STATE_DIRECTORY);
+}
+/**
+* Repairs a state file another account can read.
+*
+* Cheap, and it catches the cases a fresh write never would: a file restored
+* from a backup, copied with a permissive umask, or checked out of somewhere it
+* should not have been.
+*/
+function tightenMode(filePath, notice) {
+	try {
+		if ((fs.statSync(filePath).mode & LOOSE_MODE_MASK) === 0) return;
+		fs.chmodSync(filePath, FILE_MODE);
+		notice(`tightened permissions on ${filePath}`);
+	} catch {}
+}
+/** Whether one parsed entry is a complete trusted-device record; anything else is dropped. */
+function isTrustedDeviceRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value;
+	return typeof record.id === "string" && STORED_ID.test(record.id) && typeof record.identityPublicKey === "string" && STORED_KEY.test(record.identityPublicKey) && typeof record.stepUpPublicKey === "string" && STORED_KEY.test(record.stepUpPublicKey) && record.identityPublicKey !== record.stepUpPublicKey && typeof record.label === "string" && record.label.length <= MAX_STORED_LABEL && typeof record.platform === "string" && TRUSTED_DEVICE_PLATFORMS.has(record.platform) && Number.isFinite(record.createdAt) && Number.isFinite(record.lastSeenAt);
+}
+/**
+* Settings and passkeys on disk. Sessions deliberately not.
+*
+* A session is revoked when remote access is switched off, and a hub restart is
+* a switch-off, so persisting one would buy nothing while creating a bearer
+* secret worth stealing. A passkey is the opposite: surviving is its whole
+* point, and what is stored is a public key.
+*/
+function createRemoteAccessStore(options = {}) {
+	const directory = options.stateDir ?? defaultRemoteStateDir();
+	const notice = options.onNotice ?? (() => {});
+	const settingsPath = path.join(directory, SETTINGS_FILE);
+	const credentialsPath = path.join(directory, CREDENTIALS_FILE);
+	const trustedDevicesPath = path.join(directory, TRUSTED_DEVICES_FILE);
+	let current = load();
+	let registered = loadCredentials();
+	let trusted = loadTrustedDevices();
+	function load() {
+		let raw;
+		try {
+			raw = fs.readFileSync(settingsPath, "utf8");
+		} catch {
+			return DEFAULT_REMOTE_SETTINGS;
+		}
+		tightenMode(settingsPath, notice);
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			notice(`remote access settings at ${settingsPath} are not valid JSON; using defaults`);
+			return DEFAULT_REMOTE_SETTINGS;
+		}
+		const outcome = parseRemoteAccessSettings(parsed);
+		for (const warning of outcome.warnings) notice(`remote access settings: ${warning}`);
+		return outcome.settings;
+	}
+	function loadCredentials() {
+		let raw;
+		try {
+			raw = fs.readFileSync(credentialsPath, "utf8");
+		} catch {
+			return [];
+		}
+		tightenMode(credentialsPath, notice);
+		try {
+			const parsed = JSON.parse(raw);
+			return Array.isArray(parsed) ? parsed : [];
+		} catch {
+			notice(`registered passkeys at ${credentialsPath} are not valid JSON; none will load`);
+			return [];
+		}
+	}
+	function loadTrustedDevices() {
+		let raw;
+		try {
+			raw = fs.readFileSync(trustedDevicesPath, "utf8");
+		} catch {
+			return [];
+		}
+		tightenMode(trustedDevicesPath, notice);
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			notice(`trusted devices at ${trustedDevicesPath} are not valid JSON; none will load`);
+			return [];
+		}
+		if (!Array.isArray(parsed)) {
+			notice(`trusted devices at ${trustedDevicesPath} are not a list; none will load`);
+			return [];
+		}
+		const loaded = [];
+		for (const entry of parsed) {
+			if (!isTrustedDeviceRecord(entry) || loaded.some((held) => held.id === entry.id)) {
+				notice(`dropped an invalid trusted device record from ${trustedDevicesPath}`);
+				continue;
+			}
+			if (loaded.length >= 32) {
+				notice(`dropped trusted devices beyond the limit of ${String(32)} from ${trustedDevicesPath}`);
+				break;
+			}
+			loaded.push({
+				id: entry.id,
+				identityPublicKey: entry.identityPublicKey,
+				stepUpPublicKey: entry.stepUpPublicKey,
+				label: entry.label,
+				platform: entry.platform,
+				createdAt: entry.createdAt,
+				lastSeenAt: entry.lastSeenAt
+			});
+		}
+		return loaded;
+	}
+	function writeJson(target, body) {
+		const temporary = `${target}.${String(process.pid)}.tmp`;
+		try {
+			fs.mkdirSync(directory, {
+				recursive: true,
+				mode: DIRECTORY_MODE
+			});
+			fs.writeFileSync(temporary, `${JSON.stringify(body, void 0, 2)}\n`, { mode: FILE_MODE });
+			fs.renameSync(temporary, target);
+		} catch (error) {
+			notice(`${target} could not be saved: ${error instanceof Error ? error.message : String(error)}`);
+			try {
+				fs.rmSync(temporary, { force: true });
+			} catch {}
+		}
+	}
+	return {
+		directory,
+		settings: () => current,
+		credentials: () => registered,
+		saveCredential(credential) {
+			registered = [...registered.filter((held) => held.id !== credential.id), credential];
+			writeJson(credentialsPath, registered);
+		},
+		removeCredential(id) {
+			const next = registered.filter((held) => held.id !== id);
+			if (next.length === registered.length) return false;
+			registered = next;
+			writeJson(credentialsPath, registered);
+			return true;
+		},
+		trustedDevices: () => trusted,
+		saveTrustedDevice(record) {
+			const others = trusted.filter((held) => held.id !== record.id);
+			if (others.length === trusted.length && trusted.length >= 32) return false;
+			trusted = [...others, record];
+			writeJson(trustedDevicesPath, trusted);
+			return true;
+		},
+		removeTrustedDevice(id) {
+			const next = trusted.filter((held) => held.id !== id);
+			if (next.length === trusted.length) return false;
+			trusted = next;
+			writeJson(trustedDevicesPath, trusted);
+			return true;
+		},
+		save(settings) {
+			current = settings;
+			writeJson(settingsPath, serializeRemoteAccessSettings(settings));
+		}
+	};
+}
+//#endregion
+export { createRemoteAccessStore, defaultRemoteStateDir };
+
+//# sourceMappingURL=index.mjs.map

package/dist/src/services/remoteAccessStore/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/remoteAccessStore/index.ts"],"sourcesContent":["import fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\n\nimport { TRUSTED_DEVICE_LIMIT } from '../../constants/remote';\nimport type { RemoteAccessSettings, TrustedDeviceRecord } from '../../types/remote';\nimport { poHomeDirectory } from '../piSettings';\nimport {\n  DEFAULT_REMOTE_SETTINGS,\n  parseRemoteAccessSettings,\n  serializeRemoteAccessSettings,\n} from '../remoteAccessSettings';\nimport type { StoredCredential } from '../webauthnPolicy';\n\n/** Where the cockpit keeps machine-local state; `po sync` already writes its bundle here. */\nconst STATE_DIRECTORY = 'web';\nconst SETTINGS_FILE = 'remote-access.json';\nconst CREDENTIALS_FILE = 'credentials.json';\nconst TRUSTED_DEVICES_FILE = 'trusted-devices.json';\nconst TRUSTED_DEVICE_PLATFORMS: ReadonlySet<string> = new Set(['ios', 'android']);\nconst STORED_ID = /^[A-Za-z0-9_-]{1,64}$/u;\nconst STORED_KEY = /^[A-Za-z0-9_-]{1,512}$/u;\nconst MAX_STORED_LABEL = 200;\nconst DIRECTORY_MODE = 0o700;\nconst FILE_MODE = 0o600;\n/** Any bit set for group or other; a state file readable by another account is worth repairing. */\nconst LOOSE_MODE_MASK = 0o077;\n\nexport interface RemoteAccessStoreOptions {\n  /** Overridden by --state-dir and by tests; the default is ~/.po/web. */\n  stateDir?: string;\n  onNotice?: (message: string) => void;\n}\n\nexport interface RemoteAccessStore {\n  readonly directory: string;\n  settings(): RemoteAccessSettings;\n  save(settings: RemoteAccessSettings): void;\n  /**\n   * Registered passkeys. Public keys only, so the file is not a bearer secret\n   * and losing it costs a re-enrolment rather than an account.\n   */\n  credentials(): readonly StoredCredential[];\n  saveCredential(credential: StoredCredential): void;\n  removeCredential(id: string): boolean;\n  /** Registered native devices. Public keys only, at most `TRUSTED_DEVICE_LIMIT`. */\n  trustedDevices(): readonly TrustedDeviceRecord[];\n  /** Adds or replaces one record by id. False when a new record would exceed the limit. */\n  saveTrustedDevice(record: TrustedDeviceRecord): boolean;\n  removeTrustedDevice(id: string): boolean;\n}\n\nexport function defaultRemoteStateDir(homeDir: string = os.homedir()): string {\n  return path.join(poHomeDirectory(homeDir), STATE_DIRECTORY);\n}\n\n/**\n * Repairs a state file another account can read.\n *\n * Cheap, and it catches the cases a fresh write never would: a file restored\n * from a backup, copied with a permissive umask, or checked out of somewhere it\n * should not have been.\n */\nfunction tightenMode(filePath: string, notice: (message: string) => void): void {\n  try {\n    if ((fs.statSync(filePath).mode & LOOSE_MODE_MASK) === 0) return;\n    fs.chmodSync(filePath, FILE_MODE);\n    notice(`tightened permissions on ${filePath}`);\n  } catch {\n    // The file is missing or unreadable; the caller's own read reports that.\n  }\n}\n\n/** Whether one parsed entry is a complete trusted-device record; anything else is dropped. */\nfunction isTrustedDeviceRecord(value: unknown): value is TrustedDeviceRecord {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;\n  const record = value as Record<string, unknown>;\n  return (\n    typeof record.id === 'string' &&\n    STORED_ID.test(record.id) &&\n    typeof record.identityPublicKey === 'string' &&\n    STORED_KEY.test(record.identityPublicKey) &&\n    typeof record.stepUpPublicKey === 'string' &&\n    STORED_KEY.test(record.stepUpPublicKey) &&\n    record.identityPublicKey !== record.stepUpPublicKey &&\n    typeof record.label === 'string' &&\n    record.label.length <= MAX_STORED_LABEL &&\n    typeof record.platform === 'string' &&\n    TRUSTED_DEVICE_PLATFORMS.has(record.platform) &&\n    Number.isFinite(record.createdAt) &&\n    Number.isFinite(record.lastSeenAt)\n  );\n}\n\n/**\n * Settings and passkeys on disk. Sessions deliberately not.\n *\n * A session is revoked when remote access is switched off, and a hub restart is\n * a switch-off, so persisting one would buy nothing while creating a bearer\n * secret worth stealing. A passkey is the opposite: surviving is its whole\n * point, and what is stored is a public key.\n */\nexport function createRemoteAccessStore(options: RemoteAccessStoreOptions = {}): RemoteAccessStore {\n  const directory = options.stateDir ?? defaultRemoteStateDir();\n  const notice = options.onNotice ?? ((): void => {});\n  const settingsPath = path.join(directory, SETTINGS_FILE);\n  const credentialsPath = path.join(directory, CREDENTIALS_FILE);\n  const trustedDevicesPath = path.join(directory, TRUSTED_DEVICES_FILE);\n\n  let current = load();\n  let registered = loadCredentials();\n  let trusted = loadTrustedDevices();\n\n  function load(): RemoteAccessSettings {\n    let raw: string;\n    try {\n      raw = fs.readFileSync(settingsPath, 'utf8');\n    } catch {\n      // No file is the normal first run, so this is not worth a notice.\n      return DEFAULT_REMOTE_SETTINGS;\n    }\n    tightenMode(settingsPath, notice);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      // Left in place rather than rewritten: silently overwriting a file\n      // somebody hand-edited is worse than ignoring it for this run.\n      notice(`remote access settings at ${settingsPath} are not valid JSON; using defaults`);\n      return DEFAULT_REMOTE_SETTINGS;\n    }\n    const outcome = parseRemoteAccessSettings(parsed);\n    for (const warning of outcome.warnings) notice(`remote access settings: ${warning}`);\n    return outcome.settings;\n  }\n\n  function loadCredentials(): StoredCredential[] {\n    let raw: string;\n    try {\n      raw = fs.readFileSync(credentialsPath, 'utf8');\n    } catch {\n      return [];\n    }\n    tightenMode(credentialsPath, notice);\n    try {\n      const parsed: unknown = JSON.parse(raw);\n      return Array.isArray(parsed) ? (parsed as StoredCredential[]) : [];\n    } catch {\n      // Fails closed: a half-readable credential file means enrolling again,\n      // not guessing which entries survived.\n      notice(`registered passkeys at ${credentialsPath} are not valid JSON; none will load`);\n      return [];\n    }\n  }\n\n  function loadTrustedDevices(): TrustedDeviceRecord[] {\n    let raw: string;\n    try {\n      raw = fs.readFileSync(trustedDevicesPath, 'utf8');\n    } catch {\n      return [];\n    }\n    tightenMode(trustedDevicesPath, notice);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      // Fails closed like passkeys: a device signs in only from a record read whole.\n      notice(`trusted devices at ${trustedDevicesPath} are not valid JSON; none will load`);\n      return [];\n    }\n    if (!Array.isArray(parsed)) {\n      notice(`trusted devices at ${trustedDevicesPath} are not a list; none will load`);\n      return [];\n    }\n    const loaded: TrustedDeviceRecord[] = [];\n    for (const entry of parsed) {\n      if (!isTrustedDeviceRecord(entry) || loaded.some((held) => held.id === entry.id)) {\n        notice(`dropped an invalid trusted device record from ${trustedDevicesPath}`);\n        continue;\n      }\n      if (loaded.length >= TRUSTED_DEVICE_LIMIT) {\n        notice(\n          `dropped trusted devices beyond the limit of ${String(TRUSTED_DEVICE_LIMIT)} from ${trustedDevicesPath}`,\n        );\n        break;\n      }\n      loaded.push({\n        id: entry.id,\n        identityPublicKey: entry.identityPublicKey,\n        stepUpPublicKey: entry.stepUpPublicKey,\n        label: entry.label,\n        platform: entry.platform,\n        createdAt: entry.createdAt,\n        lastSeenAt: entry.lastSeenAt,\n      });\n    }\n    return loaded;\n  }\n\n  function writeJson(target: string, body: unknown): void {\n    const temporary = `${target}.${String(process.pid)}.tmp`;\n    try {\n      fs.mkdirSync(directory, { recursive: true, mode: DIRECTORY_MODE });\n      fs.writeFileSync(temporary, `${JSON.stringify(body, undefined, 2)}\\n`, { mode: FILE_MODE });\n      // Rename rather than write in place, so a crash mid-write leaves the\n      // previous contents rather than a truncated file.\n      fs.renameSync(temporary, target);\n    } catch (error) {\n      notice(`${target} could not be saved: ${error instanceof Error ? error.message : String(error)}`);\n      try {\n        fs.rmSync(temporary, { force: true });\n      } catch {\n        // Nothing further to do; the temp file is inert either way.\n      }\n    }\n  }\n\n  return {\n    directory,\n    settings: () => current,\n    credentials: () => registered,\n\n    saveCredential(credential) {\n      registered = [...registered.filter((held) => held.id !== credential.id), credential];\n      writeJson(credentialsPath, registered);\n    },\n\n    removeCredential(id) {\n      const next = registered.filter((held) => held.id !== id);\n      if (next.length === registered.length) return false;\n      registered = next;\n      writeJson(credentialsPath, registered);\n      return true;\n    },\n\n    trustedDevices: () => trusted,\n\n    saveTrustedDevice(record) {\n      const others = trusted.filter((held) => held.id !== record.id);\n      if (others.length === trusted.length && trusted.length >= TRUSTED_DEVICE_LIMIT) return false;\n      trusted = [...others, record];\n      writeJson(trustedDevicesPath, trusted);\n      return true;\n    },\n\n    removeTrustedDevice(id) {\n      const next = trusted.filter((held) => held.id !== id);\n      if (next.length === trusted.length) return false;\n      trusted = next;\n      writeJson(trustedDevicesPath, trusted);\n      return true;\n    },\n\n    save(settings) {\n      current = settings;\n      writeJson(settingsPath, serializeRemoteAccessSettings(settings));\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/src/services/remoteGuardPolicy/index.cjs

@@ -0,0 +1,200 @@
+const require_remote = require("../../constants/remote.cjs");
+//#region src/services/remoteGuardPolicy/index.ts
+/**
+* Who may do what, on which listener.
+*
+* The cockpit runs one Hono app behind two sockets: a loopback listener that is
+* open to whoever already has an account on the machine, and a tunnel listener
+* that faces the public internet. Every decision here answers one question
+* about one request, with no I/O, so the whole trust boundary is readable in a
+* single sitting and testable without a server.
+*/
+const METHOD_GET = "GET";
+const METHOD_HEAD = "HEAD";
+const METHOD_POST = "POST";
+/** Cloudflare's edge speaks to us on 443, so the Host it forwards may or may not carry the port. */
+const HTTPS_DEFAULT_PORT = "443";
+/**
+* The exact package-owned pairing and PWA bootstrap routes the tunnel listener
+* answers directly. They are matched by string equality, never prefixes or
+* wildcards. A contract test pins the list so additions require review.
+*
+* Passkey sign-in and native device sign-in are public because each creates a
+* session by proving a credential: a passkey, or a registered device identity key.
+* Passkey registration is also direct so the self-contained pairing page can run
+* it, but its handlers require the paired device cookie issued only after host
+* approval. Native device registration is not listed: it is sealed only.
+*/
+const PUBLIC_PAIRING_ROUTES = [
+	{
+		method: METHOD_GET,
+		path: "/"
+	},
+	{
+		method: METHOD_GET,
+		path: require_remote.PAIRING_PAGE_ROUTE
+	},
+	{
+		method: METHOD_GET,
+		path: "/manifest.webmanifest"
+	},
+	{
+		method: METHOD_GET,
+		path: "/sw.js"
+	},
+	{
+		method: METHOD_GET,
+		path: "/pwa/pwa.js"
+	},
+	{
+		method: METHOD_GET,
+		path: "/pwa/icon-192.png"
+	},
+	{
+		method: METHOD_GET,
+		path: "/pwa/icon-512.png"
+	},
+	{
+		method: METHOD_POST,
+		path: require_remote.PAIRING_CLAIM_ROUTE
+	},
+	{
+		method: METHOD_GET,
+		path: require_remote.PAIRING_STATUS_ROUTE
+	},
+	{
+		method: METHOD_POST,
+		path: require_remote.PASSKEY_AUTH_BEGIN_ROUTE
+	},
+	{
+		method: METHOD_POST,
+		path: require_remote.PASSKEY_AUTH_FINISH_ROUTE
+	},
+	{
+		method: METHOD_POST,
+		path: require_remote.PASSKEY_REGISTER_BEGIN_ROUTE
+	},
+	{
+		method: METHOD_POST,
+		path: require_remote.PASSKEY_REGISTER_FINISH_ROUTE
+	},
+	{
+		method: METHOD_POST,
+		path: require_remote.DEVICE_AUTH_CHALLENGE_ROUTE
+	},
+	{
+		method: METHOD_POST,
+		path: require_remote.DEVICE_AUTH_AUTHENTICATE_ROUTE
+	}
+];
+/**
+* Whether the tunnel listener may answer this request directly.
+*
+* Session requirements for direct routes are enforced by their exact handlers.
+* `path` must be the value the router matched on, which for Hono is
+* `c.req.path`. That value is percent-decoded, so `/%70air` reaches the `/pair`
+* handler; comparing against a separately parsed pathname would let the guard
+* and the router disagree about the same request, which is how an allowlist
+* turns into a bypass.
+*/
+function isPublicPairingRoute(method, path) {
+	const wanted = method.toUpperCase();
+	return PUBLIC_PAIRING_ROUTES.some((route) => route.method === wanted && route.path === path);
+}
+/** Normalizes to scheme://host[:port], lowercased. Undefined for anything unparseable, `null` included. */
+function normalizeOrigin(raw) {
+	try {
+		return new URL(raw).origin.toLowerCase();
+	} catch {
+		return;
+	}
+}
+function normalizeHost(raw) {
+	return raw.trim().toLowerCase();
+}
+/**
+* What the loopback listener accepts.
+*
+* The port is the one the socket actually bound, not a constant, because the
+* hub takes `--port` and the e2e fixture reserves a random free one. The vite
+* dev server is allowed unconditionally so the documented two-terminal plugin
+* loop keeps working; anything that can bind that port already runs as this
+* user, so the marginal risk is close to nothing.
+*/
+function localOriginPolicy(port, extraOrigins = []) {
+	const hosts = /* @__PURE__ */ new Set();
+	const origins = /* @__PURE__ */ new Set();
+	for (const listenPort of [port, require_remote.WEB_DEV_SERVER_PORT]) for (const name of [
+		"127.0.0.1",
+		"localhost",
+		"[::1]"
+	]) {
+		const host = `${name}:${String(listenPort)}`;
+		hosts.add(host);
+		origins.add(`http://${host}`);
+	}
+	for (const extra of extraOrigins) {
+		const normalized = normalizeOrigin(extra);
+		if (normalized !== void 0) origins.add(normalized);
+	}
+	return {
+		origins,
+		hosts
+	};
+}
+/** What the tunnel listener accepts: its own origin and nothing else. */
+function tunnelOriginPolicy(publicOrigin, extraHosts = []) {
+	const normalized = normalizeOrigin(publicOrigin);
+	if (normalized === void 0) throw new Error(`The tunnel origin "${publicOrigin}" is not a URL.`);
+	const host = new URL(normalized).host;
+	const hosts = /* @__PURE__ */ new Set([host, `${host}:${HTTPS_DEFAULT_PORT}`]);
+	for (const extra of extraHosts) hosts.add(normalizeHost(extra));
+	return {
+		origins: /* @__PURE__ */ new Set([normalized]),
+		hosts
+	};
+}
+/** A request with a side effect: anything that is not a plain read, plus every socket upgrade. */
+function isMutating(method, isUpgrade) {
+	if (isUpgrade) return true;
+	const wanted = method.toUpperCase();
+	return wanted !== METHOD_GET && wanted !== METHOD_HEAD;
+}
+/**
+* Whether the request's Origin and Host are ones this listener answers to.
+*
+* The loopback listener is lenient about a missing Origin and strict about one
+* that is present. That asymmetry is deliberate: a browser always sends Origin
+* on a socket handshake and on a cross-origin mutation, which is the attack
+* this closes, while curl, the health probe, and the test harness send none and
+* would break for no security gain. It buys nothing against a local program,
+* which can send whatever it likes, and is not meant to.
+*
+* The tunnel listener requires Origin on anything with a side effect and
+* tolerates its absence only on a plain read, because a top-level navigation
+* (following the scanned link) legitimately sends none.
+*
+* Host is checked on both. On the loopback listener that is the DNS-rebinding
+* defence for a well-known port, and it is the only check a socket upgrade gets
+* at all, since the upgrade path never reaches the node-server host parsing.
+*/
+function originVerdict(input) {
+	const policy = input.listener === "local" ? input.local : input.tunnel;
+	if (policy === void 0) return "not-ready";
+	if (input.host === void 0 || !policy.hosts.has(normalizeHost(input.host))) return "bad-host";
+	if (input.origin === void 0) {
+		if (input.listener === "local") return "allow";
+		return isMutating(input.method, input.isUpgrade) ? "bad-origin" : "allow";
+	}
+	const origin = normalizeOrigin(input.origin);
+	if (origin === void 0 || !policy.origins.has(origin)) return "bad-origin";
+	return "allow";
+}
+//#endregion
+exports.PUBLIC_PAIRING_ROUTES = PUBLIC_PAIRING_ROUTES;
+exports.isPublicPairingRoute = isPublicPairingRoute;
+exports.localOriginPolicy = localOriginPolicy;
+exports.originVerdict = originVerdict;
+exports.tunnelOriginPolicy = tunnelOriginPolicy;
+
+//# sourceMappingURL=index.cjs.map

package/dist/src/services/remoteGuardPolicy/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["PAIRING_PAGE_ROUTE","PAIRING_CLAIM_ROUTE","PAIRING_STATUS_ROUTE","PASSKEY_AUTH_BEGIN_ROUTE","PASSKEY_AUTH_FINISH_ROUTE","PASSKEY_REGISTER_BEGIN_ROUTE","PASSKEY_REGISTER_FINISH_ROUTE","DEVICE_AUTH_CHALLENGE_ROUTE","DEVICE_AUTH_AUTHENTICATE_ROUTE","WEB_DEV_SERVER_PORT"],"sources":["../../../../src/services/remoteGuardPolicy/index.ts"],"sourcesContent":["/**\n * Who may do what, on which listener.\n *\n * The cockpit runs one Hono app behind two sockets: a loopback listener that is\n * open to whoever already has an account on the machine, and a tunnel listener\n * that faces the public internet. Every decision here answers one question\n * about one request, with no I/O, so the whole trust boundary is readable in a\n * single sitting and testable without a server.\n */\n\nimport {\n  DEVICE_AUTH_AUTHENTICATE_ROUTE,\n  DEVICE_AUTH_CHALLENGE_ROUTE,\n  PAIRING_CLAIM_ROUTE,\n  PAIRING_PAGE_ROUTE,\n  PAIRING_STATUS_ROUTE,\n  PASSKEY_AUTH_BEGIN_ROUTE,\n  PASSKEY_AUTH_FINISH_ROUTE,\n  PASSKEY_REGISTER_BEGIN_ROUTE,\n  PASSKEY_REGISTER_FINISH_ROUTE,\n  WEB_DEV_SERVER_PORT,\n} from '../../constants/remote';\n\nconst METHOD_GET = 'GET';\nconst METHOD_HEAD = 'HEAD';\nconst METHOD_POST = 'POST';\n/** Cloudflare's edge speaks to us on 443, so the Host it forwards may or may not carry the port. */\nconst HTTPS_DEFAULT_PORT = '443';\n\nexport type GuardListener = 'local' | 'tunnel';\n\nexport type OriginVerdict = 'allow' | 'bad-origin' | 'bad-host' | 'not-ready';\n\nexport interface OriginPolicy {\n  origins: ReadonlySet<string>;\n  hosts: ReadonlySet<string>;\n}\n\nexport interface OriginVerdictInput {\n  listener: GuardListener;\n  method: string;\n  isUpgrade: boolean;\n  origin: string | undefined;\n  host: string | undefined;\n  local: OriginPolicy;\n  /** Undefined until the tunnel reports its hostname; until then nothing on that listener is served. */\n  tunnel: OriginPolicy | undefined;\n}\n\n/**\n * Which socket a request arrived on.\n *\n * Phrased as allow-only-if-provably-local on purpose. A missing env, an\n * unreadable port, or a socket torn down mid-request all resolve to 'tunnel'\n * and therefore require a credential. The mirror-image phrasing\n * (`port === tunnelPort`) fails open on every one of those.\n */\nexport function listenerOf(socketLocalPort: number | undefined, loopbackPort: number | undefined): GuardListener {\n  if (loopbackPort === undefined || socketLocalPort === undefined) return 'tunnel';\n  return socketLocalPort === loopbackPort ? 'local' : 'tunnel';\n}\n\n/**\n * The exact package-owned pairing and PWA bootstrap routes the tunnel listener\n * answers directly. They are matched by string equality, never prefixes or\n * wildcards. A contract test pins the list so additions require review.\n *\n * Passkey sign-in and native device sign-in are public because each creates a\n * session by proving a credential: a passkey, or a registered device identity key.\n * Passkey registration is also direct so the self-contained pairing page can run\n * it, but its handlers require the paired device cookie issued only after host\n * approval. Native device registration is not listed: it is sealed only.\n */\nexport const PUBLIC_PAIRING_ROUTES: readonly { method: string; path: string }[] = [\n  { method: METHOD_GET, path: '/' },\n  { method: METHOD_GET, path: PAIRING_PAGE_ROUTE },\n  { method: METHOD_GET, path: '/manifest.webmanifest' },\n  { method: METHOD_GET, path: '/sw.js' },\n  { method: METHOD_GET, path: '/pwa/pwa.js' },\n  { method: METHOD_GET, path: '/pwa/icon-192.png' },\n  { method: METHOD_GET, path: '/pwa/icon-512.png' },\n  { method: METHOD_POST, path: PAIRING_CLAIM_ROUTE },\n  { method: METHOD_GET, path: PAIRING_STATUS_ROUTE },\n  { method: METHOD_POST, path: PASSKEY_AUTH_BEGIN_ROUTE },\n  { method: METHOD_POST, path: PASSKEY_AUTH_FINISH_ROUTE },\n  { method: METHOD_POST, path: PASSKEY_REGISTER_BEGIN_ROUTE },\n  { method: METHOD_POST, path: PASSKEY_REGISTER_FINISH_ROUTE },\n  { method: METHOD_POST, path: DEVICE_AUTH_CHALLENGE_ROUTE },\n  { method: METHOD_POST, path: DEVICE_AUTH_AUTHENTICATE_ROUTE },\n];\n\n/**\n * Whether the tunnel listener may answer this request directly.\n *\n * Session requirements for direct routes are enforced by their exact handlers.\n * `path` must be the value the router matched on, which for Hono is\n * `c.req.path`. That value is percent-decoded, so `/%70air` reaches the `/pair`\n * handler; comparing against a separately parsed pathname would let the guard\n * and the router disagree about the same request, which is how an allowlist\n * turns into a bypass.\n */\nexport function isPublicPairingRoute(method: string, path: string): boolean {\n  const wanted = method.toUpperCase();\n  return PUBLIC_PAIRING_ROUTES.some((route) => route.method === wanted && route.path === path);\n}\n\n/**\n * Reads the operator's extra-origin allowlist.\n *\n * The escape hatch for a dev setup this package cannot guess: a second dev\n * server port, a reverse proxy, a `.local` hostname. Comma separated, blanks\n * dropped, so an empty or unset variable adds nothing.\n */\nexport function allowedOriginsFromEnv(raw: string | undefined): readonly string[] {\n  if (raw === undefined) return [];\n  return raw\n    .split(',')\n    .map((entry) => entry.trim())\n    .filter((entry) => entry !== '');\n}\n\n/** Normalizes to scheme://host[:port], lowercased. Undefined for anything unparseable, `null` included. */\nfunction normalizeOrigin(raw: string): string | undefined {\n  try {\n    return new URL(raw).origin.toLowerCase();\n  } catch {\n    // An Origin header that is not a URL is either the opaque `null` or a\n    // forgery; neither is on any allowlist, so refusing it is the answer.\n    return undefined;\n  }\n}\n\nfunction normalizeHost(raw: string): string {\n  return raw.trim().toLowerCase();\n}\n\n/**\n * What the loopback listener accepts.\n *\n * The port is the one the socket actually bound, not a constant, because the\n * hub takes `--port` and the e2e fixture reserves a random free one. The vite\n * dev server is allowed unconditionally so the documented two-terminal plugin\n * loop keeps working; anything that can bind that port already runs as this\n * user, so the marginal risk is close to nothing.\n */\nexport function localOriginPolicy(port: number, extraOrigins: readonly string[] = []): OriginPolicy {\n  const hosts = new Set<string>();\n  const origins = new Set<string>();\n  // The dev server's own port belongs here too: vite proxies /api to the hub\n  // without `changeOrigin`, so the browser's Host and Origin arrive unchanged\n  // and both name 7534 rather than the hub's port.\n  for (const listenPort of [port, WEB_DEV_SERVER_PORT]) {\n    for (const name of ['127.0.0.1', 'localhost', '[::1]']) {\n      const host = `${name}:${String(listenPort)}`;\n      hosts.add(host);\n      origins.add(`http://${host}`);\n    }\n  }\n  for (const extra of extraOrigins) {\n    const normalized = normalizeOrigin(extra);\n    if (normalized !== undefined) origins.add(normalized);\n  }\n  return { origins, hosts };\n}\n\n/** What the tunnel listener accepts: its own origin and nothing else. */\nexport function tunnelOriginPolicy(publicOrigin: string, extraHosts: readonly string[] = []): OriginPolicy {\n  const normalized = normalizeOrigin(publicOrigin);\n  if (normalized === undefined) throw new Error(`The tunnel origin \"${publicOrigin}\" is not a URL.`);\n  const host = new URL(normalized).host;\n  const hosts = new Set([host, `${host}:${HTTPS_DEFAULT_PORT}`]);\n  for (const extra of extraHosts) hosts.add(normalizeHost(extra));\n  return { origins: new Set([normalized]), hosts };\n}\n\n/** A request with a side effect: anything that is not a plain read, plus every socket upgrade. */\nfunction isMutating(method: string, isUpgrade: boolean): boolean {\n  if (isUpgrade) return true;\n  const wanted = method.toUpperCase();\n  return wanted !== METHOD_GET && wanted !== METHOD_HEAD;\n}\n\n/**\n * Whether the request's Origin and Host are ones this listener answers to.\n *\n * The loopback listener is lenient about a missing Origin and strict about one\n * that is present. That asymmetry is deliberate: a browser always sends Origin\n * on a socket handshake and on a cross-origin mutation, which is the attack\n * this closes, while curl, the health probe, and the test harness send none and\n * would break for no security gain. It buys nothing against a local program,\n * which can send whatever it likes, and is not meant to.\n *\n * The tunnel listener requires Origin on anything with a side effect and\n * tolerates its absence only on a plain read, because a top-level navigation\n * (following the scanned link) legitimately sends none.\n *\n * Host is checked on both. On the loopback listener that is the DNS-rebinding\n * defence for a well-known port, and it is the only check a socket upgrade gets\n * at all, since the upgrade path never reaches the node-server host parsing.\n */\nexport function originVerdict(input: OriginVerdictInput): OriginVerdict {\n  const policy = input.listener === 'local' ? input.local : input.tunnel;\n  // Before the tunnel names itself there is no legitimate traffic to serve and\n  // no origin to compare against, so the listener answers nothing at all.\n  if (policy === undefined) return 'not-ready';\n\n  if (input.host === undefined || !policy.hosts.has(normalizeHost(input.host))) return 'bad-host';\n\n  if (input.origin === undefined) {\n    if (input.listener === 'local') return 'allow';\n    return isMutating(input.method, input.isUpgrade) ? 'bad-origin' : 'allow';\n  }\n\n  const origin = normalizeOrigin(input.origin);\n  if (origin === undefined || !policy.origins.has(origin)) return 'bad-origin';\n  return 'allow';\n}\n"],"mappings":"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"}

package/dist/src/services/remoteGuardPolicy/index.d.mts

@@ -0,0 +1,7 @@
+//#region src/services/remoteGuardPolicy/index.d.ts
+export interface OriginPolicy {
+  origins: ReadonlySet<string>;
+  hosts: ReadonlySet<string>;
+}
+//#endregion
+//# sourceMappingURL=index.d.mts.map

package/dist/src/services/remoteGuardPolicy/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../src/services/remoteGuardPolicy/index.ts"],"mappings":";iBAiCiB;EACf,SAAS;EACT,OAAO"}