@xopcai/xopc 0.0.231 → 0.0.232

package/dist/src/tunnel/pair-url.d.ts

@@ -1,43 +0,0 @@
-import type { Config } from '../config/schema.js';
-export type MobilePairUrlValidationCode = 'INVALID_URL' | 'LOOPBACK_NOT_REACHABLE';
-export type MobilePairUrlValidationResult = {
-    ok: true;
-    url: string;
-    loopback: false;
-} | {
-    ok: false;
-    code: MobilePairUrlValidationCode;
-    message: string;
-};
-/** Normalize a gateway root URL (no trailing slash, no path). */
-export declare function normalizeGatewayBaseUrl(raw: string): string | null;
-/** True when a phone on the network cannot reach this gateway root URL. */
-export declare function isLoopbackGatewayBaseUrl(raw: string): boolean;
-export declare function validateMobilePairBaseUrl(raw: string): MobilePairUrlValidationResult;
-export type ParsedMobileConnectDeepLink = {
-    baseUrl: string;
-    lanUrl: string | null;
-    pairingSecret: string;
-};
-/** Parse `xopc://gateway/mobile-connect?...` payloads from QR codes. */
-export declare function parseMobileConnectDeepLink(raw: string): ParsedMobileConnectDeepLink | null;
-/**
- * Ordered URLs for mobile clients. Priority:
- *   1. reverse-proxy public URL (user-deployed HTTPS, typically fastest + works on cellular)
- *   2. LAN URL (zero-RTT on same network)
- *   3. baseUrl (legacy: usually the FRP tunnel public URL, kept for callers that
- *      do not yet split reverseProxyUrl from tunnelUrl)
- *   4. tunnelUrl (explicit FRP tunnel URL, kept as a fallback even when a
- *      reverse-proxy URL is also configured)
- *
- * Loopback URLs are dropped (they only work on the gateway host) and
- * duplicates are de-duped while preserving first occurrence order.
- */
-export declare function buildMobileConnectUrlOrder(params: {
-    baseUrl: string | null | undefined;
-    lanUrl: string | null | undefined;
-    reverseProxyUrl?: string | null | undefined;
-    tunnelUrl?: string | null | undefined;
-}): string[];
-/** First LAN URL when the gateway listens on a network-accessible bind host. */
-export declare function resolveMobilePairLanUrl(config: Config): string | null;

package/dist/src/tunnel/pair-url.js

@@ -1,117 +0,0 @@
-import { enumerateLanGatewayCandidates } from "../gateway/host.js";
-import { isNetworkAccessibleBindHost, resolveGatewayEffectiveHost } from "../config/gateway-bind.js";
-import net from "node:net";
-//#region src/tunnel/pair-url.ts
-/** Normalize a gateway root URL (no trailing slash, no path). */
-function normalizeGatewayBaseUrl(raw) {
-	const trimmed = raw.trim();
-	if (!trimmed) return null;
-	try {
-		const u = new URL(trimmed);
-		if (u.protocol !== "http:" && u.protocol !== "https:") return null;
-		if (u.username || u.password) return null;
-		if (u.pathname && u.pathname !== "/") return null;
-		if (u.search || u.hash) return null;
-		const portSuffix = u.port ? `:${u.port}` : "";
-		return `${u.protocol}//${u.hostname}${portSuffix}`;
-	} catch {
-		return null;
-	}
-}
-/** True when a phone on the network cannot reach this gateway root URL. */
-function isLoopbackGatewayBaseUrl(raw) {
-	const normalized = normalizeGatewayBaseUrl(raw);
-	if (!normalized) return false;
-	try {
-		const host = new URL(normalized).hostname.trim().toLowerCase();
-		if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]") return true;
-		if (net.isIP(host) === 4) {
-			const parts = host.split(".").map((p) => Number(p));
-			if (parts.length === 4 && parts.every((n) => Number.isInteger(n)) && parts[0] === 127) return true;
-		}
-		return false;
-	} catch {
-		return false;
-	}
-}
-function validateMobilePairBaseUrl(raw) {
-	const url = normalizeGatewayBaseUrl(raw);
-	if (!url) return {
-		ok: false,
-		code: "INVALID_URL",
-		message: "Enter an absolute gateway URL starting with http:// or https:// (no path)."
-	};
-	if (isLoopbackGatewayBaseUrl(url)) return {
-		ok: false,
-		code: "LOOPBACK_NOT_REACHABLE",
-		message: "127.0.0.1 and localhost only work on the gateway machine. Use a LAN IP or tunnel URL instead."
-	};
-	return {
-		ok: true,
-		url,
-		loopback: false
-	};
-}
-/** Parse `xopc://gateway/mobile-connect?...` payloads from QR codes. */
-function parseMobileConnectDeepLink(raw) {
-	const trimmed = raw.trim();
-	if (!trimmed) return null;
-	try {
-		const u = new URL(trimmed);
-		if (u.protocol !== "xopc:" || u.hostname !== "gateway" || u.pathname !== "/mobile-connect") return null;
-		const baseUrl = u.searchParams.get("baseUrl")?.trim() ?? "";
-		const psRaw = u.searchParams.get("ps")?.trim() ?? "";
-		let pairingSecret = psRaw;
-		if (psRaw) try {
-			pairingSecret = decodeURIComponent(psRaw);
-		} catch {
-			pairingSecret = psRaw;
-		}
-		if (!baseUrl || !pairingSecret) return null;
-		const lanRaw = u.searchParams.get("lanUrl")?.trim() ?? "";
-		const lanUrl = lanRaw ? normalizeGatewayBaseUrl(lanRaw) : null;
-		const normalizedBase = normalizeGatewayBaseUrl(baseUrl);
-		if (!normalizedBase) return null;
-		return {
-			baseUrl: normalizedBase,
-			lanUrl,
-			pairingSecret
-		};
-	} catch {
-		return null;
-	}
-}
-/**
-* Ordered URLs for mobile clients. Priority:
-*   1. reverse-proxy public URL (user-deployed HTTPS, typically fastest + works on cellular)
-*   2. LAN URL (zero-RTT on same network)
-*   3. baseUrl (legacy: usually the FRP tunnel public URL, kept for callers that
-*      do not yet split reverseProxyUrl from tunnelUrl)
-*   4. tunnelUrl (explicit FRP tunnel URL, kept as a fallback even when a
-*      reverse-proxy URL is also configured)
-*
-* Loopback URLs are dropped (they only work on the gateway host) and
-* duplicates are de-duped while preserving first occurrence order.
-*/
-function buildMobileConnectUrlOrder(params) {
-	const ordered = [];
-	const seen = /* @__PURE__ */ new Set();
-	const push = (raw) => {
-		const url = raw ? normalizeGatewayBaseUrl(raw) : null;
-		if (!url || isLoopbackGatewayBaseUrl(url) || seen.has(url)) return;
-		seen.add(url);
-		ordered.push(url);
-	};
-	push(params.reverseProxyUrl);
-	push(params.lanUrl);
-	push(params.baseUrl);
-	push(params.tunnelUrl);
-	return ordered;
-}
-/** First LAN URL when the gateway listens on a network-accessible bind host. */
-function resolveMobilePairLanUrl(config) {
-	if (!isNetworkAccessibleBindHost(resolveGatewayEffectiveHost(config))) return null;
-	return enumerateLanGatewayCandidates(config.gateway?.port ?? 18790)[0]?.url ?? null;
-}
-//#endregion
-export { buildMobileConnectUrlOrder, isLoopbackGatewayBaseUrl, normalizeGatewayBaseUrl, parseMobileConnectDeepLink, resolveMobilePairLanUrl, validateMobilePairBaseUrl };

package/dist/src/tunnel/pairing-rate-limit.d.ts

@@ -1,12 +0,0 @@
-export type PairingFailureLimitResult = {
-    allowed: boolean;
-    retryAfterMs: number;
-};
-/**
- * Records a failed pairing exchange and returns whether subsequent attempts
- * are still permitted. Called from the route handler on every invalid /
- * expired pairing secret — successful exchanges do NOT call this.
- */
-export declare function consumePairingExchangeFailLimit(clientKey: string): PairingFailureLimitResult;
-/** @internal */
-export declare function resetPairingExchangeLimitsForTests(): void;

package/dist/src/tunnel/pairing-rate-limit.js

@@ -1,28 +0,0 @@
-import { buckets } from "../gateway/rate-limit/buckets.js";
-import "../gateway/rate-limit/index.js";
-//#region src/tunnel/pairing-rate-limit.ts
-/**
-* Records a failed pairing exchange and returns whether subsequent attempts
-* are still permitted. Called from the route handler on every invalid /
-* expired pairing secret — successful exchanges do NOT call this.
-*/
-function consumePairingExchangeFailLimit(clientKey) {
-	const fl = buckets.pairingExchange();
-	const key = clientKey.trim() || "unknown";
-	fl.fail(key);
-	const status = fl.check(key);
-	if (status.blocked) return {
-		allowed: false,
-		retryAfterMs: status.retryAfterSec * 1e3
-	};
-	return {
-		allowed: true,
-		retryAfterMs: 0
-	};
-}
-/** @internal */
-function resetPairingExchangeLimitsForTests() {
-	buckets.pairingExchange().resetForTests();
-}
-//#endregion
-export { consumePairingExchangeFailLimit, resetPairingExchangeLimitsForTests };

package/dist/src/tunnel/pairing.d.ts

@@ -1,21 +0,0 @@
-export type PairingSecretResult = {
-    secret: string;
-    expiresAt: Date;
-};
-export type PairingExchangePayload = {
-    token: string;
-    baseUrl: string | null;
-    lanUrl: string | null;
-    connectUrls: string[];
-};
-export declare function cachePairingExchange(secret: string, payload: PairingExchangePayload): void;
-export declare function getCachedPairingExchange(secret: string): PairingExchangePayload | null;
-/**
- * Consume a pairing secret once and build the exchange payload.
- * Concurrent requests for the same secret share one in-flight exchange (mobile cold-start deeplink).
- */
-export declare function exchangePairingSecretOnce(secret: string, buildPayload: () => PairingExchangePayload): Promise<PairingExchangePayload | null>;
-export declare function createPairingSecret(): PairingSecretResult;
-export declare function consumePairingSecret(secret: string): boolean;
-/** @internal */
-export declare function resetPairingSessionsForTests(): void;

package/dist/src/tunnel/pairing.js

@@ -1,103 +0,0 @@
-import { createLogger } from "../utils/logger/index.js";
-import { init_logger } from "../utils/logger.js";
-import { randomBytes } from "node:crypto";
-//#region src/tunnel/pairing.ts
-init_logger();
-const log = createLogger("TunnelPairing");
-const PAIRING_TTL_MS = 5 * 6e4;
-const CLEANUP_INTERVAL_MS = 6e4;
-const sessions = /* @__PURE__ */ new Map();
-let cleanupTimer = null;
-function ensureCleanupTimer() {
-	if (cleanupTimer) return;
-	cleanupTimer = setInterval(() => {
-		const now = Date.now();
-		for (const [key, session] of sessions) if (now > session.expiresAt.getTime()) sessions.delete(key);
-	}, CLEANUP_INTERVAL_MS);
-	cleanupTimer.unref?.();
-}
-const EXCHANGE_REPLAY_MS = 6e4;
-const exchangeReplayCache = /* @__PURE__ */ new Map();
-function cachePairingExchange(secret, payload) {
-	exchangeReplayCache.set(secret, {
-		expiresAt: Date.now() + EXCHANGE_REPLAY_MS,
-		payload
-	});
-}
-function getCachedPairingExchange(secret) {
-	const entry = exchangeReplayCache.get(secret);
-	if (!entry) return null;
-	if (Date.now() > entry.expiresAt) {
-		exchangeReplayCache.delete(secret);
-		return null;
-	}
-	return entry.payload;
-}
-const inflightExchanges = /* @__PURE__ */ new Map();
-/**
-* Consume a pairing secret once and build the exchange payload.
-* Concurrent requests for the same secret share one in-flight exchange (mobile cold-start deeplink).
-*/
-async function exchangePairingSecretOnce(secret, buildPayload) {
-	const key = secret.trim();
-	if (!key) return null;
-	const replay = getCachedPairingExchange(key);
-	if (replay) return replay;
-	let inflight = inflightExchanges.get(key);
-	if (!inflight) {
-		inflight = (async () => {
-			const cached = getCachedPairingExchange(key);
-			if (cached) return cached;
-			if (!consumePairingSecret(key)) return getCachedPairingExchange(key);
-			const payload = buildPayload();
-			cachePairingExchange(key, payload);
-			return payload;
-		})();
-		inflightExchanges.set(key, inflight);
-	}
-	try {
-		return await inflight;
-	} finally {
-		if (inflightExchanges.get(key) === inflight) inflightExchanges.delete(key);
-	}
-}
-function createPairingSecret() {
-	ensureCleanupTimer();
-	const secret = randomBytes(32).toString("base64url");
-	const expiresAt = new Date(Date.now() + PAIRING_TTL_MS);
-	sessions.set(secret, {
-		expiresAt,
-		consumed: false
-	});
-	log.info({ expiresAt: expiresAt.toISOString() }, "Pairing session created");
-	return {
-		secret,
-		expiresAt
-	};
-}
-function consumePairingSecret(secret) {
-	if (!secret.trim()) return false;
-	const session = sessions.get(secret);
-	if (!session) return false;
-	if (session.consumed) return false;
-	if (Date.now() > session.expiresAt.getTime()) {
-		sessions.delete(secret);
-		return false;
-	}
-	session.consumed = true;
-	sessions.delete(secret);
-	log.info("Pairing session consumed");
-	return true;
-}
-/** @internal */
-function resetPairingSessionsForTests() {
-	sessions.clear();
-	exchangeReplayCache.clear();
-	inflightExchanges.clear();
-	if (cleanupTimer) {
-		clearInterval(cleanupTimer);
-		cleanupTimer = null;
-	}
-}
-//#endregion
-export { cachePairingExchange, consumePairingSecret, createPairingSecret, exchangePairingSecretOnce, getCachedPairingExchange, resetPairingSessionsForTests };

package/dist/src/tunnel/tunnel-qr.d.ts

@@ -1,9 +0,0 @@
-import type { TunnelQrPayload } from './tunnel-types.js';
-/** First non-internal IPv4 suitable for LAN QR (when gateway listens on 0.0.0.0). */
-export declare function resolveLanGatewayUrl(gatewayHost: string, gatewayPort: number): string | null;
-export declare function buildMobileConnectQrPayload(input: {
-    publicUrl: string;
-    lanUrl: string | null;
-    pairingSecret: string;
-    expiresAt?: string;
-}): TunnelQrPayload;

package/dist/src/tunnel/tunnel-qr.js

@@ -1,29 +0,0 @@
-import { enumerateLanGatewayCandidates } from "../gateway/host.js";
-//#region src/tunnel/tunnel-qr.ts
-function trimBase(raw) {
-	return raw.trim().replace(/\/+$/, "");
-}
-/** First non-internal IPv4 suitable for LAN QR (when gateway listens on 0.0.0.0). */
-function resolveLanGatewayUrl(gatewayHost, gatewayPort) {
-	const host = gatewayHost.trim().toLowerCase();
-	if (host === "127.0.0.1" || host === "localhost" || host === "::1") return null;
-	let ip;
-	if (host === "0.0.0.0" || host === "::" || host === "") ip = enumerateLanGatewayCandidates(gatewayPort)[0]?.address;
-	else if (!host.includes(":")) ip = host;
-	if (!ip) return null;
-	return trimBase(`http://${ip}:${gatewayPort}`);
-}
-function buildMobileConnectQrPayload(input) {
-	const params = new URLSearchParams();
-	params.set("baseUrl", input.publicUrl);
-	if (input.lanUrl) params.set("lanUrl", input.lanUrl);
-	if (input.pairingSecret) params.set("ps", input.pairingSecret);
-	return {
-		qrPayload: `xopc://gateway/mobile-connect?${params.toString()}`,
-		publicUrl: input.publicUrl,
-		lanUrl: input.lanUrl,
-		expiresAt: input.expiresAt
-	};
-}
-//#endregion
-export { buildMobileConnectQrPayload, resolveLanGatewayUrl };