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

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

@@ -0,0 +1,125 @@
+import { deviceExpiryAt, deviceLabelFor, evaluateDevice, sanitizeUserAgent, touchDevice } from "../deviceSessions/index.mjs";
+import { createHash, randomBytes } from "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 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 = 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 (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 = randomBytes(TOKEN_BYTES).toString("base64url");
+			const userAgent = sanitizeUserAgent(input.userAgent);
+			const at = now();
+			const record = {
+				id: randomBytes(ID_BYTES).toString("hex"),
+				tokenHash: digest(token),
+				label: 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 = evaluateDevice(devices.get(hash), at, options.settings());
+			if (!verdict.ok) {
+				if (verdict.reason !== "unknown") drop(hash, "expired");
+				return;
+			}
+			const seen = 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 (evaluateDevice(record, at, settings).ok) continue;
+				drop(hash, "expired");
+				dropped += 1;
+			}
+			return dropped;
+		}
+	};
+}
+//#endregion
+export { createDeviceAuth };
+
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"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/deviceSessions/index.cjs

@@ -0,0 +1,147 @@
+//#region src/services/deviceSessions/index.ts
+const MS_PER_MINUTE = 6e4;
+const MS_PER_HOUR = 36e5;
+const MS_PER_SECOND = 1e3;
+/** Long enough to tell an iPhone from a laptop, short enough not to be a fingerprint in a log. */
+const MAX_USER_AGENT = 200;
+/** Upper bound of the C0 block, and the bounds of C1. Codepoints rather than a character class:
+* a regex over control characters is unreadable, hard to review, and trips no-control-regex. */
+const C0_END = 31;
+const C1_START = 127;
+const C1_END = 159;
+const UNKNOWN_DEVICE = "unknown device";
+/** Whether this record still authorizes a request, under the settings in force right now. */
+function evaluateDevice(record, now, settings) {
+	if (record === void 0) return {
+		ok: false,
+		reason: "unknown"
+	};
+	if (!settings.sessionExpiryEnabled) return {
+		ok: true,
+		record
+	};
+	if (now - record.lastSeenAt >= settings.idleMinutes * MS_PER_MINUTE) return {
+		ok: false,
+		reason: "idle"
+	};
+	if (now - record.createdAt >= settings.absoluteHours * MS_PER_HOUR) return {
+		ok: false,
+		reason: "absolute"
+	};
+	return {
+		ok: true,
+		record
+	};
+}
+/** Exact deadline at which this device stops authorizing, or undefined while expiry is disabled. */
+function deviceExpiryAt(record, settings) {
+	if (!settings.sessionExpiryEnabled) return void 0;
+	return Math.min(record.lastSeenAt + settings.idleMinutes * MS_PER_MINUTE, record.createdAt + settings.absoluteHours * MS_PER_HOUR);
+}
+function touchDevice(record, now) {
+	return {
+		...record,
+		lastSeenAt: now
+	};
+}
+/** How long the cookie should live, so the browser forgets roughly when the server does. */
+function cookieMaxAgeSeconds(settings, ceilingSeconds) {
+	if (!settings.sessionExpiryEnabled) return ceilingSeconds;
+	return Math.min(ceilingSeconds, Math.round(settings.absoluteHours * MS_PER_HOUR / MS_PER_SECOND));
+}
+/** Replaces every C0 and C1 control character with a space; those are what could forge a log line. */
+function withoutControlCharacters(value) {
+	let out = "";
+	for (const character of value) {
+		const code = character.codePointAt(0) ?? 0;
+		out += code <= C0_END || code >= C1_START && code <= C1_END ? " " : character;
+	}
+	return out;
+}
+/**
+* Strips anything that could forge a second line in a log or a second element
+* in the approval dialog, then truncates.
+*
+* The user agent is attacker-supplied and lands in both `notice()` output and
+* the host's approval prompt, so control characters are the concern rather than
+* length.
+*/
+function sanitizeUserAgent(raw) {
+	if (raw === void 0) return UNKNOWN_DEVICE;
+	const stripped = withoutControlCharacters(raw).replaceAll(/\s+/gu, " ").trim();
+	if (stripped === "") return UNKNOWN_DEVICE;
+	return stripped.slice(0, MAX_USER_AGENT);
+}
+/**
+* The address Cloudflare's edge reported, reduced to a safe display and key value.
+*
+* It never authorizes a request. The tunnel route may use it only for abuse
+* throttling when Cloudflare is the trusted proxy. A local process can forge it,
+* but local processes are outside that public-internet boundary.
+*/
+function sanitizeEdgeIp(raw) {
+	if (raw === void 0) return "unknown";
+	const candidate = raw.split(",")[0]?.trim() ?? "";
+	return /^[0-9a-f:.]{1,45}$/iu.test(candidate) ? candidate : "unknown";
+}
+const DEVICE_HINTS = [
+	{
+		pattern: /iphone/iu,
+		label: "iPhone"
+	},
+	{
+		pattern: /ipad/iu,
+		label: "iPad"
+	},
+	{
+		pattern: /android/iu,
+		label: "Android"
+	},
+	{
+		pattern: /macintosh|mac os x/iu,
+		label: "Mac"
+	},
+	{
+		pattern: /windows/iu,
+		label: "Windows"
+	},
+	{
+		pattern: /linux/iu,
+		label: "Linux"
+	}
+];
+const BROWSER_HINTS = [
+	{
+		pattern: /edg\//iu,
+		label: "Edge"
+	},
+	{
+		pattern: /firefox\//iu,
+		label: "Firefox"
+	},
+	{
+		pattern: /chrome\/|crios\//iu,
+		label: "Chrome"
+	},
+	{
+		pattern: /safari\//iu,
+		label: "Safari"
+	}
+];
+/** A human label for the device list, best effort; the full user agent is shown alongside. */
+function deviceLabelFor(userAgent) {
+	const device = DEVICE_HINTS.find((hint) => hint.pattern.test(userAgent))?.label;
+	const browser = BROWSER_HINTS.find((hint) => hint.pattern.test(userAgent))?.label;
+	if (device !== void 0 && browser !== void 0) return `${device} · ${browser}`;
+	return device ?? browser ?? "paired device";
+}
+//#endregion
+exports.cookieMaxAgeSeconds = cookieMaxAgeSeconds;
+exports.deviceExpiryAt = deviceExpiryAt;
+exports.deviceLabelFor = deviceLabelFor;
+exports.evaluateDevice = evaluateDevice;
+exports.sanitizeEdgeIp = sanitizeEdgeIp;
+exports.sanitizeUserAgent = sanitizeUserAgent;
+exports.touchDevice = touchDevice;
+
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../../../src/services/deviceSessions/index.ts"],"sourcesContent":["/**\n * What makes a paired device's session still valid.\n *\n * Expiry is derived from the settings in force at the moment of the check,\n * never stamped onto the record when it was minted. That is what makes the\n * setting honest in both directions: switching expiry on has to invalidate a\n * session that is already idle, and switching it off has to bring it back. A\n * stored `expiresAt` would do neither.\n */\n\nimport type { RemoteAccessSettings } from '../../types/remote';\n\nconst MS_PER_MINUTE = 60_000;\nconst MS_PER_HOUR = 3_600_000;\nconst MS_PER_SECOND = 1000;\n/** Long enough to tell an iPhone from a laptop, short enough not to be a fingerprint in a log. */\nconst MAX_USER_AGENT = 200;\n/** Upper bound of the C0 block, and the bounds of C1. Codepoints rather than a character class:\n * a regex over control characters is unreadable, hard to review, and trips no-control-regex. */\nconst C0_END = 0x1f;\nconst C1_START = 0x7f;\nconst C1_END = 0x9f;\nconst UNKNOWN_DEVICE = 'unknown device';\n\nexport interface DeviceRecord {\n  /** Opaque, safe to display and to name in a revoke call. Never the secret. */\n  id: string;\n  /** SHA-256 of the session token. The token itself is never retained. */\n  tokenHash: string;\n  label: string;\n  userAgent: string;\n  /** Epoch milliseconds. */\n  createdAt: number;\n  /** Epoch milliseconds, bumped on every authenticated request. */\n  lastSeenAt: number;\n}\n\nexport type DeviceRejection = 'unknown' | 'idle' | 'absolute';\n\nexport type DeviceVerdict = { ok: true; record: DeviceRecord } | { ok: false; reason: DeviceRejection };\n\n/** Whether this record still authorizes a request, under the settings in force right now. */\nexport function evaluateDevice(\n  record: DeviceRecord | undefined,\n  now: number,\n  settings: RemoteAccessSettings,\n): DeviceVerdict {\n  if (record === undefined) return { ok: false, reason: 'unknown' };\n  if (!settings.sessionExpiryEnabled) return { ok: true, record };\n  if (now - record.lastSeenAt >= settings.idleMinutes * MS_PER_MINUTE) return { ok: false, reason: 'idle' };\n  if (now - record.createdAt >= settings.absoluteHours * MS_PER_HOUR) return { ok: false, reason: 'absolute' };\n  return { ok: true, record };\n}\n\n/** Exact deadline at which this device stops authorizing, or undefined while expiry is disabled. */\nexport function deviceExpiryAt(record: DeviceRecord, settings: RemoteAccessSettings): number | undefined {\n  if (!settings.sessionExpiryEnabled) return undefined;\n  return Math.min(\n    record.lastSeenAt + settings.idleMinutes * MS_PER_MINUTE,\n    record.createdAt + settings.absoluteHours * MS_PER_HOUR,\n  );\n}\n\nexport function touchDevice(record: DeviceRecord, now: number): DeviceRecord {\n  return { ...record, lastSeenAt: now };\n}\n\n/** How long the cookie should live, so the browser forgets roughly when the server does. */\nexport function cookieMaxAgeSeconds(settings: RemoteAccessSettings, ceilingSeconds: number): number {\n  if (!settings.sessionExpiryEnabled) return ceilingSeconds;\n  return Math.min(ceilingSeconds, Math.round((settings.absoluteHours * MS_PER_HOUR) / MS_PER_SECOND));\n}\n\n/** Replaces every C0 and C1 control character with a space; those are what could forge a log line. */\nfunction withoutControlCharacters(value: string): string {\n  let out = '';\n  for (const character of value) {\n    const code = character.codePointAt(0) ?? 0;\n    out += code <= C0_END || (code >= C1_START && code <= C1_END) ? ' ' : character;\n  }\n  return out;\n}\n\n/**\n * Strips anything that could forge a second line in a log or a second element\n * in the approval dialog, then truncates.\n *\n * The user agent is attacker-supplied and lands in both `notice()` output and\n * the host's approval prompt, so control characters are the concern rather than\n * length.\n */\nexport function sanitizeUserAgent(raw: string | undefined): string {\n  if (raw === undefined) return UNKNOWN_DEVICE;\n  const stripped = withoutControlCharacters(raw).replaceAll(/\\s+/gu, ' ').trim();\n  if (stripped === '') return UNKNOWN_DEVICE;\n  return stripped.slice(0, MAX_USER_AGENT);\n}\n\n/**\n * The address Cloudflare's edge reported, reduced to a safe display and key value.\n *\n * It never authorizes a request. The tunnel route may use it only for abuse\n * throttling when Cloudflare is the trusted proxy. A local process can forge it,\n * but local processes are outside that public-internet boundary.\n */\nexport function sanitizeEdgeIp(raw: string | undefined): string {\n  if (raw === undefined) return 'unknown';\n  const candidate = raw.split(',')[0]?.trim() ?? '';\n  return /^[0-9a-f:.]{1,45}$/iu.test(candidate) ? candidate : 'unknown';\n}\n\nconst DEVICE_HINTS: readonly { pattern: RegExp; label: string }[] = [\n  { pattern: /iphone/iu, label: 'iPhone' },\n  { pattern: /ipad/iu, label: 'iPad' },\n  { pattern: /android/iu, label: 'Android' },\n  { pattern: /macintosh|mac os x/iu, label: 'Mac' },\n  { pattern: /windows/iu, label: 'Windows' },\n  { pattern: /linux/iu, label: 'Linux' },\n];\n\nconst BROWSER_HINTS: readonly { pattern: RegExp; label: string }[] = [\n  // Order matters: every Chromium user agent also says Safari, and Edge says both.\n  { pattern: /edg\\//iu, label: 'Edge' },\n  { pattern: /firefox\\//iu, label: 'Firefox' },\n  { pattern: /chrome\\/|crios\\//iu, label: 'Chrome' },\n  { pattern: /safari\\//iu, label: 'Safari' },\n];\n\n/** A human label for the device list, best effort; the full user agent is shown alongside. */\nexport function deviceLabelFor(userAgent: string): string {\n  const device = DEVICE_HINTS.find((hint) => hint.pattern.test(userAgent))?.label;\n  const browser = BROWSER_HINTS.find((hint) => hint.pattern.test(userAgent))?.label;\n  if (device !== undefined && browser !== undefined) return `${device} · ${browser}`;\n  return device ?? browser ?? 'paired device';\n}\n"],"mappings":";AAYA,MAAM,gBAAgB;AACtB,MAAM,cAAc;AACpB,MAAM,gBAAgB;;AAEtB,MAAM,iBAAiB;;;AAGvB,MAAM,SAAS;AACf,MAAM,WAAW;AACjB,MAAM,SAAS;AACf,MAAM,iBAAiB;;AAoBvB,SAAgB,eACd,QACA,KACA,UACe;CACf,IAAI,WAAW,KAAA,GAAW,OAAO;EAAE,IAAI;EAAO,QAAQ;CAAU;CAChE,IAAI,CAAC,SAAS,sBAAsB,OAAO;EAAE,IAAI;EAAM;CAAO;CAC9D,IAAI,MAAM,OAAO,cAAc,SAAS,cAAc,eAAe,OAAO;EAAE,IAAI;EAAO,QAAQ;CAAO;CACxG,IAAI,MAAM,OAAO,aAAa,SAAS,gBAAgB,aAAa,OAAO;EAAE,IAAI;EAAO,QAAQ;CAAW;CAC3G,OAAO;EAAE,IAAI;EAAM;CAAO;AAC5B;;AAGA,SAAgB,eAAe,QAAsB,UAAoD;CACvG,IAAI,CAAC,SAAS,sBAAsB,OAAO,KAAA;CAC3C,OAAO,KAAK,IACV,OAAO,aAAa,SAAS,cAAc,eAC3C,OAAO,YAAY,SAAS,gBAAgB,WAC9C;AACF;AAEA,SAAgB,YAAY,QAAsB,KAA2B;CAC3E,OAAO;EAAE,GAAG;EAAQ,YAAY;CAAI;AACtC;;AAGA,SAAgB,oBAAoB,UAAgC,gBAAgC;CAClG,IAAI,CAAC,SAAS,sBAAsB,OAAO;CAC3C,OAAO,KAAK,IAAI,gBAAgB,KAAK,MAAO,SAAS,gBAAgB,cAAe,aAAa,CAAC;AACpG;;AAGA,SAAS,yBAAyB,OAAuB;CACvD,IAAI,MAAM;CACV,KAAK,MAAM,aAAa,OAAO;EAC7B,MAAM,OAAO,UAAU,YAAY,CAAC,KAAK;EACzC,OAAO,QAAQ,UAAW,QAAQ,YAAY,QAAQ,SAAU,MAAM;CACxE;CACA,OAAO;AACT;;;;;;;;;AAUA,SAAgB,kBAAkB,KAAiC;CACjE,IAAI,QAAQ,KAAA,GAAW,OAAO;CAC9B,MAAM,WAAW,yBAAyB,GAAG,CAAC,CAAC,WAAW,SAAS,GAAG,CAAC,CAAC,KAAK;CAC7E,IAAI,aAAa,IAAI,OAAO;CAC5B,OAAO,SAAS,MAAM,GAAG,cAAc;AACzC;;;;;;;;AASA,SAAgB,eAAe,KAAiC;CAC9D,IAAI,QAAQ,KAAA,GAAW,OAAO;CAC9B,MAAM,YAAY,IAAI,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,KAAK;CAC/C,OAAO,uBAAuB,KAAK,SAAS,IAAI,YAAY;AAC9D;AAEA,MAAM,eAA8D;CAClE;EAAE,SAAS;EAAY,OAAO;CAAS;CACvC;EAAE,SAAS;EAAU,OAAO;CAAO;CACnC;EAAE,SAAS;EAAa,OAAO;CAAU;CACzC;EAAE,SAAS;EAAwB,OAAO;CAAM;CAChD;EAAE,SAAS;EAAa,OAAO;CAAU;CACzC;EAAE,SAAS;EAAW,OAAO;CAAQ;AACvC;AAEA,MAAM,gBAA+D;CAEnE;EAAE,SAAS;EAAW,OAAO;CAAO;CACpC;EAAE,SAAS;EAAe,OAAO;CAAU;CAC3C;EAAE,SAAS;EAAsB,OAAO;CAAS;CACjD;EAAE,SAAS;EAAc,OAAO;CAAS;AAC3C;;AAGA,SAAgB,eAAe,WAA2B;CACxD,MAAM,SAAS,aAAa,MAAM,SAAS,KAAK,QAAQ,KAAK,SAAS,CAAC,CAAC,EAAE;CAC1E,MAAM,UAAU,cAAc,MAAM,SAAS,KAAK,QAAQ,KAAK,SAAS,CAAC,CAAC,EAAE;CAC5E,IAAI,WAAW,KAAA,KAAa,YAAY,KAAA,GAAW,OAAO,GAAG,OAAO,KAAK;CACzE,OAAO,UAAU,WAAW;AAC9B"}

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

@@ -0,0 +1,15 @@
+//#region src/services/deviceSessions/index.d.ts
+export interface DeviceRecord {
+  /** Opaque, safe to display and to name in a revoke call. Never the secret. */
+  id: string;
+  /** SHA-256 of the session token. The token itself is never retained. */
+  tokenHash: string;
+  label: string;
+  userAgent: string;
+  /** Epoch milliseconds. */
+  createdAt: number;
+  /** Epoch milliseconds, bumped on every authenticated request. */
+  lastSeenAt: number;
+}
+//#endregion
+//# sourceMappingURL=index.d.mts.map

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

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

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

@@ -0,0 +1,141 @@
+//#region src/services/deviceSessions/index.ts
+const MS_PER_MINUTE = 6e4;
+const MS_PER_HOUR = 36e5;
+const MS_PER_SECOND = 1e3;
+/** Long enough to tell an iPhone from a laptop, short enough not to be a fingerprint in a log. */
+const MAX_USER_AGENT = 200;
+/** Upper bound of the C0 block, and the bounds of C1. Codepoints rather than a character class:
+* a regex over control characters is unreadable, hard to review, and trips no-control-regex. */
+const C0_END = 31;
+const C1_START = 127;
+const C1_END = 159;
+const UNKNOWN_DEVICE = "unknown device";
+/** Whether this record still authorizes a request, under the settings in force right now. */
+function evaluateDevice(record, now, settings) {
+	if (record === void 0) return {
+		ok: false,
+		reason: "unknown"
+	};
+	if (!settings.sessionExpiryEnabled) return {
+		ok: true,
+		record
+	};
+	if (now - record.lastSeenAt >= settings.idleMinutes * MS_PER_MINUTE) return {
+		ok: false,
+		reason: "idle"
+	};
+	if (now - record.createdAt >= settings.absoluteHours * MS_PER_HOUR) return {
+		ok: false,
+		reason: "absolute"
+	};
+	return {
+		ok: true,
+		record
+	};
+}
+/** Exact deadline at which this device stops authorizing, or undefined while expiry is disabled. */
+function deviceExpiryAt(record, settings) {
+	if (!settings.sessionExpiryEnabled) return void 0;
+	return Math.min(record.lastSeenAt + settings.idleMinutes * MS_PER_MINUTE, record.createdAt + settings.absoluteHours * MS_PER_HOUR);
+}
+function touchDevice(record, now) {
+	return {
+		...record,
+		lastSeenAt: now
+	};
+}
+/** How long the cookie should live, so the browser forgets roughly when the server does. */
+function cookieMaxAgeSeconds(settings, ceilingSeconds) {
+	if (!settings.sessionExpiryEnabled) return ceilingSeconds;
+	return Math.min(ceilingSeconds, Math.round(settings.absoluteHours * MS_PER_HOUR / MS_PER_SECOND));
+}
+/** Replaces every C0 and C1 control character with a space; those are what could forge a log line. */
+function withoutControlCharacters(value) {
+	let out = "";
+	for (const character of value) {
+		const code = character.codePointAt(0) ?? 0;
+		out += code <= C0_END || code >= C1_START && code <= C1_END ? " " : character;
+	}
+	return out;
+}
+/**
+* Strips anything that could forge a second line in a log or a second element
+* in the approval dialog, then truncates.
+*
+* The user agent is attacker-supplied and lands in both `notice()` output and
+* the host's approval prompt, so control characters are the concern rather than
+* length.
+*/
+function sanitizeUserAgent(raw) {
+	if (raw === void 0) return UNKNOWN_DEVICE;
+	const stripped = withoutControlCharacters(raw).replaceAll(/\s+/gu, " ").trim();
+	if (stripped === "") return UNKNOWN_DEVICE;
+	return stripped.slice(0, MAX_USER_AGENT);
+}
+/**
+* The address Cloudflare's edge reported, reduced to a safe display and key value.
+*
+* It never authorizes a request. The tunnel route may use it only for abuse
+* throttling when Cloudflare is the trusted proxy. A local process can forge it,
+* but local processes are outside that public-internet boundary.
+*/
+function sanitizeEdgeIp(raw) {
+	if (raw === void 0) return "unknown";
+	const candidate = raw.split(",")[0]?.trim() ?? "";
+	return /^[0-9a-f:.]{1,45}$/iu.test(candidate) ? candidate : "unknown";
+}
+const DEVICE_HINTS = [
+	{
+		pattern: /iphone/iu,
+		label: "iPhone"
+	},
+	{
+		pattern: /ipad/iu,
+		label: "iPad"
+	},
+	{
+		pattern: /android/iu,
+		label: "Android"
+	},
+	{
+		pattern: /macintosh|mac os x/iu,
+		label: "Mac"
+	},
+	{
+		pattern: /windows/iu,
+		label: "Windows"
+	},
+	{
+		pattern: /linux/iu,
+		label: "Linux"
+	}
+];
+const BROWSER_HINTS = [
+	{
+		pattern: /edg\//iu,
+		label: "Edge"
+	},
+	{
+		pattern: /firefox\//iu,
+		label: "Firefox"
+	},
+	{
+		pattern: /chrome\/|crios\//iu,
+		label: "Chrome"
+	},
+	{
+		pattern: /safari\//iu,
+		label: "Safari"
+	}
+];
+/** A human label for the device list, best effort; the full user agent is shown alongside. */
+function deviceLabelFor(userAgent) {
+	const device = DEVICE_HINTS.find((hint) => hint.pattern.test(userAgent))?.label;
+	const browser = BROWSER_HINTS.find((hint) => hint.pattern.test(userAgent))?.label;
+	if (device !== void 0 && browser !== void 0) return `${device} · ${browser}`;
+	return device ?? browser ?? "paired device";
+}
+//#endregion
+export { cookieMaxAgeSeconds, deviceExpiryAt, deviceLabelFor, evaluateDevice, sanitizeEdgeIp, sanitizeUserAgent, touchDevice };
+
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/deviceSessions/index.ts"],"sourcesContent":["/**\n * What makes a paired device's session still valid.\n *\n * Expiry is derived from the settings in force at the moment of the check,\n * never stamped onto the record when it was minted. That is what makes the\n * setting honest in both directions: switching expiry on has to invalidate a\n * session that is already idle, and switching it off has to bring it back. A\n * stored `expiresAt` would do neither.\n */\n\nimport type { RemoteAccessSettings } from '../../types/remote';\n\nconst MS_PER_MINUTE = 60_000;\nconst MS_PER_HOUR = 3_600_000;\nconst MS_PER_SECOND = 1000;\n/** Long enough to tell an iPhone from a laptop, short enough not to be a fingerprint in a log. */\nconst MAX_USER_AGENT = 200;\n/** Upper bound of the C0 block, and the bounds of C1. Codepoints rather than a character class:\n * a regex over control characters is unreadable, hard to review, and trips no-control-regex. */\nconst C0_END = 0x1f;\nconst C1_START = 0x7f;\nconst C1_END = 0x9f;\nconst UNKNOWN_DEVICE = 'unknown device';\n\nexport interface DeviceRecord {\n  /** Opaque, safe to display and to name in a revoke call. Never the secret. */\n  id: string;\n  /** SHA-256 of the session token. The token itself is never retained. */\n  tokenHash: string;\n  label: string;\n  userAgent: string;\n  /** Epoch milliseconds. */\n  createdAt: number;\n  /** Epoch milliseconds, bumped on every authenticated request. */\n  lastSeenAt: number;\n}\n\nexport type DeviceRejection = 'unknown' | 'idle' | 'absolute';\n\nexport type DeviceVerdict = { ok: true; record: DeviceRecord } | { ok: false; reason: DeviceRejection };\n\n/** Whether this record still authorizes a request, under the settings in force right now. */\nexport function evaluateDevice(\n  record: DeviceRecord | undefined,\n  now: number,\n  settings: RemoteAccessSettings,\n): DeviceVerdict {\n  if (record === undefined) return { ok: false, reason: 'unknown' };\n  if (!settings.sessionExpiryEnabled) return { ok: true, record };\n  if (now - record.lastSeenAt >= settings.idleMinutes * MS_PER_MINUTE) return { ok: false, reason: 'idle' };\n  if (now - record.createdAt >= settings.absoluteHours * MS_PER_HOUR) return { ok: false, reason: 'absolute' };\n  return { ok: true, record };\n}\n\n/** Exact deadline at which this device stops authorizing, or undefined while expiry is disabled. */\nexport function deviceExpiryAt(record: DeviceRecord, settings: RemoteAccessSettings): number | undefined {\n  if (!settings.sessionExpiryEnabled) return undefined;\n  return Math.min(\n    record.lastSeenAt + settings.idleMinutes * MS_PER_MINUTE,\n    record.createdAt + settings.absoluteHours * MS_PER_HOUR,\n  );\n}\n\nexport function touchDevice(record: DeviceRecord, now: number): DeviceRecord {\n  return { ...record, lastSeenAt: now };\n}\n\n/** How long the cookie should live, so the browser forgets roughly when the server does. */\nexport function cookieMaxAgeSeconds(settings: RemoteAccessSettings, ceilingSeconds: number): number {\n  if (!settings.sessionExpiryEnabled) return ceilingSeconds;\n  return Math.min(ceilingSeconds, Math.round((settings.absoluteHours * MS_PER_HOUR) / MS_PER_SECOND));\n}\n\n/** Replaces every C0 and C1 control character with a space; those are what could forge a log line. */\nfunction withoutControlCharacters(value: string): string {\n  let out = '';\n  for (const character of value) {\n    const code = character.codePointAt(0) ?? 0;\n    out += code <= C0_END || (code >= C1_START && code <= C1_END) ? ' ' : character;\n  }\n  return out;\n}\n\n/**\n * Strips anything that could forge a second line in a log or a second element\n * in the approval dialog, then truncates.\n *\n * The user agent is attacker-supplied and lands in both `notice()` output and\n * the host's approval prompt, so control characters are the concern rather than\n * length.\n */\nexport function sanitizeUserAgent(raw: string | undefined): string {\n  if (raw === undefined) return UNKNOWN_DEVICE;\n  const stripped = withoutControlCharacters(raw).replaceAll(/\\s+/gu, ' ').trim();\n  if (stripped === '') return UNKNOWN_DEVICE;\n  return stripped.slice(0, MAX_USER_AGENT);\n}\n\n/**\n * The address Cloudflare's edge reported, reduced to a safe display and key value.\n *\n * It never authorizes a request. The tunnel route may use it only for abuse\n * throttling when Cloudflare is the trusted proxy. A local process can forge it,\n * but local processes are outside that public-internet boundary.\n */\nexport function sanitizeEdgeIp(raw: string | undefined): string {\n  if (raw === undefined) return 'unknown';\n  const candidate = raw.split(',')[0]?.trim() ?? '';\n  return /^[0-9a-f:.]{1,45}$/iu.test(candidate) ? candidate : 'unknown';\n}\n\nconst DEVICE_HINTS: readonly { pattern: RegExp; label: string }[] = [\n  { pattern: /iphone/iu, label: 'iPhone' },\n  { pattern: /ipad/iu, label: 'iPad' },\n  { pattern: /android/iu, label: 'Android' },\n  { pattern: /macintosh|mac os x/iu, label: 'Mac' },\n  { pattern: /windows/iu, label: 'Windows' },\n  { pattern: /linux/iu, label: 'Linux' },\n];\n\nconst BROWSER_HINTS: readonly { pattern: RegExp; label: string }[] = [\n  // Order matters: every Chromium user agent also says Safari, and Edge says both.\n  { pattern: /edg\\//iu, label: 'Edge' },\n  { pattern: /firefox\\//iu, label: 'Firefox' },\n  { pattern: /chrome\\/|crios\\//iu, label: 'Chrome' },\n  { pattern: /safari\\//iu, label: 'Safari' },\n];\n\n/** A human label for the device list, best effort; the full user agent is shown alongside. */\nexport function deviceLabelFor(userAgent: string): string {\n  const device = DEVICE_HINTS.find((hint) => hint.pattern.test(userAgent))?.label;\n  const browser = BROWSER_HINTS.find((hint) => hint.pattern.test(userAgent))?.label;\n  if (device !== undefined && browser !== undefined) return `${device} · ${browser}`;\n  return device ?? browser ?? 'paired device';\n}\n"],"mappings":";AAYA,MAAM,gBAAgB;AACtB,MAAM,cAAc;AACpB,MAAM,gBAAgB;;AAEtB,MAAM,iBAAiB;;;AAGvB,MAAM,SAAS;AACf,MAAM,WAAW;AACjB,MAAM,SAAS;AACf,MAAM,iBAAiB;;AAoBvB,SAAgB,eACd,QACA,KACA,UACe;CACf,IAAI,WAAW,KAAA,GAAW,OAAO;EAAE,IAAI;EAAO,QAAQ;CAAU;CAChE,IAAI,CAAC,SAAS,sBAAsB,OAAO;EAAE,IAAI;EAAM;CAAO;CAC9D,IAAI,MAAM,OAAO,cAAc,SAAS,cAAc,eAAe,OAAO;EAAE,IAAI;EAAO,QAAQ;CAAO;CACxG,IAAI,MAAM,OAAO,aAAa,SAAS,gBAAgB,aAAa,OAAO;EAAE,IAAI;EAAO,QAAQ;CAAW;CAC3G,OAAO;EAAE,IAAI;EAAM;CAAO;AAC5B;;AAGA,SAAgB,eAAe,QAAsB,UAAoD;CACvG,IAAI,CAAC,SAAS,sBAAsB,OAAO,KAAA;CAC3C,OAAO,KAAK,IACV,OAAO,aAAa,SAAS,cAAc,eAC3C,OAAO,YAAY,SAAS,gBAAgB,WAC9C;AACF;AAEA,SAAgB,YAAY,QAAsB,KAA2B;CAC3E,OAAO;EAAE,GAAG;EAAQ,YAAY;CAAI;AACtC;;AAGA,SAAgB,oBAAoB,UAAgC,gBAAgC;CAClG,IAAI,CAAC,SAAS,sBAAsB,OAAO;CAC3C,OAAO,KAAK,IAAI,gBAAgB,KAAK,MAAO,SAAS,gBAAgB,cAAe,aAAa,CAAC;AACpG;;AAGA,SAAS,yBAAyB,OAAuB;CACvD,IAAI,MAAM;CACV,KAAK,MAAM,aAAa,OAAO;EAC7B,MAAM,OAAO,UAAU,YAAY,CAAC,KAAK;EACzC,OAAO,QAAQ,UAAW,QAAQ,YAAY,QAAQ,SAAU,MAAM;CACxE;CACA,OAAO;AACT;;;;;;;;;AAUA,SAAgB,kBAAkB,KAAiC;CACjE,IAAI,QAAQ,KAAA,GAAW,OAAO;CAC9B,MAAM,WAAW,yBAAyB,GAAG,CAAC,CAAC,WAAW,SAAS,GAAG,CAAC,CAAC,KAAK;CAC7E,IAAI,aAAa,IAAI,OAAO;CAC5B,OAAO,SAAS,MAAM,GAAG,cAAc;AACzC;;;;;;;;AASA,SAAgB,eAAe,KAAiC;CAC9D,IAAI,QAAQ,KAAA,GAAW,OAAO;CAC9B,MAAM,YAAY,IAAI,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,KAAK;CAC/C,OAAO,uBAAuB,KAAK,SAAS,IAAI,YAAY;AAC9D;AAEA,MAAM,eAA8D;CAClE;EAAE,SAAS;EAAY,OAAO;CAAS;CACvC;EAAE,SAAS;EAAU,OAAO;CAAO;CACnC;EAAE,SAAS;EAAa,OAAO;CAAU;CACzC;EAAE,SAAS;EAAwB,OAAO;CAAM;CAChD;EAAE,SAAS;EAAa,OAAO;CAAU;CACzC;EAAE,SAAS;EAAW,OAAO;CAAQ;AACvC;AAEA,MAAM,gBAA+D;CAEnE;EAAE,SAAS;EAAW,OAAO;CAAO;CACpC;EAAE,SAAS;EAAe,OAAO;CAAU;CAC3C;EAAE,SAAS;EAAsB,OAAO;CAAS;CACjD;EAAE,SAAS;EAAc,OAAO;CAAS;AAC3C;;AAGA,SAAgB,eAAe,WAA2B;CACxD,MAAM,SAAS,aAAa,MAAM,SAAS,KAAK,QAAQ,KAAK,SAAS,CAAC,CAAC,EAAE;CAC1E,MAAM,UAAU,cAAc,MAAM,SAAS,KAAK,QAAQ,KAAK,SAAS,CAAC,CAAC,EAAE;CAC5E,IAAI,WAAW,KAAA,KAAa,YAAY,KAAA,GAAW,OAAO,GAAG,OAAO,KAAK;CACzE,OAAO,UAAU,WAAW;AAC9B"}

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

@@ -0,0 +1,125 @@
+const require_notification = require("../../schemas/notification.cjs");
+require("../../../notification.cjs");
+let node_crypto = require("node:crypto");
+//#region src/services/headlessClient/index.ts
+/** Explicit client interactions over the existing browser dialog protocol. */
+function createHeadlessClient(options) {
+	const pending = /* @__PURE__ */ new Map();
+	let disposed = false;
+	const advance = () => pending.values().next().value?.start();
+	return {
+		client: {
+			async notify(request) {
+				if (disposed) throw new Error("Headless client is closed");
+				const data = require_notification.createDoomNotificationEntryData(request);
+				if (!data) throw new Error("Invalid notification request");
+				try {
+					await options.appendCustomEntry(require_notification.DOOM_NOTIFICATION_ENTRY_TYPE, data);
+				} catch (error) {
+					options.emitFrame({
+						type: "error",
+						code: "notification_undelivered",
+						error: `${data.body} (not saved to history: ${error instanceof Error ? error.message : String(error)})`
+					});
+				}
+			},
+			setStatus(source, text) {
+				if (disposed) throw new Error("Headless client is closed");
+				options.emitFrame({
+					type: "extension_ui_request",
+					method: "setStatus",
+					statusKey: source,
+					statusText: text
+				});
+			},
+			appendComposerText(text) {
+				if (disposed) throw new Error("Headless client is closed");
+				options.emitFrame({
+					type: "extension_ui_request",
+					method: "append_composer_text",
+					id: (0, node_crypto.randomUUID)(),
+					text
+				});
+			},
+			request(request, signal) {
+				if (disposed) return Promise.reject(/* @__PURE__ */ new Error("Headless client is closed"));
+				if (signal?.aborted) return Promise.resolve(void 0);
+				if (![
+					"confirm",
+					"select",
+					"input"
+				].includes(request.kind)) return Promise.reject(/* @__PURE__ */ new Error("Unsupported headless client request"));
+				const labels = request.options?.map((option) => option.label);
+				if (labels && new Set(labels).size !== labels.length) return Promise.reject(/* @__PURE__ */ new Error("Select option labels must be unique"));
+				const id = `headless-ui:${(0, node_crypto.randomUUID)()}`;
+				return new Promise((resolve, reject) => {
+					let started = false;
+					const finish = (outcome) => {
+						if (!pending.delete(id)) return;
+						signal?.removeEventListener("abort", abort);
+						try {
+							if (started) options.emitFrame({
+								type: "extension_ui_answered",
+								id
+							});
+							if ("error" in outcome) reject(outcome.error);
+							else resolve(outcome.value);
+						} catch (error) {
+							reject(error);
+						} finally {
+							advance();
+						}
+					};
+					const abort = () => finish({ value: void 0 });
+					pending.set(id, {
+						start() {
+							if (started || disposed) return;
+							started = true;
+							try {
+								options.emitFrame({
+									type: "extension_ui_request",
+									id,
+									method: request.kind === "input" && request.multiline ? "editor" : request.kind,
+									title: request.title,
+									message: request.message,
+									options: labels,
+									placeholder: request.message,
+									prefill: request.initialValue
+								});
+							} catch (error) {
+								finish({ error });
+							}
+						},
+						respond(frame) {
+							if (!started) return;
+							if (frame.cancelled === true) return finish({ value: void 0 });
+							if (request.kind === "confirm") {
+								if (typeof frame.confirmed === "boolean") finish({ value: frame.confirmed });
+							} else if (typeof frame.value === "string") {
+								const selected = request.options?.find((option) => option.label === frame.value);
+								finish({ value: selected?.value ?? frame.value });
+							}
+						},
+						close: () => finish({ error: /* @__PURE__ */ new Error("Headless client is closed") })
+					});
+					signal?.addEventListener("abort", abort, { once: true });
+					advance();
+				});
+			}
+		},
+		receive(frame) {
+			if (frame.type !== "extension_ui_response") return false;
+			if (typeof frame.id === "string") pending.get(frame.id)?.respond(frame);
+			return true;
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			for (const request of pending.values()) request.close();
+		}
+	};
+}
+//#endregion
+exports.createHeadlessClient = createHeadlessClient;
+
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["createDoomNotificationEntryData","DOOM_NOTIFICATION_ENTRY_TYPE","randomUUID"],"sources":["../../../../src/services/headlessClient/index.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\n\nimport { createDoomNotificationEntryData, DOOM_NOTIFICATION_ENTRY_TYPE } from '../../exports/notification';\nimport type {\n  HeadlessClientBridge,\n  HeadlessClientOptions,\n  PendingClientRequest,\n} from '../../types/server/headlessClient';\n\n/** Explicit client interactions over the existing browser dialog protocol. */\nexport function createHeadlessClient(options: HeadlessClientOptions): HeadlessClientBridge {\n  const pending = new Map<string, PendingClientRequest>();\n  let disposed = false;\n  const advance = (): void => pending.values().next().value?.start();\n\n  return {\n    client: {\n      async notify(request) {\n        if (disposed) throw new Error('Headless client is closed');\n        const data = createDoomNotificationEntryData(request);\n        if (!data) throw new Error('Invalid notification request');\n        try {\n          await options.appendCustomEntry(DOOM_NOTIFICATION_ENTRY_TYPE, data);\n        } catch (error) {\n          // Callers fire notify without awaiting, often to report a journal failure. A rejection here\n          // would crash the session server, so a refused append still reaches the browser live.\n          options.emitFrame({\n            type: 'error',\n            code: 'notification_undelivered',\n            error: `${data.body} (not saved to history: ${error instanceof Error ? error.message : String(error)})`,\n          });\n        }\n      },\n      setStatus(source, text) {\n        if (disposed) throw new Error('Headless client is closed');\n        options.emitFrame({ type: 'extension_ui_request', method: 'setStatus', statusKey: source, statusText: text });\n      },\n      appendComposerText(text) {\n        if (disposed) throw new Error('Headless client is closed');\n        options.emitFrame({ type: 'extension_ui_request', method: 'append_composer_text', id: randomUUID(), text });\n      },\n      request(request, signal) {\n        if (disposed) return Promise.reject(new Error('Headless client is closed'));\n        if (signal?.aborted) return Promise.resolve(undefined);\n        if (!['confirm', 'select', 'input'].includes(request.kind)) {\n          return Promise.reject(new Error('Unsupported headless client request'));\n        }\n        const labels = request.options?.map((option) => option.label);\n        if (labels && new Set(labels).size !== labels.length) {\n          return Promise.reject(new Error('Select option labels must be unique'));\n        }\n        const id = `headless-ui:${randomUUID()}`;\n        return new Promise((resolve, reject) => {\n          let started = false;\n          const finish = (outcome: { value: unknown } | { error: unknown }): void => {\n            if (!pending.delete(id)) return;\n            signal?.removeEventListener('abort', abort);\n            try {\n              if (started) options.emitFrame({ type: 'extension_ui_answered', id });\n              if ('error' in outcome) reject(outcome.error);\n              else resolve(outcome.value);\n            } catch (error) {\n              reject(error);\n            } finally {\n              advance();\n            }\n          };\n          const abort = (): void => finish({ value: undefined });\n          pending.set(id, {\n            start() {\n              if (started || disposed) return;\n              started = true;\n              try {\n                options.emitFrame({\n                  type: 'extension_ui_request',\n                  id,\n                  method: request.kind === 'input' && request.multiline ? 'editor' : request.kind,\n                  title: request.title,\n                  message: request.message,\n                  options: labels,\n                  placeholder: request.message,\n                  prefill: request.initialValue,\n                });\n              } catch (error) {\n                finish({ error });\n              }\n            },\n            respond(frame) {\n              if (!started) return;\n              if (frame.cancelled === true) return finish({ value: undefined });\n              if (request.kind === 'confirm') {\n                if (typeof frame.confirmed === 'boolean') finish({ value: frame.confirmed });\n              } else if (typeof frame.value === 'string') {\n                // Rich questionnaire clients return an encoded whole-answer envelope here.\n                const selected = request.options?.find((option) => option.label === frame.value);\n                finish({ value: selected?.value ?? frame.value });\n              }\n            },\n            close: () => finish({ error: new Error('Headless client is closed') }),\n          });\n          signal?.addEventListener('abort', abort, { once: true });\n          advance();\n        });\n      },\n    },\n    receive(frame) {\n      if (frame.type !== 'extension_ui_response') return false;\n      if (typeof frame.id === 'string') pending.get(frame.id)?.respond(frame);\n      return true;\n    },\n    dispose() {\n      if (disposed) return;\n      disposed = true;\n      for (const request of pending.values()) request.close();\n    },\n  };\n}\n"],"mappings":"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"}