@agimon-ai/doompi-core 0.0.1-alpha.100

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 ~/.doompi/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 ~/.doompi/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"}

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

@@ -0,0 +1,125 @@
+const require_index = require("../deviceSessions/index.cjs");
+let node_crypto = require("node:crypto");
+//#region src/services/deviceAuth/index.ts
+/** 256 bits. The token is scanned or set by the server, never typed, so there is no reason to economise. */
+const TOKEN_BYTES = 32;
+const ID_BYTES = 8;
+function digest(token) {
+	return (0, node_crypto.createHash)("sha256").update(token).digest("hex");
+}
+/**
+* Paired sessions, held in memory only.
+*
+* Keyed by digest rather than scanned, so verification is a map lookup and
+* there is no comparison loop for a timing side channel to live in. That is why
+* `timingSafeEqual` does not appear here: there is nothing to compare. If a
+* future change introduces a scan, it will need one.
+*/
+function createDeviceAuth(options) {
+	const now = options.now ?? (() => Date.now());
+	const notice = options.onNotice ?? (() => {});
+	/** Digest to record. The raw token exists only in flight. */
+	const devices = /* @__PURE__ */ new Map();
+	const timers = /* @__PURE__ */ new Map();
+	const clearDeadline = (hash) => {
+		const timer = timers.get(hash);
+		if (timer !== void 0) clearTimeout(timer);
+		timers.delete(hash);
+	};
+	const drop = (hash, reason) => {
+		const record = devices.get(hash);
+		if (record === void 0) return void 0;
+		devices.delete(hash);
+		clearDeadline(hash);
+		options.onDrop?.(record, reason);
+		return record;
+	};
+	const schedule = (hash, record) => {
+		clearDeadline(hash);
+		const deadline = require_index.deviceExpiryAt(record, options.settings());
+		if (deadline === void 0) return;
+		const remaining = deadline - now();
+		if (remaining <= 0) {
+			drop(hash, "expired");
+			return;
+		}
+		const timer = setTimeout(() => {
+			const current = devices.get(hash);
+			if (current === void 0) return;
+			if (require_index.evaluateDevice(current, now(), options.settings()).ok) schedule(hash, current);
+			else drop(hash, "expired");
+		}, Math.min(remaining, 2147483647));
+		timer.unref();
+		timers.set(hash, timer);
+	};
+	return {
+		enrol(input) {
+			const token = (0, node_crypto.randomBytes)(TOKEN_BYTES).toString("base64url");
+			const userAgent = require_index.sanitizeUserAgent(input.userAgent);
+			const at = now();
+			const record = {
+				id: (0, node_crypto.randomBytes)(ID_BYTES).toString("hex"),
+				tokenHash: digest(token),
+				label: require_index.deviceLabelFor(userAgent),
+				userAgent,
+				createdAt: at,
+				lastSeenAt: at
+			};
+			devices.set(record.tokenHash, record);
+			schedule(record.tokenHash, record);
+			notice(`paired ${record.label} (${record.id})`);
+			return {
+				token,
+				record
+			};
+		},
+		verify(token) {
+			if (token === void 0 || token === "") return void 0;
+			const hash = digest(token);
+			const at = now();
+			const verdict = require_index.evaluateDevice(devices.get(hash), at, options.settings());
+			if (!verdict.ok) {
+				if (verdict.reason !== "unknown") drop(hash, "expired");
+				return;
+			}
+			const seen = require_index.touchDevice(verdict.record, at);
+			devices.set(hash, seen);
+			schedule(hash, seen);
+			return seen;
+		},
+		revoke(id) {
+			for (const [hash, record] of devices) {
+				if (record.id !== id) continue;
+				drop(hash, "revoked");
+				notice(`revoked ${record.label} (${record.id})`);
+				return true;
+			}
+			return false;
+		},
+		revokeAll() {
+			const records = [...devices.values()];
+			for (const [hash] of devices) drop(hash, "revoked");
+			if (records.length > 0) notice(`revoked ${String(records.length)} paired device(s)`);
+			return records.length;
+		},
+		list: () => [...devices.values()],
+		reschedule() {
+			for (const [hash, record] of devices) schedule(hash, record);
+		},
+		sweep() {
+			const at = now();
+			const settings = options.settings();
+			let dropped = 0;
+			for (const [hash, record] of devices) {
+				if (require_index.evaluateDevice(record, at, settings).ok) continue;
+				drop(hash, "expired");
+				dropped += 1;
+			}
+			return dropped;
+		}
+	};
+}
+//#endregion
+exports.createDeviceAuth = createDeviceAuth;
+
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["createHash","deviceExpiryAt","evaluateDevice","randomBytes","sanitizeUserAgent","deviceLabelFor","touchDevice"],"sources":["../../../../src/services/deviceAuth/index.ts"],"sourcesContent":["import { createHash, randomBytes } from 'node:crypto';\n\nimport type { RemoteAccessSettings } from '../../types/remote';\nimport {\n  type DeviceRecord,\n  deviceExpiryAt,\n  deviceLabelFor,\n  evaluateDevice,\n  sanitizeUserAgent,\n  touchDevice,\n} from '../deviceSessions';\n\n/** 256 bits. The token is scanned or set by the server, never typed, so there is no reason to economise. */\nconst TOKEN_BYTES = 32;\nconst ID_BYTES = 8;\n\nexport interface DeviceAuthOptions {\n  /** Read fresh on every check, so a changed toggle takes effect on the next request. */\n  settings: () => RemoteAccessSettings;\n  now?: () => number;\n  onNotice?: (message: string) => void;\n  onDrop?: (record: DeviceRecord, reason: 'revoked' | 'expired') => void;\n}\n\nexport interface EnrolledDevice {\n  /** Returned exactly once, to be sent as the cookie value. Only its digest is retained. */\n  token: string;\n  record: DeviceRecord;\n}\n\nexport interface DeviceAuth {\n  enrol(input: { userAgent: string | undefined }): EnrolledDevice;\n  /** The device this cookie names, or undefined. Bumps last-seen as a side effect. */\n  verify(token: string | undefined): DeviceRecord | undefined;\n  revoke(id: string): boolean;\n  revokeAll(): number;\n  list(): readonly DeviceRecord[];\n  /** Re-arms exact deadlines after expiry settings change. */\n  reschedule(): void;\n  /** Drops what has expired under the current settings. Returns how many went. */\n  sweep(): number;\n}\n\nfunction digest(token: string): string {\n  // No salt and no KDF, deliberately. The input is 256 bits of uniform\n  // randomness, so there is no dictionary to attack and a slow hash would only\n  // add latency to every request. Do not \"fix\" this into bcrypt.\n  return createHash('sha256').update(token).digest('hex');\n}\n\n/**\n * Paired sessions, held in memory only.\n *\n * Keyed by digest rather than scanned, so verification is a map lookup and\n * there is no comparison loop for a timing side channel to live in. That is why\n * `timingSafeEqual` does not appear here: there is nothing to compare. If a\n * future change introduces a scan, it will need one.\n */\nexport function createDeviceAuth(options: DeviceAuthOptions): DeviceAuth {\n  const now = options.now ?? ((): number => Date.now());\n  const notice = options.onNotice ?? ((): void => {});\n  /** Digest to record. The raw token exists only in flight. */\n  const devices = new Map<string, DeviceRecord>();\n  const timers = new Map<string, ReturnType<typeof setTimeout>>();\n\n  const clearDeadline = (hash: string): void => {\n    const timer = timers.get(hash);\n    if (timer !== undefined) clearTimeout(timer);\n    timers.delete(hash);\n  };\n\n  const drop = (hash: string, reason: 'revoked' | 'expired'): DeviceRecord | undefined => {\n    const record = devices.get(hash);\n    if (record === undefined) return undefined;\n    devices.delete(hash);\n    clearDeadline(hash);\n    options.onDrop?.(record, reason);\n    return record;\n  };\n\n  const schedule = (hash: string, record: DeviceRecord): void => {\n    clearDeadline(hash);\n    const deadline = deviceExpiryAt(record, options.settings());\n    if (deadline === undefined) return;\n    const remaining = deadline - now();\n    if (remaining <= 0) {\n      drop(hash, 'expired');\n      return;\n    }\n    const timer = setTimeout(\n      () => {\n        const current = devices.get(hash);\n        if (current === undefined) return;\n        if (evaluateDevice(current, now(), options.settings()).ok) schedule(hash, current);\n        else drop(hash, 'expired');\n      },\n      Math.min(remaining, 2_147_483_647),\n    );\n    timer.unref();\n    timers.set(hash, timer);\n  };\n  return {\n    enrol(input) {\n      const token = randomBytes(TOKEN_BYTES).toString('base64url');\n      const userAgent = sanitizeUserAgent(input.userAgent);\n      const at = now();\n      const record: DeviceRecord = {\n        id: randomBytes(ID_BYTES).toString('hex'),\n        tokenHash: digest(token),\n        label: deviceLabelFor(userAgent),\n        userAgent,\n        createdAt: at,\n        lastSeenAt: at,\n      };\n      devices.set(record.tokenHash, record);\n      schedule(record.tokenHash, record);\n      notice(`paired ${record.label} (${record.id})`);\n      return { token, record };\n    },\n\n    verify(token) {\n      if (token === undefined || token === '') return undefined;\n      const hash = digest(token);\n      const at = now();\n      const verdict = evaluateDevice(devices.get(hash), at, options.settings());\n      if (!verdict.ok) {\n        // An expired record is dropped on the way past rather than left to the\n        // sweeper, so a revoked-by-time device stops appearing in the list.\n        if (verdict.reason !== 'unknown') drop(hash, 'expired');\n        return undefined;\n      }\n      const seen = touchDevice(verdict.record, at);\n      devices.set(hash, seen);\n      schedule(hash, seen);\n      return seen;\n    },\n\n    revoke(id) {\n      for (const [hash, record] of devices) {\n        if (record.id !== id) continue;\n        drop(hash, 'revoked');\n        notice(`revoked ${record.label} (${record.id})`);\n        return true;\n      }\n      return false;\n    },\n\n    revokeAll() {\n      const records = [...devices.values()];\n      for (const [hash] of devices) drop(hash, 'revoked');\n      if (records.length > 0) notice(`revoked ${String(records.length)} paired device(s)`);\n      return records.length;\n    },\n\n    list: () => [...devices.values()],\n\n    reschedule() {\n      for (const [hash, record] of devices) schedule(hash, record);\n    },\n    sweep() {\n      const at = now();\n      const settings = options.settings();\n      let dropped = 0;\n      for (const [hash, record] of devices) {\n        if (evaluateDevice(record, at, settings).ok) continue;\n        drop(hash, 'expired');\n        dropped += 1;\n      }\n      return dropped;\n    },\n  };\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,9 @@
+import { DeviceRecord } from "../deviceSessions/index.mjs";
+//#region src/services/deviceAuth/index.d.ts
+export interface EnrolledDevice {
+  /** Returned exactly once, to be sent as the cookie value. Only its digest is retained. */
+  token: string;
+  record: DeviceRecord;
+}
+//#endregion
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../src/services/deviceAuth/index.ts"],"mappings":";;iBAwBiB;;EAEf;EACA,QAAQ"}