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

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

@@ -0,0 +1,168 @@
+const require_remote = require("../../constants/remote.cjs");
+//#region src/services/devProxyPolicy/index.ts
+/**
+* What the dev proxy will forward, and where.
+*
+* Pure, with no I/O, so the whole decision surface of a feature that reaches
+* loopback services can be read in one sitting and tested without a server.
+*
+* The upstream host is not a parameter anywhere in this module, and a target
+* is a port and nothing else. Accepting a hostname would mean resolving one,
+* and a resolver turns a fixed destination into an attacker-chosen one through
+* DNS rebinding, decimal and octal address spellings, and IPv4-mapped IPv6
+* forms. Refusing the parameter forecloses that family rather than filtering
+* it. Which of the two loopback literals actually answers is settled in
+* the loopbackAddress service, from the port alone.
+*/
+const MAX_NAME_LENGTH = 32;
+/**
+* Lowercase, digits and dashes, opening on an alphanumeric.
+*
+* The name is a path segment and it is also what the developer types into
+* `base: '/devproxy/<name>/'`, so it stays in the character set that needs no
+* escaping in either place.
+*/
+const TARGET_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/u;
+const MIN_PORT = 1;
+const MAX_PORT = 65535;
+function validateTargetName(raw) {
+	if (typeof raw !== "string") return {
+		ok: false,
+		reason: "A target name must be text."
+	};
+	const name = raw.trim().toLowerCase();
+	if (name === "") return {
+		ok: false,
+		reason: "A target needs a name."
+	};
+	if (name.length > MAX_NAME_LENGTH) return {
+		ok: false,
+		reason: `A target name is at most ${String(MAX_NAME_LENGTH)} characters.`
+	};
+	if (!TARGET_NAME.test(name)) return {
+		ok: false,
+		reason: "A target name uses lowercase letters, digits and dashes, starting with a letter or digit."
+	};
+	return {
+		ok: true,
+		name
+	};
+}
+/**
+* Whether this port may be proxied.
+*
+* `reserved` is read fresh by the caller on every attempt rather than captured
+* once, because the cockpit's own ports are only known after it binds and the
+* tunnel port changes when remote access is toggled. A cached list would go
+* stale in exactly the direction that matters, letting the proxy point at the
+* cockpit itself.
+*/
+function validateTargetPort(raw, reserved) {
+	const port = typeof raw === "number" ? raw : Number(raw);
+	if (!Number.isSafeInteger(port)) return {
+		ok: false,
+		reason: "A port must be a whole number."
+	};
+	if (port < MIN_PORT || port > MAX_PORT) return {
+		ok: false,
+		reason: `A port is between ${String(MIN_PORT)} and ${String(MAX_PORT)}.`
+	};
+	if (reserved.includes(port)) return {
+		ok: false,
+		reason: "That port belongs to the cockpit itself."
+	};
+	return {
+		ok: true,
+		port
+	};
+}
+/**
+* Whether a path segment tries to climb out of the prefix.
+*
+* Checked before and after percent-decoding. A proxy that only checked the raw
+* form would forward `%2e%2e`, and an upstream that decodes before resolving
+* would then walk out of the tree the operator meant to expose.
+*/
+function escapesPrefix(upstreamPath) {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(upstreamPath);
+	} catch {
+		return true;
+	}
+	for (const candidate of [upstreamPath, decoded]) for (const segment of candidate.split("/")) if (segment === "." || segment === "..") return true;
+	return false;
+}
+/**
+* Whether this path is one the dev proxy owns.
+*
+* The remote guard and the proxy handler must agree about this, and they do not
+* see the same string: Hono's router hands the guard a raw slice of the request
+* line, while the handler reads `new URL(...).pathname`, which resolves `..`
+* before anyone looks at it. So `/devproxy/x/../../api/health` can be a proxy
+* path to one and an API path to the other, and a guard that answered on the
+* prefix alone would grant an `/api/` request the direct, unsealed treatment.
+*
+* Refusing every dot segment removes the disagreement instead of trying to
+* predict it. A legitimate asset URL has no reason to carry one.
+*/
+function isDevProxyPath(path) {
+	if (!path.startsWith("/devproxy/")) return false;
+	return !escapesPrefix(path.slice(require_remote.DEV_PROXY_PREFIX.length));
+}
+/**
+* Identifies the target a proxied request belongs to.
+*
+* `upstreamPath` is the request path unchanged, prefix included. That is the
+* whole trick, and getting it wrong costs a redirect loop: the target is
+* configured with `base: '/devproxy/<name>/'`, so it believes it is serving
+* there and redirects anything at `/` back to its base. Stripping the prefix
+* would hand it `/`, take its redirect, and go round again. nginx draws the
+* same distinction between `proxy_pass http://host/` and `proxy_pass
+* http://host`; this is the second one.
+*
+* Reads the raw, still-encoded pathname. Hono routes and the remote guard both
+* work on the decoded value, so a request that only becomes `/devproxy/...`
+* after decoding would reach this handler, and passing the encoded form
+* through untouched is what makes a file named `a b.png` load.
+*/
+function parseProxyPath(rawPathname) {
+	if (!rawPathname.startsWith("/devproxy/")) return {
+		kind: "reject",
+		reason: "Not a proxied path."
+	};
+	const rest = rawPathname.slice(require_remote.DEV_PROXY_PREFIX.length);
+	const boundary = rest.indexOf("/");
+	if (boundary === -1) {
+		const verdict = validateTargetName(rest);
+		if (!verdict.ok) return {
+			kind: "reject",
+			reason: verdict.reason
+		};
+		return {
+			kind: "redirect",
+			location: `${require_remote.DEV_PROXY_PREFIX}${verdict.name}/`
+		};
+	}
+	const verdict = validateTargetName(rest.slice(0, boundary));
+	if (!verdict.ok) return {
+		kind: "reject",
+		reason: verdict.reason
+	};
+	if (escapesPrefix(rest.slice(boundary))) return {
+		kind: "reject",
+		reason: "That path leaves the proxied target."
+	};
+	return {
+		kind: "match",
+		name: verdict.name,
+		upstreamPath: rawPathname
+	};
+}
+//#endregion
+exports.isDevProxyPath = isDevProxyPath;
+exports.parseProxyPath = parseProxyPath;
+exports.validateTargetName = validateTargetName;
+exports.validateTargetPort = validateTargetPort;
+
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["DEV_PROXY_PREFIX"],"sources":["../../../../src/services/devProxyPolicy/index.ts"],"sourcesContent":["/**\n * What the dev proxy will forward, and where.\n *\n * Pure, with no I/O, so the whole decision surface of a feature that reaches\n * loopback services can be read in one sitting and tested without a server.\n *\n * The upstream host is not a parameter anywhere in this module, and a target\n * is a port and nothing else. Accepting a hostname would mean resolving one,\n * and a resolver turns a fixed destination into an attacker-chosen one through\n * DNS rebinding, decimal and octal address spellings, and IPv4-mapped IPv6\n * forms. Refusing the parameter forecloses that family rather than filtering\n * it. Which of the two loopback literals actually answers is settled in\n * the loopbackAddress service, from the port alone.\n */\n\nimport { DEV_PROXY_PREFIX } from '../../constants/remote';\n\nconst MAX_NAME_LENGTH = 32;\n/**\n * Lowercase, digits and dashes, opening on an alphanumeric.\n *\n * The name is a path segment and it is also what the developer types into\n * `base: '/devproxy/<name>/'`, so it stays in the character set that needs no\n * escaping in either place.\n */\nconst TARGET_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/u;\nconst MIN_PORT = 1;\nconst MAX_PORT = 65_535;\n\nexport type NameVerdict = { ok: true; name: string } | { ok: false; reason: string };\n\nexport type PortVerdict = { ok: true; port: number } | { ok: false; reason: string };\n\nexport type ProxyPathVerdict =\n  | { kind: 'match'; name: string; /** The path unchanged, prefix included. */ upstreamPath: string }\n  | { kind: 'redirect'; location: string }\n  | { kind: 'reject'; reason: string };\n\nexport function validateTargetName(raw: unknown): NameVerdict {\n  if (typeof raw !== 'string') return { ok: false, reason: 'A target name must be text.' };\n  const name = raw.trim().toLowerCase();\n  if (name === '') return { ok: false, reason: 'A target needs a name.' };\n  if (name.length > MAX_NAME_LENGTH) {\n    return { ok: false, reason: `A target name is at most ${String(MAX_NAME_LENGTH)} characters.` };\n  }\n  if (!TARGET_NAME.test(name)) {\n    return {\n      ok: false,\n      reason: 'A target name uses lowercase letters, digits and dashes, starting with a letter or digit.',\n    };\n  }\n  return { ok: true, name };\n}\n\n/**\n * Whether this port may be proxied.\n *\n * `reserved` is read fresh by the caller on every attempt rather than captured\n * once, because the cockpit's own ports are only known after it binds and the\n * tunnel port changes when remote access is toggled. A cached list would go\n * stale in exactly the direction that matters, letting the proxy point at the\n * cockpit itself.\n */\nexport function validateTargetPort(raw: unknown, reserved: readonly (number | undefined)[]): PortVerdict {\n  const port = typeof raw === 'number' ? raw : Number(raw);\n  if (!Number.isSafeInteger(port)) return { ok: false, reason: 'A port must be a whole number.' };\n  if (port < MIN_PORT || port > MAX_PORT) {\n    return { ok: false, reason: `A port is between ${String(MIN_PORT)} and ${String(MAX_PORT)}.` };\n  }\n  if (reserved.includes(port)) return { ok: false, reason: 'That port belongs to the cockpit itself.' };\n  return { ok: true, port };\n}\n\n/**\n * Whether a path segment tries to climb out of the prefix.\n *\n * Checked before and after percent-decoding. A proxy that only checked the raw\n * form would forward `%2e%2e`, and an upstream that decodes before resolving\n * would then walk out of the tree the operator meant to expose.\n */\nfunction escapesPrefix(upstreamPath: string): boolean {\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(upstreamPath);\n  } catch {\n    // A malformed percent sequence is not a path this proxy needs to serve.\n    return true;\n  }\n  for (const candidate of [upstreamPath, decoded]) {\n    for (const segment of candidate.split('/')) {\n      if (segment === '.' || segment === '..') return true;\n    }\n  }\n  return false;\n}\n\n/**\n * Whether this path is one the dev proxy owns.\n *\n * The remote guard and the proxy handler must agree about this, and they do not\n * see the same string: Hono's router hands the guard a raw slice of the request\n * line, while the handler reads `new URL(...).pathname`, which resolves `..`\n * before anyone looks at it. So `/devproxy/x/../../api/health` can be a proxy\n * path to one and an API path to the other, and a guard that answered on the\n * prefix alone would grant an `/api/` request the direct, unsealed treatment.\n *\n * Refusing every dot segment removes the disagreement instead of trying to\n * predict it. A legitimate asset URL has no reason to carry one.\n */\nexport function isDevProxyPath(path: string): boolean {\n  if (!path.startsWith(DEV_PROXY_PREFIX)) return false;\n  return !escapesPrefix(path.slice(DEV_PROXY_PREFIX.length));\n}\n/**\n * Identifies the target a proxied request belongs to.\n *\n * `upstreamPath` is the request path unchanged, prefix included. That is the\n * whole trick, and getting it wrong costs a redirect loop: the target is\n * configured with `base: '/devproxy/<name>/'`, so it believes it is serving\n * there and redirects anything at `/` back to its base. Stripping the prefix\n * would hand it `/`, take its redirect, and go round again. nginx draws the\n * same distinction between `proxy_pass http://host/` and `proxy_pass\n * http://host`; this is the second one.\n *\n * Reads the raw, still-encoded pathname. Hono routes and the remote guard both\n * work on the decoded value, so a request that only becomes `/devproxy/...`\n * after decoding would reach this handler, and passing the encoded form\n * through untouched is what makes a file named `a b.png` load.\n */\nexport function parseProxyPath(rawPathname: string): ProxyPathVerdict {\n  if (!rawPathname.startsWith(DEV_PROXY_PREFIX)) return { kind: 'reject', reason: 'Not a proxied path.' };\n  const rest = rawPathname.slice(DEV_PROXY_PREFIX.length);\n  const boundary = rest.indexOf('/');\n\n  if (boundary === -1) {\n    const verdict = validateTargetName(rest);\n    if (!verdict.ok) return { kind: 'reject', reason: verdict.reason };\n    // A dev server serving at its own root needs the trailing slash, or every\n    // relative URL on the page resolves one level too high. nginx answers the\n    // same way rather than guessing.\n    return { kind: 'redirect', location: `${DEV_PROXY_PREFIX}${verdict.name}/` };\n  }\n\n  const verdict = validateTargetName(rest.slice(0, boundary));\n  if (!verdict.ok) return { kind: 'reject', reason: verdict.reason };\n  if (escapesPrefix(rest.slice(boundary))) {\n    return { kind: 'reject', reason: 'That path leaves the proxied target.' };\n  }\n  return { kind: 'match', name: verdict.name, upstreamPath: rawPathname };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,kBAAkB;;;;;;;;AAQxB,MAAM,cAAc;AACpB,MAAM,WAAW;AACjB,MAAM,WAAW;AAWjB,SAAgB,mBAAmB,KAA2B;CAC5D,IAAI,OAAO,QAAQ,UAAU,OAAO;EAAE,IAAI;EAAO,QAAQ;CAA8B;CACvF,MAAM,OAAO,IAAI,KAAK,CAAC,CAAC,YAAY;CACpC,IAAI,SAAS,IAAI,OAAO;EAAE,IAAI;EAAO,QAAQ;CAAyB;CACtE,IAAI,KAAK,SAAS,iBAChB,OAAO;EAAE,IAAI;EAAO,QAAQ,4BAA4B,OAAO,eAAe,EAAE;CAAc;CAEhG,IAAI,CAAC,YAAY,KAAK,IAAI,GACxB,OAAO;EACL,IAAI;EACJ,QAAQ;CACV;CAEF,OAAO;EAAE,IAAI;EAAM;CAAK;AAC1B;;;;;;;;;;AAWA,SAAgB,mBAAmB,KAAc,UAAwD;CACvG,MAAM,OAAO,OAAO,QAAQ,WAAW,MAAM,OAAO,GAAG;CACvD,IAAI,CAAC,OAAO,cAAc,IAAI,GAAG,OAAO;EAAE,IAAI;EAAO,QAAQ;CAAiC;CAC9F,IAAI,OAAO,YAAY,OAAO,UAC5B,OAAO;EAAE,IAAI;EAAO,QAAQ,qBAAqB,OAAO,QAAQ,EAAE,OAAO,OAAO,QAAQ,EAAE;CAAG;CAE/F,IAAI,SAAS,SAAS,IAAI,GAAG,OAAO;EAAE,IAAI;EAAO,QAAQ;CAA2C;CACpG,OAAO;EAAE,IAAI;EAAM;CAAK;AAC1B;;;;;;;;AASA,SAAS,cAAc,cAA+B;CACpD,IAAI;CACJ,IAAI;EACF,UAAU,mBAAmB,YAAY;CAC3C,QAAQ;EAEN,OAAO;CACT;CACA,KAAK,MAAM,aAAa,CAAC,cAAc,OAAO,GAC5C,KAAK,MAAM,WAAW,UAAU,MAAM,GAAG,GACvC,IAAI,YAAY,OAAO,YAAY,MAAM,OAAO;CAGpD,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,eAAe,MAAuB;CACpD,IAAI,CAAC,KAAK,WAAA,YAA2B,GAAG,OAAO;CAC/C,OAAO,CAAC,cAAc,KAAK,MAAMA,eAAAA,iBAAiB,MAAM,CAAC;AAC3D;;;;;;;;;;;;;;;;;AAiBA,SAAgB,eAAe,aAAuC;CACpE,IAAI,CAAC,YAAY,WAAA,YAA2B,GAAG,OAAO;EAAE,MAAM;EAAU,QAAQ;CAAsB;CACtG,MAAM,OAAO,YAAY,MAAMA,eAAAA,iBAAiB,MAAM;CACtD,MAAM,WAAW,KAAK,QAAQ,GAAG;CAEjC,IAAI,aAAa,IAAI;EACnB,MAAM,UAAU,mBAAmB,IAAI;EACvC,IAAI,CAAC,QAAQ,IAAI,OAAO;GAAE,MAAM;GAAU,QAAQ,QAAQ;EAAO;EAIjE,OAAO;GAAE,MAAM;GAAY,UAAU,GAAGA,eAAAA,mBAAmB,QAAQ,KAAK;EAAG;CAC7E;CAEA,MAAM,UAAU,mBAAmB,KAAK,MAAM,GAAG,QAAQ,CAAC;CAC1D,IAAI,CAAC,QAAQ,IAAI,OAAO;EAAE,MAAM;EAAU,QAAQ,QAAQ;CAAO;CACjE,IAAI,cAAc,KAAK,MAAM,QAAQ,CAAC,GACpC,OAAO;EAAE,MAAM;EAAU,QAAQ;CAAuC;CAE1E,OAAO;EAAE,MAAM;EAAS,MAAM,QAAQ;EAAM,cAAc;CAAY;AACxE"}

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

@@ -0,0 +1,165 @@
+import { DEV_PROXY_PREFIX } from "../../constants/remote.mjs";
+//#region src/services/devProxyPolicy/index.ts
+/**
+* What the dev proxy will forward, and where.
+*
+* Pure, with no I/O, so the whole decision surface of a feature that reaches
+* loopback services can be read in one sitting and tested without a server.
+*
+* The upstream host is not a parameter anywhere in this module, and a target
+* is a port and nothing else. Accepting a hostname would mean resolving one,
+* and a resolver turns a fixed destination into an attacker-chosen one through
+* DNS rebinding, decimal and octal address spellings, and IPv4-mapped IPv6
+* forms. Refusing the parameter forecloses that family rather than filtering
+* it. Which of the two loopback literals actually answers is settled in
+* the loopbackAddress service, from the port alone.
+*/
+const MAX_NAME_LENGTH = 32;
+/**
+* Lowercase, digits and dashes, opening on an alphanumeric.
+*
+* The name is a path segment and it is also what the developer types into
+* `base: '/devproxy/<name>/'`, so it stays in the character set that needs no
+* escaping in either place.
+*/
+const TARGET_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/u;
+const MIN_PORT = 1;
+const MAX_PORT = 65535;
+function validateTargetName(raw) {
+	if (typeof raw !== "string") return {
+		ok: false,
+		reason: "A target name must be text."
+	};
+	const name = raw.trim().toLowerCase();
+	if (name === "") return {
+		ok: false,
+		reason: "A target needs a name."
+	};
+	if (name.length > MAX_NAME_LENGTH) return {
+		ok: false,
+		reason: `A target name is at most ${String(MAX_NAME_LENGTH)} characters.`
+	};
+	if (!TARGET_NAME.test(name)) return {
+		ok: false,
+		reason: "A target name uses lowercase letters, digits and dashes, starting with a letter or digit."
+	};
+	return {
+		ok: true,
+		name
+	};
+}
+/**
+* Whether this port may be proxied.
+*
+* `reserved` is read fresh by the caller on every attempt rather than captured
+* once, because the cockpit's own ports are only known after it binds and the
+* tunnel port changes when remote access is toggled. A cached list would go
+* stale in exactly the direction that matters, letting the proxy point at the
+* cockpit itself.
+*/
+function validateTargetPort(raw, reserved) {
+	const port = typeof raw === "number" ? raw : Number(raw);
+	if (!Number.isSafeInteger(port)) return {
+		ok: false,
+		reason: "A port must be a whole number."
+	};
+	if (port < MIN_PORT || port > MAX_PORT) return {
+		ok: false,
+		reason: `A port is between ${String(MIN_PORT)} and ${String(MAX_PORT)}.`
+	};
+	if (reserved.includes(port)) return {
+		ok: false,
+		reason: "That port belongs to the cockpit itself."
+	};
+	return {
+		ok: true,
+		port
+	};
+}
+/**
+* Whether a path segment tries to climb out of the prefix.
+*
+* Checked before and after percent-decoding. A proxy that only checked the raw
+* form would forward `%2e%2e`, and an upstream that decodes before resolving
+* would then walk out of the tree the operator meant to expose.
+*/
+function escapesPrefix(upstreamPath) {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(upstreamPath);
+	} catch {
+		return true;
+	}
+	for (const candidate of [upstreamPath, decoded]) for (const segment of candidate.split("/")) if (segment === "." || segment === "..") return true;
+	return false;
+}
+/**
+* Whether this path is one the dev proxy owns.
+*
+* The remote guard and the proxy handler must agree about this, and they do not
+* see the same string: Hono's router hands the guard a raw slice of the request
+* line, while the handler reads `new URL(...).pathname`, which resolves `..`
+* before anyone looks at it. So `/devproxy/x/../../api/health` can be a proxy
+* path to one and an API path to the other, and a guard that answered on the
+* prefix alone would grant an `/api/` request the direct, unsealed treatment.
+*
+* Refusing every dot segment removes the disagreement instead of trying to
+* predict it. A legitimate asset URL has no reason to carry one.
+*/
+function isDevProxyPath(path) {
+	if (!path.startsWith("/devproxy/")) return false;
+	return !escapesPrefix(path.slice(DEV_PROXY_PREFIX.length));
+}
+/**
+* Identifies the target a proxied request belongs to.
+*
+* `upstreamPath` is the request path unchanged, prefix included. That is the
+* whole trick, and getting it wrong costs a redirect loop: the target is
+* configured with `base: '/devproxy/<name>/'`, so it believes it is serving
+* there and redirects anything at `/` back to its base. Stripping the prefix
+* would hand it `/`, take its redirect, and go round again. nginx draws the
+* same distinction between `proxy_pass http://host/` and `proxy_pass
+* http://host`; this is the second one.
+*
+* Reads the raw, still-encoded pathname. Hono routes and the remote guard both
+* work on the decoded value, so a request that only becomes `/devproxy/...`
+* after decoding would reach this handler, and passing the encoded form
+* through untouched is what makes a file named `a b.png` load.
+*/
+function parseProxyPath(rawPathname) {
+	if (!rawPathname.startsWith("/devproxy/")) return {
+		kind: "reject",
+		reason: "Not a proxied path."
+	};
+	const rest = rawPathname.slice(DEV_PROXY_PREFIX.length);
+	const boundary = rest.indexOf("/");
+	if (boundary === -1) {
+		const verdict = validateTargetName(rest);
+		if (!verdict.ok) return {
+			kind: "reject",
+			reason: verdict.reason
+		};
+		return {
+			kind: "redirect",
+			location: `${DEV_PROXY_PREFIX}${verdict.name}/`
+		};
+	}
+	const verdict = validateTargetName(rest.slice(0, boundary));
+	if (!verdict.ok) return {
+		kind: "reject",
+		reason: verdict.reason
+	};
+	if (escapesPrefix(rest.slice(boundary))) return {
+		kind: "reject",
+		reason: "That path leaves the proxied target."
+	};
+	return {
+		kind: "match",
+		name: verdict.name,
+		upstreamPath: rawPathname
+	};
+}
+//#endregion
+export { isDevProxyPath, parseProxyPath, validateTargetName, validateTargetPort };
+
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/devProxyPolicy/index.ts"],"sourcesContent":["/**\n * What the dev proxy will forward, and where.\n *\n * Pure, with no I/O, so the whole decision surface of a feature that reaches\n * loopback services can be read in one sitting and tested without a server.\n *\n * The upstream host is not a parameter anywhere in this module, and a target\n * is a port and nothing else. Accepting a hostname would mean resolving one,\n * and a resolver turns a fixed destination into an attacker-chosen one through\n * DNS rebinding, decimal and octal address spellings, and IPv4-mapped IPv6\n * forms. Refusing the parameter forecloses that family rather than filtering\n * it. Which of the two loopback literals actually answers is settled in\n * the loopbackAddress service, from the port alone.\n */\n\nimport { DEV_PROXY_PREFIX } from '../../constants/remote';\n\nconst MAX_NAME_LENGTH = 32;\n/**\n * Lowercase, digits and dashes, opening on an alphanumeric.\n *\n * The name is a path segment and it is also what the developer types into\n * `base: '/devproxy/<name>/'`, so it stays in the character set that needs no\n * escaping in either place.\n */\nconst TARGET_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/u;\nconst MIN_PORT = 1;\nconst MAX_PORT = 65_535;\n\nexport type NameVerdict = { ok: true; name: string } | { ok: false; reason: string };\n\nexport type PortVerdict = { ok: true; port: number } | { ok: false; reason: string };\n\nexport type ProxyPathVerdict =\n  | { kind: 'match'; name: string; /** The path unchanged, prefix included. */ upstreamPath: string }\n  | { kind: 'redirect'; location: string }\n  | { kind: 'reject'; reason: string };\n\nexport function validateTargetName(raw: unknown): NameVerdict {\n  if (typeof raw !== 'string') return { ok: false, reason: 'A target name must be text.' };\n  const name = raw.trim().toLowerCase();\n  if (name === '') return { ok: false, reason: 'A target needs a name.' };\n  if (name.length > MAX_NAME_LENGTH) {\n    return { ok: false, reason: `A target name is at most ${String(MAX_NAME_LENGTH)} characters.` };\n  }\n  if (!TARGET_NAME.test(name)) {\n    return {\n      ok: false,\n      reason: 'A target name uses lowercase letters, digits and dashes, starting with a letter or digit.',\n    };\n  }\n  return { ok: true, name };\n}\n\n/**\n * Whether this port may be proxied.\n *\n * `reserved` is read fresh by the caller on every attempt rather than captured\n * once, because the cockpit's own ports are only known after it binds and the\n * tunnel port changes when remote access is toggled. A cached list would go\n * stale in exactly the direction that matters, letting the proxy point at the\n * cockpit itself.\n */\nexport function validateTargetPort(raw: unknown, reserved: readonly (number | undefined)[]): PortVerdict {\n  const port = typeof raw === 'number' ? raw : Number(raw);\n  if (!Number.isSafeInteger(port)) return { ok: false, reason: 'A port must be a whole number.' };\n  if (port < MIN_PORT || port > MAX_PORT) {\n    return { ok: false, reason: `A port is between ${String(MIN_PORT)} and ${String(MAX_PORT)}.` };\n  }\n  if (reserved.includes(port)) return { ok: false, reason: 'That port belongs to the cockpit itself.' };\n  return { ok: true, port };\n}\n\n/**\n * Whether a path segment tries to climb out of the prefix.\n *\n * Checked before and after percent-decoding. A proxy that only checked the raw\n * form would forward `%2e%2e`, and an upstream that decodes before resolving\n * would then walk out of the tree the operator meant to expose.\n */\nfunction escapesPrefix(upstreamPath: string): boolean {\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(upstreamPath);\n  } catch {\n    // A malformed percent sequence is not a path this proxy needs to serve.\n    return true;\n  }\n  for (const candidate of [upstreamPath, decoded]) {\n    for (const segment of candidate.split('/')) {\n      if (segment === '.' || segment === '..') return true;\n    }\n  }\n  return false;\n}\n\n/**\n * Whether this path is one the dev proxy owns.\n *\n * The remote guard and the proxy handler must agree about this, and they do not\n * see the same string: Hono's router hands the guard a raw slice of the request\n * line, while the handler reads `new URL(...).pathname`, which resolves `..`\n * before anyone looks at it. So `/devproxy/x/../../api/health` can be a proxy\n * path to one and an API path to the other, and a guard that answered on the\n * prefix alone would grant an `/api/` request the direct, unsealed treatment.\n *\n * Refusing every dot segment removes the disagreement instead of trying to\n * predict it. A legitimate asset URL has no reason to carry one.\n */\nexport function isDevProxyPath(path: string): boolean {\n  if (!path.startsWith(DEV_PROXY_PREFIX)) return false;\n  return !escapesPrefix(path.slice(DEV_PROXY_PREFIX.length));\n}\n/**\n * Identifies the target a proxied request belongs to.\n *\n * `upstreamPath` is the request path unchanged, prefix included. That is the\n * whole trick, and getting it wrong costs a redirect loop: the target is\n * configured with `base: '/devproxy/<name>/'`, so it believes it is serving\n * there and redirects anything at `/` back to its base. Stripping the prefix\n * would hand it `/`, take its redirect, and go round again. nginx draws the\n * same distinction between `proxy_pass http://host/` and `proxy_pass\n * http://host`; this is the second one.\n *\n * Reads the raw, still-encoded pathname. Hono routes and the remote guard both\n * work on the decoded value, so a request that only becomes `/devproxy/...`\n * after decoding would reach this handler, and passing the encoded form\n * through untouched is what makes a file named `a b.png` load.\n */\nexport function parseProxyPath(rawPathname: string): ProxyPathVerdict {\n  if (!rawPathname.startsWith(DEV_PROXY_PREFIX)) return { kind: 'reject', reason: 'Not a proxied path.' };\n  const rest = rawPathname.slice(DEV_PROXY_PREFIX.length);\n  const boundary = rest.indexOf('/');\n\n  if (boundary === -1) {\n    const verdict = validateTargetName(rest);\n    if (!verdict.ok) return { kind: 'reject', reason: verdict.reason };\n    // A dev server serving at its own root needs the trailing slash, or every\n    // relative URL on the page resolves one level too high. nginx answers the\n    // same way rather than guessing.\n    return { kind: 'redirect', location: `${DEV_PROXY_PREFIX}${verdict.name}/` };\n  }\n\n  const verdict = validateTargetName(rest.slice(0, boundary));\n  if (!verdict.ok) return { kind: 'reject', reason: verdict.reason };\n  if (escapesPrefix(rest.slice(boundary))) {\n    return { kind: 'reject', reason: 'That path leaves the proxied target.' };\n  }\n  return { kind: 'match', name: verdict.name, upstreamPath: rawPathname };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,kBAAkB;;;;;;;;AAQxB,MAAM,cAAc;AACpB,MAAM,WAAW;AACjB,MAAM,WAAW;AAWjB,SAAgB,mBAAmB,KAA2B;CAC5D,IAAI,OAAO,QAAQ,UAAU,OAAO;EAAE,IAAI;EAAO,QAAQ;CAA8B;CACvF,MAAM,OAAO,IAAI,KAAK,CAAC,CAAC,YAAY;CACpC,IAAI,SAAS,IAAI,OAAO;EAAE,IAAI;EAAO,QAAQ;CAAyB;CACtE,IAAI,KAAK,SAAS,iBAChB,OAAO;EAAE,IAAI;EAAO,QAAQ,4BAA4B,OAAO,eAAe,EAAE;CAAc;CAEhG,IAAI,CAAC,YAAY,KAAK,IAAI,GACxB,OAAO;EACL,IAAI;EACJ,QAAQ;CACV;CAEF,OAAO;EAAE,IAAI;EAAM;CAAK;AAC1B;;;;;;;;;;AAWA,SAAgB,mBAAmB,KAAc,UAAwD;CACvG,MAAM,OAAO,OAAO,QAAQ,WAAW,MAAM,OAAO,GAAG;CACvD,IAAI,CAAC,OAAO,cAAc,IAAI,GAAG,OAAO;EAAE,IAAI;EAAO,QAAQ;CAAiC;CAC9F,IAAI,OAAO,YAAY,OAAO,UAC5B,OAAO;EAAE,IAAI;EAAO,QAAQ,qBAAqB,OAAO,QAAQ,EAAE,OAAO,OAAO,QAAQ,EAAE;CAAG;CAE/F,IAAI,SAAS,SAAS,IAAI,GAAG,OAAO;EAAE,IAAI;EAAO,QAAQ;CAA2C;CACpG,OAAO;EAAE,IAAI;EAAM;CAAK;AAC1B;;;;;;;;AASA,SAAS,cAAc,cAA+B;CACpD,IAAI;CACJ,IAAI;EACF,UAAU,mBAAmB,YAAY;CAC3C,QAAQ;EAEN,OAAO;CACT;CACA,KAAK,MAAM,aAAa,CAAC,cAAc,OAAO,GAC5C,KAAK,MAAM,WAAW,UAAU,MAAM,GAAG,GACvC,IAAI,YAAY,OAAO,YAAY,MAAM,OAAO;CAGpD,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,eAAe,MAAuB;CACpD,IAAI,CAAC,KAAK,WAAA,YAA2B,GAAG,OAAO;CAC/C,OAAO,CAAC,cAAc,KAAK,MAAM,iBAAiB,MAAM,CAAC;AAC3D;;;;;;;;;;;;;;;;;AAiBA,SAAgB,eAAe,aAAuC;CACpE,IAAI,CAAC,YAAY,WAAA,YAA2B,GAAG,OAAO;EAAE,MAAM;EAAU,QAAQ;CAAsB;CACtG,MAAM,OAAO,YAAY,MAAM,iBAAiB,MAAM;CACtD,MAAM,WAAW,KAAK,QAAQ,GAAG;CAEjC,IAAI,aAAa,IAAI;EACnB,MAAM,UAAU,mBAAmB,IAAI;EACvC,IAAI,CAAC,QAAQ,IAAI,OAAO;GAAE,MAAM;GAAU,QAAQ,QAAQ;EAAO;EAIjE,OAAO;GAAE,MAAM;GAAY,UAAU,GAAG,mBAAmB,QAAQ,KAAK;EAAG;CAC7E;CAEA,MAAM,UAAU,mBAAmB,KAAK,MAAM,GAAG,QAAQ,CAAC;CAC1D,IAAI,CAAC,QAAQ,IAAI,OAAO;EAAE,MAAM;EAAU,QAAQ,QAAQ;CAAO;CACjE,IAAI,cAAc,KAAK,MAAM,QAAQ,CAAC,GACpC,OAAO;EAAE,MAAM;EAAU,QAAQ;CAAuC;CAE1E,OAAO;EAAE,MAAM;EAAS,MAAM,QAAQ;EAAM,cAAc;CAAY;AACxE"}

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

@@ -0,0 +1,107 @@
+const require_runtime = require("../../../_virtual/_rolldown/runtime.cjs");
+const require_index = require("../devProxyPolicy/index.cjs");
+let node_fs = require("node:fs");
+node_fs = require_runtime.__toESM(node_fs, 1);
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path, 1);
+//#region src/services/devProxyStore/index.ts
+/**
+* Registered proxy targets on disk.
+*
+* Persisted, unlike a remote session, because a target is a name the developer
+* typed into their own build configuration as `base: '/devproxy/<name>/'`.
+* Losing it on restart would silently break that line, and the file holds no
+* secret: a port number and a label the operator chose while sitting at the
+* machine.
+*/
+const TARGETS_FILE = "dev-proxy.json";
+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;
+/** Repairs a state file another account can read. */
+function tightenMode(filePath, notice) {
+	try {
+		if ((node_fs.default.statSync(filePath).mode & LOOSE_MODE_MASK) === 0) return;
+		node_fs.default.chmodSync(filePath, FILE_MODE);
+		notice(`tightened permissions on ${filePath}`);
+	} catch {}
+}
+/**
+* Rebuilds one record, dropping anything the current policy would refuse.
+*
+* The file is revalidated on read rather than trusted, because a name that was
+* legal when written is not necessarily legal now, and an edited file must not
+* be able to introduce a target the API would have rejected.
+*/
+function parseTarget(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const record = value;
+	const name = require_index.validateTargetName(record.name);
+	if (!name.ok) return void 0;
+	if (typeof record.port !== "number" || !Number.isSafeInteger(record.port)) return void 0;
+	const createdAt = typeof record.createdAt === "number" ? record.createdAt : 0;
+	return {
+		name: name.name,
+		port: record.port,
+		createdAt
+	};
+}
+function createDevProxyStore(options) {
+	const notice = options.onNotice ?? (() => {});
+	const targetsPath = node_path.default.join(options.stateDir, TARGETS_FILE);
+	let held = load();
+	function load() {
+		let raw;
+		try {
+			raw = node_fs.default.readFileSync(targetsPath, "utf8");
+		} catch {
+			return [];
+		}
+		tightenMode(targetsPath, notice);
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			notice(`dev proxy targets at ${targetsPath} are not valid JSON; none will load`);
+			return [];
+		}
+		if (!Array.isArray(parsed)) return [];
+		return parsed.map(parseTarget).filter((target) => target !== void 0);
+	}
+	function write() {
+		const temporary = `${targetsPath}.${String(process.pid)}.tmp`;
+		try {
+			node_fs.default.mkdirSync(options.stateDir, {
+				recursive: true,
+				mode: DIRECTORY_MODE
+			});
+			node_fs.default.writeFileSync(temporary, `${JSON.stringify(held, void 0, 2)}\n`, { mode: FILE_MODE });
+			node_fs.default.renameSync(temporary, targetsPath);
+		} catch (error) {
+			notice(`${targetsPath} could not be saved: ${error instanceof Error ? error.message : String(error)}`);
+			try {
+				node_fs.default.rmSync(temporary, { force: true });
+			} catch {}
+		}
+	}
+	return {
+		targets: () => held,
+		find: (name) => held.find((target) => target.name === name),
+		save(target) {
+			held = [...held.filter((existing) => existing.name !== target.name), target];
+			write();
+		},
+		remove(name) {
+			const next = held.filter((existing) => existing.name !== name);
+			if (next.length === held.length) return false;
+			held = next;
+			write();
+			return true;
+		}
+	};
+}
+//#endregion
+exports.createDevProxyStore = createDevProxyStore;
+
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["fs","validateTargetName","path"],"sources":["../../../../src/services/devProxyStore/index.ts"],"sourcesContent":["import fs from 'node:fs';\nimport path from 'node:path';\n\nimport type { DevProxyTarget } from '../../types/remote';\nimport { validateTargetName } from '../devProxyPolicy';\n\n/**\n * Registered proxy targets on disk.\n *\n * Persisted, unlike a remote session, because a target is a name the developer\n * typed into their own build configuration as `base: '/devproxy/<name>/'`.\n * Losing it on restart would silently break that line, and the file holds no\n * secret: a port number and a label the operator chose while sitting at the\n * machine.\n */\n\nconst TARGETS_FILE = 'dev-proxy.json';\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 DevProxyStoreOptions {\n  /** The same directory the remote-access store uses; defaults to ~/.po/web. */\n  stateDir: string;\n  onNotice?: (message: string) => void;\n}\n\nexport interface DevProxyStore {\n  targets(): readonly DevProxyTarget[];\n  find(name: string): DevProxyTarget | undefined;\n  /** Replaces any target already holding this name, so re-registering a moved port is one call. */\n  save(target: DevProxyTarget): void;\n  remove(name: string): boolean;\n}\n\n/** Repairs a state file another account can read. */\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/**\n * Rebuilds one record, dropping anything the current policy would refuse.\n *\n * The file is revalidated on read rather than trusted, because a name that was\n * legal when written is not necessarily legal now, and an edited file must not\n * be able to introduce a target the API would have rejected.\n */\nfunction parseTarget(value: unknown): DevProxyTarget | undefined {\n  if (typeof value !== 'object' || value === null) return undefined;\n  const record = value as Partial<DevProxyTarget>;\n  const name = validateTargetName(record.name);\n  if (!name.ok) return undefined;\n  if (typeof record.port !== 'number' || !Number.isSafeInteger(record.port)) return undefined;\n  const createdAt = typeof record.createdAt === 'number' ? record.createdAt : 0;\n  return { name: name.name, port: record.port, createdAt };\n}\n\nexport function createDevProxyStore(options: DevProxyStoreOptions): DevProxyStore {\n  const notice = options.onNotice ?? ((): void => {});\n  const targetsPath = path.join(options.stateDir, TARGETS_FILE);\n  let held = load();\n\n  function load(): DevProxyTarget[] {\n    let raw: string;\n    try {\n      raw = fs.readFileSync(targetsPath, 'utf8');\n    } catch {\n      // No file is the normal first run, so this is not worth a notice.\n      return [];\n    }\n    tightenMode(targetsPath, notice);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      notice(`dev proxy targets at ${targetsPath} are not valid JSON; none will load`);\n      return [];\n    }\n    if (!Array.isArray(parsed)) return [];\n    return parsed.map(parseTarget).filter((target): target is DevProxyTarget => target !== undefined);\n  }\n\n  function write(): void {\n    const temporary = `${targetsPath}.${String(process.pid)}.tmp`;\n    try {\n      fs.mkdirSync(options.stateDir, { recursive: true, mode: DIRECTORY_MODE });\n      fs.writeFileSync(temporary, `${JSON.stringify(held, 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, targetsPath);\n    } catch (error) {\n      notice(`${targetsPath} 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    targets: () => held,\n    find: (name) => held.find((target) => target.name === name),\n\n    save(target) {\n      held = [...held.filter((existing) => existing.name !== target.name), target];\n      write();\n    },\n\n    remove(name) {\n      const next = held.filter((existing) => existing.name !== name);\n      if (next.length === held.length) return false;\n      held = next;\n      write();\n      return true;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,MAAM,eAAe;AACrB,MAAM,iBAAiB;AACvB,MAAM,YAAY;;AAElB,MAAM,kBAAkB;;AAiBxB,SAAS,YAAY,UAAkB,QAAyC;CAC9E,IAAI;EACF,KAAKA,QAAAA,QAAG,SAAS,QAAQ,CAAC,CAAC,OAAO,qBAAqB,GAAG;EAC1D,QAAA,QAAG,UAAU,UAAU,SAAS;EAChC,OAAO,4BAA4B,UAAU;CAC/C,QAAQ,CAER;AACF;;;;;;;;AASA,SAAS,YAAY,OAA4C;CAC/D,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO,KAAA;CACxD,MAAM,SAAS;CACf,MAAM,OAAOC,cAAAA,mBAAmB,OAAO,IAAI;CAC3C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAA;CACrB,IAAI,OAAO,OAAO,SAAS,YAAY,CAAC,OAAO,cAAc,OAAO,IAAI,GAAG,OAAO,KAAA;CAClF,MAAM,YAAY,OAAO,OAAO,cAAc,WAAW,OAAO,YAAY;CAC5E,OAAO;EAAE,MAAM,KAAK;EAAM,MAAM,OAAO;EAAM;CAAU;AACzD;AAEA,SAAgB,oBAAoB,SAA8C;CAChF,MAAM,SAAS,QAAQ,mBAAyB,CAAC;CACjD,MAAM,cAAcC,UAAAA,QAAK,KAAK,QAAQ,UAAU,YAAY;CAC5D,IAAI,OAAO,KAAK;CAEhB,SAAS,OAAyB;EAChC,IAAI;EACJ,IAAI;GACF,MAAMF,QAAAA,QAAG,aAAa,aAAa,MAAM;EAC3C,QAAQ;GAEN,OAAO,CAAC;EACV;EACA,YAAY,aAAa,MAAM;EAC/B,IAAI;EACJ,IAAI;GACF,SAAS,KAAK,MAAM,GAAG;EACzB,QAAQ;GACN,OAAO,wBAAwB,YAAY,oCAAoC;GAC/E,OAAO,CAAC;EACV;EACA,IAAI,CAAC,MAAM,QAAQ,MAAM,GAAG,OAAO,CAAC;EACpC,OAAO,OAAO,IAAI,WAAW,CAAC,CAAC,QAAQ,WAAqC,WAAW,KAAA,CAAS;CAClG;CAEA,SAAS,QAAc;EACrB,MAAM,YAAY,GAAG,YAAY,GAAG,OAAO,QAAQ,GAAG,EAAE;EACxD,IAAI;GACF,QAAA,QAAG,UAAU,QAAQ,UAAU;IAAE,WAAW;IAAM,MAAM;GAAe,CAAC;GACxE,QAAA,QAAG,cAAc,WAAW,GAAG,KAAK,UAAU,MAAM,KAAA,GAAW,CAAC,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;GAG1F,QAAA,QAAG,WAAW,WAAW,WAAW;EACtC,SAAS,OAAO;GACd,OAAO,GAAG,YAAY,uBAAuB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAAG;GACrG,IAAI;IACF,QAAA,QAAG,OAAO,WAAW,EAAE,OAAO,KAAK,CAAC;GACtC,QAAQ,CAER;EACF;CACF;CAEA,OAAO;EACL,eAAe;EACf,OAAO,SAAS,KAAK,MAAM,WAAW,OAAO,SAAS,IAAI;EAE1D,KAAK,QAAQ;GACX,OAAO,CAAC,GAAG,KAAK,QAAQ,aAAa,SAAS,SAAS,OAAO,IAAI,GAAG,MAAM;GAC3E,MAAM;EACR;EAEA,OAAO,MAAM;GACX,MAAM,OAAO,KAAK,QAAQ,aAAa,SAAS,SAAS,IAAI;GAC7D,IAAI,KAAK,WAAW,KAAK,QAAQ,OAAO;GACxC,OAAO;GACP,MAAM;GACN,OAAO;EACT;CACF;AACF"}

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

@@ -0,0 +1,104 @@
+import { validateTargetName } from "../devProxyPolicy/index.mjs";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/services/devProxyStore/index.ts
+/**
+* Registered proxy targets on disk.
+*
+* Persisted, unlike a remote session, because a target is a name the developer
+* typed into their own build configuration as `base: '/devproxy/<name>/'`.
+* Losing it on restart would silently break that line, and the file holds no
+* secret: a port number and a label the operator chose while sitting at the
+* machine.
+*/
+const TARGETS_FILE = "dev-proxy.json";
+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;
+/** Repairs a state file another account can read. */
+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 {}
+}
+/**
+* Rebuilds one record, dropping anything the current policy would refuse.
+*
+* The file is revalidated on read rather than trusted, because a name that was
+* legal when written is not necessarily legal now, and an edited file must not
+* be able to introduce a target the API would have rejected.
+*/
+function parseTarget(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const record = value;
+	const name = validateTargetName(record.name);
+	if (!name.ok) return void 0;
+	if (typeof record.port !== "number" || !Number.isSafeInteger(record.port)) return void 0;
+	const createdAt = typeof record.createdAt === "number" ? record.createdAt : 0;
+	return {
+		name: name.name,
+		port: record.port,
+		createdAt
+	};
+}
+function createDevProxyStore(options) {
+	const notice = options.onNotice ?? (() => {});
+	const targetsPath = path.join(options.stateDir, TARGETS_FILE);
+	let held = load();
+	function load() {
+		let raw;
+		try {
+			raw = fs.readFileSync(targetsPath, "utf8");
+		} catch {
+			return [];
+		}
+		tightenMode(targetsPath, notice);
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			notice(`dev proxy targets at ${targetsPath} are not valid JSON; none will load`);
+			return [];
+		}
+		if (!Array.isArray(parsed)) return [];
+		return parsed.map(parseTarget).filter((target) => target !== void 0);
+	}
+	function write() {
+		const temporary = `${targetsPath}.${String(process.pid)}.tmp`;
+		try {
+			fs.mkdirSync(options.stateDir, {
+				recursive: true,
+				mode: DIRECTORY_MODE
+			});
+			fs.writeFileSync(temporary, `${JSON.stringify(held, void 0, 2)}\n`, { mode: FILE_MODE });
+			fs.renameSync(temporary, targetsPath);
+		} catch (error) {
+			notice(`${targetsPath} could not be saved: ${error instanceof Error ? error.message : String(error)}`);
+			try {
+				fs.rmSync(temporary, { force: true });
+			} catch {}
+		}
+	}
+	return {
+		targets: () => held,
+		find: (name) => held.find((target) => target.name === name),
+		save(target) {
+			held = [...held.filter((existing) => existing.name !== target.name), target];
+			write();
+		},
+		remove(name) {
+			const next = held.filter((existing) => existing.name !== name);
+			if (next.length === held.length) return false;
+			held = next;
+			write();
+			return true;
+		}
+	};
+}
+//#endregion
+export { createDevProxyStore };
+
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/devProxyStore/index.ts"],"sourcesContent":["import fs from 'node:fs';\nimport path from 'node:path';\n\nimport type { DevProxyTarget } from '../../types/remote';\nimport { validateTargetName } from '../devProxyPolicy';\n\n/**\n * Registered proxy targets on disk.\n *\n * Persisted, unlike a remote session, because a target is a name the developer\n * typed into their own build configuration as `base: '/devproxy/<name>/'`.\n * Losing it on restart would silently break that line, and the file holds no\n * secret: a port number and a label the operator chose while sitting at the\n * machine.\n */\n\nconst TARGETS_FILE = 'dev-proxy.json';\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 DevProxyStoreOptions {\n  /** The same directory the remote-access store uses; defaults to ~/.po/web. */\n  stateDir: string;\n  onNotice?: (message: string) => void;\n}\n\nexport interface DevProxyStore {\n  targets(): readonly DevProxyTarget[];\n  find(name: string): DevProxyTarget | undefined;\n  /** Replaces any target already holding this name, so re-registering a moved port is one call. */\n  save(target: DevProxyTarget): void;\n  remove(name: string): boolean;\n}\n\n/** Repairs a state file another account can read. */\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/**\n * Rebuilds one record, dropping anything the current policy would refuse.\n *\n * The file is revalidated on read rather than trusted, because a name that was\n * legal when written is not necessarily legal now, and an edited file must not\n * be able to introduce a target the API would have rejected.\n */\nfunction parseTarget(value: unknown): DevProxyTarget | undefined {\n  if (typeof value !== 'object' || value === null) return undefined;\n  const record = value as Partial<DevProxyTarget>;\n  const name = validateTargetName(record.name);\n  if (!name.ok) return undefined;\n  if (typeof record.port !== 'number' || !Number.isSafeInteger(record.port)) return undefined;\n  const createdAt = typeof record.createdAt === 'number' ? record.createdAt : 0;\n  return { name: name.name, port: record.port, createdAt };\n}\n\nexport function createDevProxyStore(options: DevProxyStoreOptions): DevProxyStore {\n  const notice = options.onNotice ?? ((): void => {});\n  const targetsPath = path.join(options.stateDir, TARGETS_FILE);\n  let held = load();\n\n  function load(): DevProxyTarget[] {\n    let raw: string;\n    try {\n      raw = fs.readFileSync(targetsPath, 'utf8');\n    } catch {\n      // No file is the normal first run, so this is not worth a notice.\n      return [];\n    }\n    tightenMode(targetsPath, notice);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      notice(`dev proxy targets at ${targetsPath} are not valid JSON; none will load`);\n      return [];\n    }\n    if (!Array.isArray(parsed)) return [];\n    return parsed.map(parseTarget).filter((target): target is DevProxyTarget => target !== undefined);\n  }\n\n  function write(): void {\n    const temporary = `${targetsPath}.${String(process.pid)}.tmp`;\n    try {\n      fs.mkdirSync(options.stateDir, { recursive: true, mode: DIRECTORY_MODE });\n      fs.writeFileSync(temporary, `${JSON.stringify(held, 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, targetsPath);\n    } catch (error) {\n      notice(`${targetsPath} 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    targets: () => held,\n    find: (name) => held.find((target) => target.name === name),\n\n    save(target) {\n      held = [...held.filter((existing) => existing.name !== target.name), target];\n      write();\n    },\n\n    remove(name) {\n      const next = held.filter((existing) => existing.name !== name);\n      if (next.length === held.length) return false;\n      held = next;\n      write();\n      return true;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AAgBA,MAAM,eAAe;AACrB,MAAM,iBAAiB;AACvB,MAAM,YAAY;;AAElB,MAAM,kBAAkB;;AAiBxB,SAAS,YAAY,UAAkB,QAAyC;CAC9E,IAAI;EACF,KAAK,GAAG,SAAS,QAAQ,CAAC,CAAC,OAAO,qBAAqB,GAAG;EAC1D,GAAG,UAAU,UAAU,SAAS;EAChC,OAAO,4BAA4B,UAAU;CAC/C,QAAQ,CAER;AACF;;;;;;;;AASA,SAAS,YAAY,OAA4C;CAC/D,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO,KAAA;CACxD,MAAM,SAAS;CACf,MAAM,OAAO,mBAAmB,OAAO,IAAI;CAC3C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAA;CACrB,IAAI,OAAO,OAAO,SAAS,YAAY,CAAC,OAAO,cAAc,OAAO,IAAI,GAAG,OAAO,KAAA;CAClF,MAAM,YAAY,OAAO,OAAO,cAAc,WAAW,OAAO,YAAY;CAC5E,OAAO;EAAE,MAAM,KAAK;EAAM,MAAM,OAAO;EAAM;CAAU;AACzD;AAEA,SAAgB,oBAAoB,SAA8C;CAChF,MAAM,SAAS,QAAQ,mBAAyB,CAAC;CACjD,MAAM,cAAc,KAAK,KAAK,QAAQ,UAAU,YAAY;CAC5D,IAAI,OAAO,KAAK;CAEhB,SAAS,OAAyB;EAChC,IAAI;EACJ,IAAI;GACF,MAAM,GAAG,aAAa,aAAa,MAAM;EAC3C,QAAQ;GAEN,OAAO,CAAC;EACV;EACA,YAAY,aAAa,MAAM;EAC/B,IAAI;EACJ,IAAI;GACF,SAAS,KAAK,MAAM,GAAG;EACzB,QAAQ;GACN,OAAO,wBAAwB,YAAY,oCAAoC;GAC/E,OAAO,CAAC;EACV;EACA,IAAI,CAAC,MAAM,QAAQ,MAAM,GAAG,OAAO,CAAC;EACpC,OAAO,OAAO,IAAI,WAAW,CAAC,CAAC,QAAQ,WAAqC,WAAW,KAAA,CAAS;CAClG;CAEA,SAAS,QAAc;EACrB,MAAM,YAAY,GAAG,YAAY,GAAG,OAAO,QAAQ,GAAG,EAAE;EACxD,IAAI;GACF,GAAG,UAAU,QAAQ,UAAU;IAAE,WAAW;IAAM,MAAM;GAAe,CAAC;GACxE,GAAG,cAAc,WAAW,GAAG,KAAK,UAAU,MAAM,KAAA,GAAW,CAAC,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;GAG1F,GAAG,WAAW,WAAW,WAAW;EACtC,SAAS,OAAO;GACd,OAAO,GAAG,YAAY,uBAAuB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAAG;GACrG,IAAI;IACF,GAAG,OAAO,WAAW,EAAE,OAAO,KAAK,CAAC;GACtC,QAAQ,CAER;EACF;CACF;CAEA,OAAO;EACL,eAAe;EACf,OAAO,SAAS,KAAK,MAAM,WAAW,OAAO,SAAS,IAAI;EAE1D,KAAK,QAAQ;GACX,OAAO,CAAC,GAAG,KAAK,QAAQ,aAAa,SAAS,SAAS,OAAO,IAAI,GAAG,MAAM;GAC3E,MAAM;EACR;EAEA,OAAO,MAAM;GACX,MAAM,OAAO,KAAK,QAAQ,aAAa,SAAS,SAAS,IAAI;GAC7D,IAAI,KAAK,WAAW,KAAK,QAAQ,OAAO;GACxC,OAAO;GACP,MAAM;GACN,OAAO;EACT;CACF;AACF"}