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

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

@@ -0,0 +1,145 @@
+const require_remote = require("../../constants/remote.cjs");
+const require_index = require("../deviceSessions/index.cjs");
+//#region src/services/pairingFlow/index.ts
+/**
+* Pairing a device, as a state machine over injected randomness and time.
+*
+*   code (120s) --claim--> pending (180s) --approve--> approved --consume--> consumed
+*                             |                 \
+*                             +----- deny -------+--> denied
+*
+* The host approval step is the point. A scanned code proves someone is
+* standing where the screen is, but a screen is visible over a shoulder and in
+* a screenshare, so the code alone is a single factor for a credential that
+* ends in shell access. Approving on the machine is the second.
+*
+* Randomness and hashing arrive as functions so this file stays free of
+* node:crypto and testable with a counter.
+*/
+/** Failed claims allowed per source inside one window before the endpoint starts refusing. */
+const ATTEMPT_LIMIT = 10;
+const ATTEMPT_WINDOW_MS = 6e4;
+/** Caps throttle state even if many distinct peers reach the listener. */
+const SOURCE_LIMIT = 1024;
+/** How long a settled request stays readable, so a late approval is still collectable. */
+const PAIRING_REQUEST_RETENTION_MS = require_remote.PAIRING_REQUEST_TTL_MS * 2;
+function createPairingFlow(options) {
+	/** Only the newest code pair is live, so minting another retires both old codes. */
+	let liveCode;
+	const requests = /* @__PURE__ */ new Map();
+	const attemptsBySource = /* @__PURE__ */ new Map();
+	const notice = options.onNotice ?? (() => {});
+	const isExpired = (request, now) => request.status === "pending" && now - request.createdAt >= 18e4;
+	/** Derived rather than scheduled, so a stopped clock cannot leave a request live. */
+	const statusOf = (request, now) => isExpired(request, now) ? "expired" : request.status;
+	const countFailure = (sourceAddress, now) => {
+		const source = sourceAddress ?? "unknown";
+		let attempts = attemptsBySource.get(source);
+		if (attempts === void 0 || now - attempts.windowStartedAt >= ATTEMPT_WINDOW_MS) {
+			if (attempts === void 0 && attemptsBySource.size >= SOURCE_LIMIT) {
+				const oldest = attemptsBySource.keys().next().value;
+				if (oldest !== void 0) attemptsBySource.delete(oldest);
+			}
+			attempts = {
+				windowStartedAt: now,
+				failures: 0
+			};
+			attemptsBySource.set(source, attempts);
+		}
+		attempts.failures += 1;
+		if (attempts.failures === 11) notice(`pairing claim abuse detected from ${source}; throttling invalid attempts`);
+		return attempts.failures > ATTEMPT_LIMIT ? "rate_limited" : "ok";
+	};
+	return {
+		mintCode() {
+			const code = options.randomToken();
+			const manualCode = options.randomManualCode();
+			const expiresAt = options.now() + require_remote.PAIRING_CODE_TTL_MS;
+			liveCode = {
+				hashes: [options.digest(code), options.digest(manualCode)],
+				expiresAt
+			};
+			return {
+				code,
+				manualCode,
+				expiresAt
+			};
+		},
+		claim(input) {
+			const now = options.now();
+			const presented = options.digest(input.code);
+			if (liveCode === void 0 || now >= liveCode.expiresAt || !liveCode.hashes.includes(presented)) {
+				const limit = countFailure(input.sourceAddress, now);
+				if (limit !== "ok") return {
+					ok: false,
+					code: limit
+				};
+				return {
+					ok: false,
+					code: "unknown_code"
+				};
+			}
+			liveCode = void 0;
+			const request = {
+				id: options.randomToken(),
+				userAgent: require_index.sanitizeUserAgent(input.userAgent),
+				edgeIp: require_index.sanitizeEdgeIp(input.edgeIp),
+				createdAt: now,
+				status: "pending"
+			};
+			requests.set(request.id, request);
+			notice(`pairing requested from ${request.userAgent} via ${request.edgeIp}`);
+			return {
+				ok: true,
+				requestId: request.id
+			};
+		},
+		status(requestId) {
+			const request = requests.get(requestId);
+			return request === void 0 ? void 0 : statusOf(request, options.now());
+		},
+		approve(requestId) {
+			const request = requests.get(requestId);
+			if (request === void 0) return "unknown";
+			const now = options.now();
+			if (isExpired(request, now)) return "expired";
+			if (request.status !== "pending") return "settled";
+			request.status = "approved";
+			notice(`pairing approved for ${request.userAgent}`);
+			return "approved";
+		},
+		deny(requestId) {
+			const request = requests.get(requestId);
+			if (request === void 0) return "unknown";
+			if (request.status !== "pending") return "settled";
+			request.status = "denied";
+			notice(`pairing denied for ${request.userAgent}`);
+			return "denied";
+		},
+		consume(requestId) {
+			const request = requests.get(requestId);
+			if (request === void 0 || request.status !== "approved") return void 0;
+			request.status = "consumed";
+			return { userAgent: request.userAgent };
+		},
+		pending() {
+			const now = options.now();
+			return [...requests.values()].filter((request) => statusOf(request, now) === "pending");
+		},
+		sweep() {
+			const now = options.now();
+			for (const [id, request] of requests) if (now - request.createdAt >= PAIRING_REQUEST_RETENTION_MS) requests.delete(id);
+			if (liveCode !== void 0 && now >= liveCode.expiresAt) liveCode = void 0;
+			for (const [source, attempts] of attemptsBySource) if (now - attempts.windowStartedAt >= ATTEMPT_WINDOW_MS) attemptsBySource.delete(source);
+		},
+		clear() {
+			requests.clear();
+			liveCode = void 0;
+			attemptsBySource.clear();
+		}
+	};
+}
+//#endregion
+exports.createPairingFlow = createPairingFlow;
+
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["PAIRING_REQUEST_TTL_MS","PAIRING_CODE_TTL_MS","sanitizeUserAgent","sanitizeEdgeIp"],"sources":["../../../../src/services/pairingFlow/index.ts"],"sourcesContent":["/**\n * Pairing a device, as a state machine over injected randomness and time.\n *\n *   code (120s) --claim--> pending (180s) --approve--> approved --consume--> consumed\n *                             |                 \\\n *                             +----- deny -------+--> denied\n *\n * The host approval step is the point. A scanned code proves someone is\n * standing where the screen is, but a screen is visible over a shoulder and in\n * a screenshare, so the code alone is a single factor for a credential that\n * ends in shell access. Approving on the machine is the second.\n *\n * Randomness and hashing arrive as functions so this file stays free of\n * node:crypto and testable with a counter.\n */\n\nimport { PAIRING_CODE_TTL_MS, PAIRING_REQUEST_TTL_MS } from '../../constants/remote';\nimport { type PairingStatus } from '../../types/remote';\nimport { sanitizeEdgeIp, sanitizeUserAgent } from '../deviceSessions';\n\n/** Failed claims allowed per source inside one window before the endpoint starts refusing. */\nconst ATTEMPT_LIMIT = 10;\nconst ATTEMPT_WINDOW_MS = 60_000;\n/** Caps throttle state even if many distinct peers reach the listener. */\nconst SOURCE_LIMIT = 1024;\n/** How long a settled request stays readable, so a late approval is still collectable. */\nconst PAIRING_REQUEST_RETENTION_MS = PAIRING_REQUEST_TTL_MS * 2;\n\nexport interface PairingRequest {\n  id: string;\n  userAgent: string;\n  edgeIp: string;\n  createdAt: number;\n  status: PairingStatus;\n}\n\nexport type ClaimOutcome = { ok: true; requestId: string } | { ok: false; code: 'unknown_code' | 'rate_limited' };\n\nexport interface PairingFlowOptions {\n  /** Returns a fresh high-entropy token carried only by the QR fragment. */\n  randomToken: () => string;\n  /** Returns a short numeric code intended for manual entry. */\n  randomManualCode: () => string;\n  /** One-way digest of a token; only the digest is retained. */\n  digest: (token: string) => string;\n  now: () => number;\n  onNotice?: (message: string) => void;\n}\n\nexport interface PairingFlow {\n  /** Mints a QR token and a separate manual code. Replaces the previous pair. */\n  mintCode(): { code: string; manualCode: string; expiresAt: number };\n  claim(input: {\n    code: string;\n    userAgent: string | undefined;\n    edgeIp: string | undefined;\n    /** Source normalized by the adapter from trusted proxy metadata or the socket peer. */\n    sourceAddress: string | undefined;\n  }): ClaimOutcome;\n  status(requestId: string): PairingStatus | undefined;\n  approve(requestId: string): 'approved' | 'unknown' | 'expired' | 'settled';\n  deny(requestId: string): 'denied' | 'unknown' | 'settled';\n  /** Takes an approved request exactly once, returning what the device record needs. */\n  consume(requestId: string): { userAgent: string } | undefined;\n  pending(): readonly PairingRequest[];\n  /** Drops what has aged out. Only reclaims memory; expiry is derived, not scheduled. */\n  sweep(): void;\n  clear(): void;\n}\n\nexport function createPairingFlow(options: PairingFlowOptions): PairingFlow {\n  /** Only the newest code pair is live, so minting another retires both old codes. */\n  let liveCode: { hashes: readonly [string, string]; expiresAt: number } | undefined;\n  const requests = new Map<string, PairingRequest>();\n  const attemptsBySource = new Map<string, { windowStartedAt: number; failures: number }>();\n\n  const notice = options.onNotice ?? ((): void => {});\n\n  const isExpired = (request: PairingRequest, now: number): boolean =>\n    request.status === 'pending' && now - request.createdAt >= PAIRING_REQUEST_TTL_MS;\n\n  /** Derived rather than scheduled, so a stopped clock cannot leave a request live. */\n  const statusOf = (request: PairingRequest, now: number): PairingStatus =>\n    isExpired(request, now) ? 'expired' : request.status;\n\n  const countFailure = (sourceAddress: string | undefined, now: number): 'ok' | 'rate_limited' => {\n    const source = sourceAddress ?? 'unknown';\n    let attempts = attemptsBySource.get(source);\n    if (attempts === undefined || now - attempts.windowStartedAt >= ATTEMPT_WINDOW_MS) {\n      if (attempts === undefined && attemptsBySource.size >= SOURCE_LIMIT) {\n        const oldest = attemptsBySource.keys().next().value as string | undefined;\n        if (oldest !== undefined) attemptsBySource.delete(oldest);\n      }\n      attempts = { windowStartedAt: now, failures: 0 };\n      attemptsBySource.set(source, attempts);\n    }\n    attempts.failures += 1;\n    if (attempts.failures === ATTEMPT_LIMIT + 1) {\n      notice(`pairing claim abuse detected from ${source}; throttling invalid attempts`);\n    }\n    return attempts.failures > ATTEMPT_LIMIT ? 'rate_limited' : 'ok';\n  };\n\n  return {\n    mintCode() {\n      const code = options.randomToken();\n      const manualCode = options.randomManualCode();\n      const expiresAt = options.now() + PAIRING_CODE_TTL_MS;\n      liveCode = { hashes: [options.digest(code), options.digest(manualCode)], expiresAt };\n      return { code, manualCode, expiresAt };\n    },\n\n    claim(input) {\n      const now = options.now();\n      const presented = options.digest(input.code);\n      // The QR token and manual code are one logical credential. A successful\n      // claim retires both so neither representation can be replayed.\n      if (liveCode === undefined || now >= liveCode.expiresAt || !liveCode.hashes.includes(presented)) {\n        const limit = countFailure(input.sourceAddress, now);\n        if (limit !== 'ok') return { ok: false, code: limit };\n        return { ok: false, code: 'unknown_code' };\n      }\n      liveCode = undefined;\n      const request: PairingRequest = {\n        id: options.randomToken(),\n        userAgent: sanitizeUserAgent(input.userAgent),\n        edgeIp: sanitizeEdgeIp(input.edgeIp),\n        createdAt: now,\n        status: 'pending',\n      };\n      requests.set(request.id, request);\n      notice(`pairing requested from ${request.userAgent} via ${request.edgeIp}`);\n      return { ok: true, requestId: request.id };\n    },\n\n    status(requestId) {\n      const request = requests.get(requestId);\n      return request === undefined ? undefined : statusOf(request, options.now());\n    },\n\n    approve(requestId) {\n      const request = requests.get(requestId);\n      if (request === undefined) return 'unknown';\n      const now = options.now();\n      if (isExpired(request, now)) return 'expired';\n      if (request.status !== 'pending') return 'settled';\n      request.status = 'approved';\n      notice(`pairing approved for ${request.userAgent}`);\n      return 'approved';\n    },\n\n    deny(requestId) {\n      const request = requests.get(requestId);\n      if (request === undefined) return 'unknown';\n      if (request.status !== 'pending') return 'settled';\n      request.status = 'denied';\n      notice(`pairing denied for ${request.userAgent}`);\n      return 'denied';\n    },\n\n    consume(requestId) {\n      const request = requests.get(requestId);\n      if (request === undefined || request.status !== 'approved') return undefined;\n      // Single use with no grace window. If the response is lost in flight the\n      // user rescans, which costs five seconds and removes any question about\n      // who else might be holding this id.\n      request.status = 'consumed';\n      return { userAgent: request.userAgent };\n    },\n\n    pending() {\n      const now = options.now();\n      return [...requests.values()].filter((request) => statusOf(request, now) === 'pending');\n    },\n\n    sweep() {\n      const now = options.now();\n      for (const [id, request] of requests) {\n        // A settled request is kept well past its window rather than dropped on\n        // sight: an approval landing in the last second still has to be\n        // collected by the phone's next poll, and a denied one should read as\n        // denied rather than decay into \"no such request\".\n        if (now - request.createdAt >= PAIRING_REQUEST_RETENTION_MS) requests.delete(id);\n      }\n      if (liveCode !== undefined && now >= liveCode.expiresAt) liveCode = undefined;\n      for (const [source, attempts] of attemptsBySource) {\n        if (now - attempts.windowStartedAt >= ATTEMPT_WINDOW_MS) attemptsBySource.delete(source);\n      }\n    },\n\n    clear() {\n      requests.clear();\n      liveCode = undefined;\n      attemptsBySource.clear();\n    },\n  };\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,44 @@
+import { PairingStatus } from "../../types/remote.mjs";
+//#region src/services/pairingFlow/index.d.ts
+export interface PairingRequest {
+  id: string;
+  userAgent: string;
+  edgeIp: string;
+  createdAt: number;
+  status: PairingStatus;
+}
+export type ClaimOutcome = {
+  ok: true;
+  requestId: string;
+} | {
+  ok: false;
+  code: 'unknown_code' | 'rate_limited';
+};
+export interface PairingFlow {
+  /** Mints a QR token and a separate manual code. Replaces the previous pair. */
+  mintCode(): {
+    code: string;
+    manualCode: string;
+    expiresAt: number;
+  };
+  claim(input: {
+    code: string;
+    userAgent: string | undefined;
+    edgeIp: string | undefined;
+    /** Source normalized by the adapter from trusted proxy metadata or the socket peer. */
+    sourceAddress: string | undefined;
+  }): ClaimOutcome;
+  status(requestId: string): PairingStatus | undefined;
+  approve(requestId: string): 'approved' | 'unknown' | 'expired' | 'settled';
+  deny(requestId: string): 'denied' | 'unknown' | 'settled';
+  /** Takes an approved request exactly once, returning what the device record needs. */
+  consume(requestId: string): {
+    userAgent: string;
+  } | undefined;
+  pending(): readonly PairingRequest[];
+  /** Drops what has aged out. Only reclaims memory; expiry is derived, not scheduled. */
+  sweep(): void;
+  clear(): void;
+}
+//#endregion
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../src/services/pairingFlow/index.ts"],"mappings":";;iBA4BiB;EACf;EACA;EACA;EACA;EACA,QAAQ;;YAGE;EAAiB;EAAU;;EAAwB;EAAW;;iBAazD;;EAEf;IAAc;IAAc;IAAoB;;EAChD,MAAM;IACJ;IACA;IACA;;IAEA;MACE;EACJ,OAAO,oBAAoB;EAC3B,QAAQ;EACR,KAAK;;EAEL,QAAQ;IAAsB;;EAC9B,oBAAoB;;EAEpB;EACA"}

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

@@ -0,0 +1,145 @@
+import { PAIRING_CODE_TTL_MS, PAIRING_REQUEST_TTL_MS } from "../../constants/remote.mjs";
+import { sanitizeEdgeIp, sanitizeUserAgent } from "../deviceSessions/index.mjs";
+//#region src/services/pairingFlow/index.ts
+/**
+* Pairing a device, as a state machine over injected randomness and time.
+*
+*   code (120s) --claim--> pending (180s) --approve--> approved --consume--> consumed
+*                             |                 \
+*                             +----- deny -------+--> denied
+*
+* The host approval step is the point. A scanned code proves someone is
+* standing where the screen is, but a screen is visible over a shoulder and in
+* a screenshare, so the code alone is a single factor for a credential that
+* ends in shell access. Approving on the machine is the second.
+*
+* Randomness and hashing arrive as functions so this file stays free of
+* node:crypto and testable with a counter.
+*/
+/** Failed claims allowed per source inside one window before the endpoint starts refusing. */
+const ATTEMPT_LIMIT = 10;
+const ATTEMPT_WINDOW_MS = 6e4;
+/** Caps throttle state even if many distinct peers reach the listener. */
+const SOURCE_LIMIT = 1024;
+/** How long a settled request stays readable, so a late approval is still collectable. */
+const PAIRING_REQUEST_RETENTION_MS = PAIRING_REQUEST_TTL_MS * 2;
+function createPairingFlow(options) {
+	/** Only the newest code pair is live, so minting another retires both old codes. */
+	let liveCode;
+	const requests = /* @__PURE__ */ new Map();
+	const attemptsBySource = /* @__PURE__ */ new Map();
+	const notice = options.onNotice ?? (() => {});
+	const isExpired = (request, now) => request.status === "pending" && now - request.createdAt >= 18e4;
+	/** Derived rather than scheduled, so a stopped clock cannot leave a request live. */
+	const statusOf = (request, now) => isExpired(request, now) ? "expired" : request.status;
+	const countFailure = (sourceAddress, now) => {
+		const source = sourceAddress ?? "unknown";
+		let attempts = attemptsBySource.get(source);
+		if (attempts === void 0 || now - attempts.windowStartedAt >= ATTEMPT_WINDOW_MS) {
+			if (attempts === void 0 && attemptsBySource.size >= SOURCE_LIMIT) {
+				const oldest = attemptsBySource.keys().next().value;
+				if (oldest !== void 0) attemptsBySource.delete(oldest);
+			}
+			attempts = {
+				windowStartedAt: now,
+				failures: 0
+			};
+			attemptsBySource.set(source, attempts);
+		}
+		attempts.failures += 1;
+		if (attempts.failures === 11) notice(`pairing claim abuse detected from ${source}; throttling invalid attempts`);
+		return attempts.failures > ATTEMPT_LIMIT ? "rate_limited" : "ok";
+	};
+	return {
+		mintCode() {
+			const code = options.randomToken();
+			const manualCode = options.randomManualCode();
+			const expiresAt = options.now() + PAIRING_CODE_TTL_MS;
+			liveCode = {
+				hashes: [options.digest(code), options.digest(manualCode)],
+				expiresAt
+			};
+			return {
+				code,
+				manualCode,
+				expiresAt
+			};
+		},
+		claim(input) {
+			const now = options.now();
+			const presented = options.digest(input.code);
+			if (liveCode === void 0 || now >= liveCode.expiresAt || !liveCode.hashes.includes(presented)) {
+				const limit = countFailure(input.sourceAddress, now);
+				if (limit !== "ok") return {
+					ok: false,
+					code: limit
+				};
+				return {
+					ok: false,
+					code: "unknown_code"
+				};
+			}
+			liveCode = void 0;
+			const request = {
+				id: options.randomToken(),
+				userAgent: sanitizeUserAgent(input.userAgent),
+				edgeIp: sanitizeEdgeIp(input.edgeIp),
+				createdAt: now,
+				status: "pending"
+			};
+			requests.set(request.id, request);
+			notice(`pairing requested from ${request.userAgent} via ${request.edgeIp}`);
+			return {
+				ok: true,
+				requestId: request.id
+			};
+		},
+		status(requestId) {
+			const request = requests.get(requestId);
+			return request === void 0 ? void 0 : statusOf(request, options.now());
+		},
+		approve(requestId) {
+			const request = requests.get(requestId);
+			if (request === void 0) return "unknown";
+			const now = options.now();
+			if (isExpired(request, now)) return "expired";
+			if (request.status !== "pending") return "settled";
+			request.status = "approved";
+			notice(`pairing approved for ${request.userAgent}`);
+			return "approved";
+		},
+		deny(requestId) {
+			const request = requests.get(requestId);
+			if (request === void 0) return "unknown";
+			if (request.status !== "pending") return "settled";
+			request.status = "denied";
+			notice(`pairing denied for ${request.userAgent}`);
+			return "denied";
+		},
+		consume(requestId) {
+			const request = requests.get(requestId);
+			if (request === void 0 || request.status !== "approved") return void 0;
+			request.status = "consumed";
+			return { userAgent: request.userAgent };
+		},
+		pending() {
+			const now = options.now();
+			return [...requests.values()].filter((request) => statusOf(request, now) === "pending");
+		},
+		sweep() {
+			const now = options.now();
+			for (const [id, request] of requests) if (now - request.createdAt >= PAIRING_REQUEST_RETENTION_MS) requests.delete(id);
+			if (liveCode !== void 0 && now >= liveCode.expiresAt) liveCode = void 0;
+			for (const [source, attempts] of attemptsBySource) if (now - attempts.windowStartedAt >= ATTEMPT_WINDOW_MS) attemptsBySource.delete(source);
+		},
+		clear() {
+			requests.clear();
+			liveCode = void 0;
+			attemptsBySource.clear();
+		}
+	};
+}
+//#endregion
+export { createPairingFlow };
+
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/pairingFlow/index.ts"],"sourcesContent":["/**\n * Pairing a device, as a state machine over injected randomness and time.\n *\n *   code (120s) --claim--> pending (180s) --approve--> approved --consume--> consumed\n *                             |                 \\\n *                             +----- deny -------+--> denied\n *\n * The host approval step is the point. A scanned code proves someone is\n * standing where the screen is, but a screen is visible over a shoulder and in\n * a screenshare, so the code alone is a single factor for a credential that\n * ends in shell access. Approving on the machine is the second.\n *\n * Randomness and hashing arrive as functions so this file stays free of\n * node:crypto and testable with a counter.\n */\n\nimport { PAIRING_CODE_TTL_MS, PAIRING_REQUEST_TTL_MS } from '../../constants/remote';\nimport { type PairingStatus } from '../../types/remote';\nimport { sanitizeEdgeIp, sanitizeUserAgent } from '../deviceSessions';\n\n/** Failed claims allowed per source inside one window before the endpoint starts refusing. */\nconst ATTEMPT_LIMIT = 10;\nconst ATTEMPT_WINDOW_MS = 60_000;\n/** Caps throttle state even if many distinct peers reach the listener. */\nconst SOURCE_LIMIT = 1024;\n/** How long a settled request stays readable, so a late approval is still collectable. */\nconst PAIRING_REQUEST_RETENTION_MS = PAIRING_REQUEST_TTL_MS * 2;\n\nexport interface PairingRequest {\n  id: string;\n  userAgent: string;\n  edgeIp: string;\n  createdAt: number;\n  status: PairingStatus;\n}\n\nexport type ClaimOutcome = { ok: true; requestId: string } | { ok: false; code: 'unknown_code' | 'rate_limited' };\n\nexport interface PairingFlowOptions {\n  /** Returns a fresh high-entropy token carried only by the QR fragment. */\n  randomToken: () => string;\n  /** Returns a short numeric code intended for manual entry. */\n  randomManualCode: () => string;\n  /** One-way digest of a token; only the digest is retained. */\n  digest: (token: string) => string;\n  now: () => number;\n  onNotice?: (message: string) => void;\n}\n\nexport interface PairingFlow {\n  /** Mints a QR token and a separate manual code. Replaces the previous pair. */\n  mintCode(): { code: string; manualCode: string; expiresAt: number };\n  claim(input: {\n    code: string;\n    userAgent: string | undefined;\n    edgeIp: string | undefined;\n    /** Source normalized by the adapter from trusted proxy metadata or the socket peer. */\n    sourceAddress: string | undefined;\n  }): ClaimOutcome;\n  status(requestId: string): PairingStatus | undefined;\n  approve(requestId: string): 'approved' | 'unknown' | 'expired' | 'settled';\n  deny(requestId: string): 'denied' | 'unknown' | 'settled';\n  /** Takes an approved request exactly once, returning what the device record needs. */\n  consume(requestId: string): { userAgent: string } | undefined;\n  pending(): readonly PairingRequest[];\n  /** Drops what has aged out. Only reclaims memory; expiry is derived, not scheduled. */\n  sweep(): void;\n  clear(): void;\n}\n\nexport function createPairingFlow(options: PairingFlowOptions): PairingFlow {\n  /** Only the newest code pair is live, so minting another retires both old codes. */\n  let liveCode: { hashes: readonly [string, string]; expiresAt: number } | undefined;\n  const requests = new Map<string, PairingRequest>();\n  const attemptsBySource = new Map<string, { windowStartedAt: number; failures: number }>();\n\n  const notice = options.onNotice ?? ((): void => {});\n\n  const isExpired = (request: PairingRequest, now: number): boolean =>\n    request.status === 'pending' && now - request.createdAt >= PAIRING_REQUEST_TTL_MS;\n\n  /** Derived rather than scheduled, so a stopped clock cannot leave a request live. */\n  const statusOf = (request: PairingRequest, now: number): PairingStatus =>\n    isExpired(request, now) ? 'expired' : request.status;\n\n  const countFailure = (sourceAddress: string | undefined, now: number): 'ok' | 'rate_limited' => {\n    const source = sourceAddress ?? 'unknown';\n    let attempts = attemptsBySource.get(source);\n    if (attempts === undefined || now - attempts.windowStartedAt >= ATTEMPT_WINDOW_MS) {\n      if (attempts === undefined && attemptsBySource.size >= SOURCE_LIMIT) {\n        const oldest = attemptsBySource.keys().next().value as string | undefined;\n        if (oldest !== undefined) attemptsBySource.delete(oldest);\n      }\n      attempts = { windowStartedAt: now, failures: 0 };\n      attemptsBySource.set(source, attempts);\n    }\n    attempts.failures += 1;\n    if (attempts.failures === ATTEMPT_LIMIT + 1) {\n      notice(`pairing claim abuse detected from ${source}; throttling invalid attempts`);\n    }\n    return attempts.failures > ATTEMPT_LIMIT ? 'rate_limited' : 'ok';\n  };\n\n  return {\n    mintCode() {\n      const code = options.randomToken();\n      const manualCode = options.randomManualCode();\n      const expiresAt = options.now() + PAIRING_CODE_TTL_MS;\n      liveCode = { hashes: [options.digest(code), options.digest(manualCode)], expiresAt };\n      return { code, manualCode, expiresAt };\n    },\n\n    claim(input) {\n      const now = options.now();\n      const presented = options.digest(input.code);\n      // The QR token and manual code are one logical credential. A successful\n      // claim retires both so neither representation can be replayed.\n      if (liveCode === undefined || now >= liveCode.expiresAt || !liveCode.hashes.includes(presented)) {\n        const limit = countFailure(input.sourceAddress, now);\n        if (limit !== 'ok') return { ok: false, code: limit };\n        return { ok: false, code: 'unknown_code' };\n      }\n      liveCode = undefined;\n      const request: PairingRequest = {\n        id: options.randomToken(),\n        userAgent: sanitizeUserAgent(input.userAgent),\n        edgeIp: sanitizeEdgeIp(input.edgeIp),\n        createdAt: now,\n        status: 'pending',\n      };\n      requests.set(request.id, request);\n      notice(`pairing requested from ${request.userAgent} via ${request.edgeIp}`);\n      return { ok: true, requestId: request.id };\n    },\n\n    status(requestId) {\n      const request = requests.get(requestId);\n      return request === undefined ? undefined : statusOf(request, options.now());\n    },\n\n    approve(requestId) {\n      const request = requests.get(requestId);\n      if (request === undefined) return 'unknown';\n      const now = options.now();\n      if (isExpired(request, now)) return 'expired';\n      if (request.status !== 'pending') return 'settled';\n      request.status = 'approved';\n      notice(`pairing approved for ${request.userAgent}`);\n      return 'approved';\n    },\n\n    deny(requestId) {\n      const request = requests.get(requestId);\n      if (request === undefined) return 'unknown';\n      if (request.status !== 'pending') return 'settled';\n      request.status = 'denied';\n      notice(`pairing denied for ${request.userAgent}`);\n      return 'denied';\n    },\n\n    consume(requestId) {\n      const request = requests.get(requestId);\n      if (request === undefined || request.status !== 'approved') return undefined;\n      // Single use with no grace window. If the response is lost in flight the\n      // user rescans, which costs five seconds and removes any question about\n      // who else might be holding this id.\n      request.status = 'consumed';\n      return { userAgent: request.userAgent };\n    },\n\n    pending() {\n      const now = options.now();\n      return [...requests.values()].filter((request) => statusOf(request, now) === 'pending');\n    },\n\n    sweep() {\n      const now = options.now();\n      for (const [id, request] of requests) {\n        // A settled request is kept well past its window rather than dropped on\n        // sight: an approval landing in the last second still has to be\n        // collected by the phone's next poll, and a denied one should read as\n        // denied rather than decay into \"no such request\".\n        if (now - request.createdAt >= PAIRING_REQUEST_RETENTION_MS) requests.delete(id);\n      }\n      if (liveCode !== undefined && now >= liveCode.expiresAt) liveCode = undefined;\n      for (const [source, attempts] of attemptsBySource) {\n        if (now - attempts.windowStartedAt >= ATTEMPT_WINDOW_MS) attemptsBySource.delete(source);\n      }\n    },\n\n    clear() {\n      requests.clear();\n      liveCode = undefined;\n      attemptsBySource.clear();\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAqBA,MAAM,gBAAgB;AACtB,MAAM,oBAAoB;;AAE1B,MAAM,eAAe;;AAErB,MAAM,+BAA+B,yBAAyB;AA4C9D,SAAgB,kBAAkB,SAA0C;;CAE1E,IAAI;CACJ,MAAM,2BAAW,IAAI,IAA4B;CACjD,MAAM,mCAAmB,IAAI,IAA2D;CAExF,MAAM,SAAS,QAAQ,mBAAyB,CAAC;CAEjD,MAAM,aAAa,SAAyB,QAC1C,QAAQ,WAAW,aAAa,MAAM,QAAQ,aAAA;;CAGhD,MAAM,YAAY,SAAyB,QACzC,UAAU,SAAS,GAAG,IAAI,YAAY,QAAQ;CAEhD,MAAM,gBAAgB,eAAmC,QAAuC;EAC9F,MAAM,SAAS,iBAAiB;EAChC,IAAI,WAAW,iBAAiB,IAAI,MAAM;EAC1C,IAAI,aAAa,KAAA,KAAa,MAAM,SAAS,mBAAmB,mBAAmB;GACjF,IAAI,aAAa,KAAA,KAAa,iBAAiB,QAAQ,cAAc;IACnE,MAAM,SAAS,iBAAiB,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,WAAW,KAAA,GAAW,iBAAiB,OAAO,MAAM;GAC1D;GACA,WAAW;IAAE,iBAAiB;IAAK,UAAU;GAAE;GAC/C,iBAAiB,IAAI,QAAQ,QAAQ;EACvC;EACA,SAAS,YAAY;EACrB,IAAI,SAAS,aAAa,IACxB,OAAO,qCAAqC,OAAO,8BAA8B;EAEnF,OAAO,SAAS,WAAW,gBAAgB,iBAAiB;CAC9D;CAEA,OAAO;EACL,WAAW;GACT,MAAM,OAAO,QAAQ,YAAY;GACjC,MAAM,aAAa,QAAQ,iBAAiB;GAC5C,MAAM,YAAY,QAAQ,IAAI,IAAI;GAClC,WAAW;IAAE,QAAQ,CAAC,QAAQ,OAAO,IAAI,GAAG,QAAQ,OAAO,UAAU,CAAC;IAAG;GAAU;GACnF,OAAO;IAAE;IAAM;IAAY;GAAU;EACvC;EAEA,MAAM,OAAO;GACX,MAAM,MAAM,QAAQ,IAAI;GACxB,MAAM,YAAY,QAAQ,OAAO,MAAM,IAAI;GAG3C,IAAI,aAAa,KAAA,KAAa,OAAO,SAAS,aAAa,CAAC,SAAS,OAAO,SAAS,SAAS,GAAG;IAC/F,MAAM,QAAQ,aAAa,MAAM,eAAe,GAAG;IACnD,IAAI,UAAU,MAAM,OAAO;KAAE,IAAI;KAAO,MAAM;IAAM;IACpD,OAAO;KAAE,IAAI;KAAO,MAAM;IAAe;GAC3C;GACA,WAAW,KAAA;GACX,MAAM,UAA0B;IAC9B,IAAI,QAAQ,YAAY;IACxB,WAAW,kBAAkB,MAAM,SAAS;IAC5C,QAAQ,eAAe,MAAM,MAAM;IACnC,WAAW;IACX,QAAQ;GACV;GACA,SAAS,IAAI,QAAQ,IAAI,OAAO;GAChC,OAAO,0BAA0B,QAAQ,UAAU,OAAO,QAAQ,QAAQ;GAC1E,OAAO;IAAE,IAAI;IAAM,WAAW,QAAQ;GAAG;EAC3C;EAEA,OAAO,WAAW;GAChB,MAAM,UAAU,SAAS,IAAI,SAAS;GACtC,OAAO,YAAY,KAAA,IAAY,KAAA,IAAY,SAAS,SAAS,QAAQ,IAAI,CAAC;EAC5E;EAEA,QAAQ,WAAW;GACjB,MAAM,UAAU,SAAS,IAAI,SAAS;GACtC,IAAI,YAAY,KAAA,GAAW,OAAO;GAClC,MAAM,MAAM,QAAQ,IAAI;GACxB,IAAI,UAAU,SAAS,GAAG,GAAG,OAAO;GACpC,IAAI,QAAQ,WAAW,WAAW,OAAO;GACzC,QAAQ,SAAS;GACjB,OAAO,wBAAwB,QAAQ,WAAW;GAClD,OAAO;EACT;EAEA,KAAK,WAAW;GACd,MAAM,UAAU,SAAS,IAAI,SAAS;GACtC,IAAI,YAAY,KAAA,GAAW,OAAO;GAClC,IAAI,QAAQ,WAAW,WAAW,OAAO;GACzC,QAAQ,SAAS;GACjB,OAAO,sBAAsB,QAAQ,WAAW;GAChD,OAAO;EACT;EAEA,QAAQ,WAAW;GACjB,MAAM,UAAU,SAAS,IAAI,SAAS;GACtC,IAAI,YAAY,KAAA,KAAa,QAAQ,WAAW,YAAY,OAAO,KAAA;GAInE,QAAQ,SAAS;GACjB,OAAO,EAAE,WAAW,QAAQ,UAAU;EACxC;EAEA,UAAU;GACR,MAAM,MAAM,QAAQ,IAAI;GACxB,OAAO,CAAC,GAAG,SAAS,OAAO,CAAC,CAAC,CAAC,QAAQ,YAAY,SAAS,SAAS,GAAG,MAAM,SAAS;EACxF;EAEA,QAAQ;GACN,MAAM,MAAM,QAAQ,IAAI;GACxB,KAAK,MAAM,CAAC,IAAI,YAAY,UAK1B,IAAI,MAAM,QAAQ,aAAa,8BAA8B,SAAS,OAAO,EAAE;GAEjF,IAAI,aAAa,KAAA,KAAa,OAAO,SAAS,WAAW,WAAW,KAAA;GACpE,KAAK,MAAM,CAAC,QAAQ,aAAa,kBAC/B,IAAI,MAAM,SAAS,mBAAmB,mBAAmB,iBAAiB,OAAO,MAAM;EAE3F;EAEA,QAAQ;GACN,SAAS,MAAM;GACf,WAAW,KAAA;GACX,iBAAiB,MAAM;EACzB;CACF;AACF"}