@camstack/addon-import-alexa 0.1.2 → 0.1.3

package/dist/addon.mjs

@@ -1,4 +1,6 @@
 import { createRequire } from "node:module";
+import { networkInterfaces } from "node:os";
+import { randomBytes } from "node:crypto";
 import { promises } from "node:fs";
 import path from "node:path";
 //#region \0rolldown/runtime.js
@@ -6839,6 +6841,123 @@ var ConvertResultSchema = object({
 	})).readonly()
 });
 /**
+* Build an `IAddonRouteProvider` from a list of routes. Implements
+* both the operator-facing `getRoutes` (returning route descriptors
+* minus the handlers, which can't cross JSON) and the framework-
+* private `invoke` method that the hub calls when this provider lives
+* in a forked worker.
+*
+* Co-located addons use the returned `getRoutes` directly because
+* their handlers don't need to cross any wire. The `invoke` method
+* is present anyway so the bridge code on the hub is uniform — it
+* doesn't need to switch on "local vs remote provider" at the call
+* site.
+*
+* Example:
+*   const routes: IAddonHttpRoute[] = [
+*     { method: 'GET', path: '/start', access: 'public', handler: this.handleStart },
+*   ]
+*   return [
+*     {
+*       capability: addonRoutesCapability,
+*       provider: buildAddonRouteProvider('auth-oidc', routes),
+*     },
+*   ]
+*/
+function buildAddonRouteProvider(id, routes) {
+	return {
+		id,
+		getRoutes: () => routes,
+		invoke: async (input) => {
+			const match = matchRoute(routes, input.method, input.path);
+			if (!match) return {
+				status: 404,
+				headers: {},
+				redirectUrl: null,
+				body: { error: `No route matches ${input.method} ${input.path}` }
+			};
+			const envelope = {
+				status: 200,
+				headers: {},
+				redirectUrl: null
+			};
+			const reply = buildCapturingReply(envelope);
+			const request = {
+				params: {
+					...input.params,
+					...match.params
+				},
+				query: input.query,
+				body: input.body,
+				headers: input.headers,
+				...input.user ? { user: input.user } : {},
+				...input.scopedToken !== void 0 ? { scopedToken: input.scopedToken } : {}
+			};
+			await match.route.handler(request, reply);
+			return envelope;
+		}
+	};
+}
+/**
+* Pattern matcher: same semantics as `AddonRouteRegistry.matchRoute`
+* but operating on a flat list and bypassing the `/addon/<id>/` prefix
+* — the bridge sends the post-prefix path directly so we don't need
+* to round-trip it through normalization.
+*/
+function matchRoute(routes, method, path) {
+	const normalizedMethod = method.toUpperCase();
+	for (const route of routes) {
+		if (route.method !== normalizedMethod) continue;
+		const params = matchPath(route.path, path);
+		if (params !== null) return {
+			route,
+			params
+		};
+	}
+	return null;
+}
+function matchPath(pattern, p) {
+	const patternParts = pattern.split("/").filter(Boolean);
+	const pathParts = p.split("/").filter(Boolean);
+	if (patternParts.length !== pathParts.length) return null;
+	const params = {};
+	for (let i = 0; i < patternParts.length; i++) {
+		const a = patternParts[i];
+		const b = pathParts[i];
+		if (a.startsWith(":")) params[a.slice(1)] = b;
+		else if (a !== b) return null;
+	}
+	return params;
+}
+function buildCapturingReply(envelope) {
+	const wrapper = {
+		status(code) {
+			envelope.status = code;
+			return wrapper;
+		},
+		code(code) {
+			envelope.status = code;
+			return wrapper;
+		},
+		send(data) {
+			envelope.body = data;
+		},
+		redirect(url) {
+			envelope.redirectUrl = url;
+			if (envelope.status === 200) envelope.status = 302;
+		},
+		header(name, value) {
+			envelope.headers[name.toLowerCase()] = value;
+			return wrapper;
+		},
+		type(mime) {
+			envelope.contentType = mime;
+			return wrapper;
+		}
+	};
+	return wrapper;
+}
+/**
 * Numeric day-of-week: 0 = Sunday … 6 = Saturday (matches `Date.getDay`).
 * Named `RecordingWeekday` to avoid collision with the string-union
 * `Weekday` exported from `interfaces/timezones.ts`.
@@ -15606,7 +15725,24 @@ var InvokeReplyEnvelopeSchema = object({
 	/** Set when the handler called `reply.type(mime)`. */
 	contentType: string().optional()
 });
-method(_void(), array(AddonHttpRouteSchema)), method(InvokeRequestSchema, InvokeReplyEnvelopeSchema, { kind: "mutation" });
+var addonRoutesCapability = {
+	name: "addon-routes",
+	scope: "system",
+	mode: "collection",
+	internal: true,
+	methods: {
+		getRoutes: method(_void(), array(AddonHttpRouteSchema)),
+		/**
+		* Cross-process dispatch entry point. Forked addons implement this
+		* (via `buildAddonRouteProvider`) so the hub's Fastify catch-all
+		* can route through Moleculer when the handler lives in a worker.
+		*
+		* Local addons can implement it for free with the same helper;
+		* the hub bypasses the wire on co-located addons.
+		*/
+		invoke: method(InvokeRequestSchema, InvokeReplyEnvelopeSchema, { kind: "mutation" })
+	}
+};
 /**
 * shm ring usage stats for a `frameSink: 'shm'` decoder session —
 * exposed via `decoder.getShmStats` so downstream consumers can
@@ -23940,6 +24076,122 @@ object({
 	schemaVersion: literal(1)
 });
 //#endregion
+//#region src/config.ts
+/**
+* Alexa account connection settings for ONE broker (= one Amazon account).
+*
+* v1 uses the unofficial alexa-remote2 cookie / refresh-token flow. The operator
+* supplies the Amazon domain/region and either a captured cookie blob or a
+* refresh token (the proxy-login UX captures one of these). State is poll-only,
+* so a configurable poll interval is included.
+*/
+var alexaConnectionSchema = object({
+	/** Amazon domain/region. */
+	amazonDomain: string().min(1).default("amazon.com").describe("Amazon domain (region)"),
+	/**
+	* Captured cookie material — either a raw cookie string OR the full
+	* `cookieData` JSON registration blob produced by alexa-remote2's standalone
+	* proxy login (preferred: it carries the refresh token + lets the session
+	* auto-refresh). This is the primary auth input.
+	*/
+	cookie: string().default("").describe("Captured Alexa cookie / cookieData blob (from proxy login)"),
+	/**
+	* Refresh token. NOTE: a bare refresh token alone is NOT sufficient to init
+	* alexa-remote2 — supply the full cookie / cookieData blob (which embeds it).
+	* Retained for provenance / forward-compat.
+	*/
+	refreshToken: string().default("").describe("Alexa refresh token (must be inside cookie blob)"),
+	/** Device-registration secret some flows need. */
+	macDms: string().default("").describe("macDms device-registration secret (optional)"),
+	/** Poll interval for state sync (Alexa has no clean 3rd-party push). */
+	pollIntervalMs: preprocess((v) => v === "" || v === null ? void 0 : v, number().int().min(15e3).max(36e5).default(6e4)).describe("State poll interval (ms) — conservative to avoid Amazon throttling")
+});
+/** Translate a stored connection into the client's credentials shape. */
+function connectionToCredentials(conn) {
+	return {
+		amazonDomain: conn.amazonDomain,
+		...conn.cookie.length > 0 ? { cookie: conn.cookie } : {},
+		...conn.refreshToken.length > 0 ? { refreshToken: conn.refreshToken } : {},
+		...conn.macDms.length > 0 ? { macDms: conn.macDms } : {}
+	};
+}
+/** A single registered Alexa account ("broker"). */
+var AlexaBrokerEntrySchema = object({
+	id: string().min(1),
+	name: string().min(1),
+	connection: alexaConnectionSchema,
+	integrationId: string().optional()
+});
+/**
+* Interactive proxy-login settings (addon-global, not per-broker). alexa-remote2
+* spins a local reverse-proxy to Amazon's login page on `proxyHost:proxyPort`;
+* the operator opens that URL and logs in. `proxyHost` MUST be the host:port the
+* operator's browser uses (alexa-cookie2 rewrites Amazon URLs to absolute
+* `http://<proxyHost>:<proxyPort>/...`), so it is a directly-reachable host —
+* the hub's LAN IP/hostname — NOT behind the hub's HTTPS data-plane mount.
+* Empty `proxyHost` ⇒ auto-detect the host's primary non-loopback IPv4 at
+* login-start time.
+*/
+var alexaProxyLoginSchema = object({
+	proxyHost: string().default("").describe("Host/IP the browser uses to reach the login proxy (blank = auto-detect)"),
+	proxyPort: preprocess((v) => v === "" || v === null ? void 0 : v, number().int().min(1).max(65535).default(3456)).describe("Port the local Amazon-login proxy listens on (must be reachable)")
+});
+/** Top-level addon config — broker entries + the proxy-login settings. */
+var alexaAddonConfigSchema = object({
+	brokers: array(AlexaBrokerEntrySchema).default([]),
+	proxyLogin: alexaProxyLoginSchema.default({
+		proxyHost: "",
+		proxyPort: 3456
+	})
+});
+/** Narrow an `unknown` to a shallow plain-object record (cast-free boundary). */
+function toRecord(value) {
+	if (typeof value === "object" && value !== null && !Array.isArray(value)) return Object.fromEntries(Object.entries(value));
+	return {};
+}
+/** Coerce a loose settings blob through the connection schema, applying defaults. */
+function settingsToAlexaConnection(settings) {
+	return alexaConnectionSchema.parse(toRecord(settings));
+}
+/** Hand-written connection form for the broker/integration creation UI. */
+function buildConnectionFormSchema() {
+	return { sections: [{
+		id: "alexa-account",
+		title: "Amazon Alexa account",
+		description: "Link an Amazon account via the unofficial Alexa client. Supply a captured cookie OR a refresh token. NOTE: this is an unofficial integration — Amazon can change or break it without notice, and it may violate Amazon ToS. State is polled, not pushed.",
+		columns: 1,
+		fields: [
+			{
+				type: "text",
+				key: "amazonDomain",
+				label: "Amazon domain (region)",
+				placeholder: "amazon.com",
+				default: "amazon.com"
+			},
+			{
+				type: "password",
+				key: "cookie",
+				label: "Cookie blob (from proxy login)",
+				showToggle: true
+			},
+			{
+				type: "password",
+				key: "refreshToken",
+				label: "Refresh token (alternative to cookie)",
+				showToggle: true
+			},
+			{
+				type: "number",
+				key: "pollIntervalMs",
+				label: "State poll interval (ms)",
+				min: 15e3,
+				max: 36e5,
+				default: 6e4
+			}
+		]
+	}] };
+}
+//#endregion
 //#region ../../node_modules/extend/index.js
 var require_extend = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	var hasOwn = Object.prototype.hasOwnProperty;
@@ -62524,7 +62776,7 @@ var require_alexa_cookie = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports = AlexaCookie();
 }));
 //#endregion
-//#region src/alexa-remote-decode.ts
+//#region src/alexa-proxy-login.ts
 var import_alexa_remote = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	var https = __require("https");
 	var querystring = __require("querystring");
@@ -65143,6 +65395,413 @@ var import_alexa_remote = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin
 	module.exports = AlexaRemote;
 })))());
 /**
+* A single interactive proxy-login attempt. One instance = one Amazon login.
+* Construct → {@link start} → poll {@link getStatus} → on `captured` the
+* `onCookie` callback has fired with the blob → {@link dispose}.
+*/
+var AlexaProxyLoginSession = class {
+	#opts;
+	#logger;
+	#remote = null;
+	#phase = "starting";
+	#error = null;
+	#startedAt = Date.now();
+	#capturedAt = null;
+	#captured = false;
+	constructor(opts) {
+		this.#opts = opts;
+		this.#logger = opts.logger;
+	}
+	/** `http://<proxyOwnIp>:<proxyPort>/` — what the operator opens. */
+	get loginUrl() {
+		return `http://${this.#opts.proxyOwnIp}:${this.#opts.proxyPort}/`;
+	}
+	getStatus() {
+		return {
+			sessionId: this.#opts.sessionId,
+			phase: this.#phase,
+			loginUrl: this.#phase === "awaiting-login" ? this.loginUrl : "",
+			amazonDomain: this.#opts.amazonDomain,
+			error: this.#error,
+			startedAt: this.#startedAt,
+			capturedAt: this.#capturedAt
+		};
+	}
+	/**
+	* Spin up the proxy. Returns once `init` has been kicked off; the proxy then
+	* binds asynchronously. alexa-remote2's `init` callback fires TWICE in proxy
+	* mode (this is by design, not a bug):
+	*   1. when the proxy is LISTENING, with an Error whose message is
+	*      "Please open http://… and login" — this is the "proxy ready" signal
+	*      (→ `awaiting-login`), NOT a failure;
+	*   2. after a successful Amazon login, alexa-remote2 calls `setCookie` (→ the
+	*      `cookie` event, our real capture path) and auto-stops the proxy.
+	* So `#onInitDone` must treat the "Please open" error as readiness and any
+	* OTHER error as a genuine failure.
+	*/
+	async start() {
+		const remote = new import_alexa_remote.default();
+		this.#remote = remote;
+		const amazonPage = this.#opts.amazonDomain.length > 0 ? this.#opts.amazonDomain : "amazon.com";
+		remote.on("cookie", () => this.#onCookieEvent(remote));
+		remote.init({
+			proxyOnly: true,
+			proxyOwnIp: this.#opts.proxyOwnIp,
+			proxyPort: this.#opts.proxyPort,
+			proxyLogLevel: "warn",
+			amazonPage,
+			logger: (...args) => {
+				const line = args.map(String).join(" ");
+				if (SECRET_LINE_RE.test(line)) return;
+				this.#logger.debug("alexa proxy-login", { meta: {
+					sessionId: this.#opts.sessionId,
+					line
+				} });
+			}
+		}, (err) => this.#onInitDone(err));
+	}
+	/** Stop the proxy + the remote (idempotent). Safe to call multiple times. */
+	async dispose() {
+		const remote = this.#remote;
+		this.#remote = null;
+		if (remote === null) return;
+		try {
+			remote.stop();
+		} catch (err) {
+			this.#logger.warn("alexa proxy-login: dispose stop() failed", { meta: {
+				sessionId: this.#opts.sessionId,
+				error: errMsg(err)
+			} });
+		}
+	}
+	/** Mark cancelled + dispose. */
+	async cancel() {
+		if (this.#phase !== "captured") this.#phase = "cancelled";
+		await this.dispose();
+	}
+	#onCookieEvent(remote) {
+		if (this.#captured) return;
+		const cookieData = remote.cookieData;
+		const cookie = remote.cookie;
+		if (cookieData === void 0 || cookieData === null) return;
+		if (typeof cookie !== "string" || cookie.length === 0) return;
+		const blob = isStringOrObject(cookieData) ? cookieData : null;
+		if (blob === null) return;
+		this.#captured = true;
+		this.#capturedAt = Date.now();
+		this.#phase = "captured";
+		this.#logger.info("alexa proxy-login: cookie captured", { meta: { sessionId: this.#opts.sessionId } });
+		try {
+			this.#opts.onCookie(this.#opts.sessionId, {
+				cookieData: blob,
+				cookie
+			});
+		} catch (err) {
+			this.#logger.warn("alexa proxy-login: onCookie handler threw", { meta: {
+				sessionId: this.#opts.sessionId,
+				error: errMsg(err)
+			} });
+		}
+		this.dispose();
+	}
+	#onInitDone(err) {
+		if (this.#captured || this.#phase === "cancelled") return;
+		if (err === void 0) return;
+		if (isProxyReadyError(err)) {
+			if (this.#phase === "starting") {
+				this.#phase = "awaiting-login";
+				this.#logger.info("alexa proxy-login: proxy ready — awaiting Amazon login", { meta: {
+					sessionId: this.#opts.sessionId,
+					loginUrl: this.loginUrl
+				} });
+			}
+			return;
+		}
+		this.#phase = "error";
+		this.#error = errMsg(err);
+		this.#logger.warn("alexa proxy-login: init failed", { meta: {
+			sessionId: this.#opts.sessionId,
+			error: this.#error
+		} });
+		this.dispose();
+	}
+};
+/**
+* Lines emitted by alexa-cookie2 that contain raw credential material
+* (cookie values, CSRF tokens, bearer tokens). Any log line matching this
+* pattern is silently dropped — it must never reach the structured logger or
+* Loki.
+*
+* Covers patterns such as:
+*   "Alexa-Cookie: Update Cookie <name>=<value>"
+*   "Result: csrf=…, Cookie=…"
+*   "Set-Cookie: …"
+*/
+var SECRET_LINE_RE = /cookie|csrf|token/i;
+/**
+* alexa-remote2 signals "proxy ready, go log in" by invoking `init`'s callback
+* with an Error carrying the "Please open http://…/ with your browser and login"
+* message (alexa-cookie2 `generateAlexaCookie` listening callback). Detect it so
+* we treat readiness as success, not failure.
+*/
+function isProxyReadyError(err) {
+	const m = errMsg(err).toLowerCase();
+	return m.includes("please open") && m.includes("login");
+}
+/** True for the `string | object` forms alexa-remote2 accepts back as `cookie`. */
+function isStringOrObject(value) {
+	return typeof value === "string" || typeof value === "object" && value !== null;
+}
+//#endregion
+//#region src/alexa-proxy-login-manager.ts
+var AlexaProxyLoginManager = class {
+	#logger;
+	#getProxyConfig;
+	#session = null;
+	#captured = /* @__PURE__ */ new Map();
+	constructor(deps) {
+		this.#logger = deps.logger;
+		this.#getProxyConfig = deps.getProxyConfig;
+	}
+	/**
+	* Start a fresh proxy-login. Cancels any in-flight session first (single
+	* fixed port). Returns the `loginUrl` for the onboarding UI to open.
+	*/
+	async start(amazonDomain) {
+		await this.cancelActive();
+		const { proxyHost, proxyPort } = this.#getProxyConfig();
+		const host = proxyHost.length > 0 ? proxyHost : detectPrimaryIpv4();
+		if (host.length === 0) throw new Error("alexa proxy-login: could not auto-detect a reachable host IP — set proxyHost in settings");
+		const sessionId = randomBytes(9).toString("base64url");
+		const session = new AlexaProxyLoginSession({
+			sessionId,
+			amazonDomain,
+			proxyOwnIp: host,
+			proxyPort,
+			logger: this.#logger,
+			onCookie: (id, captured) => {
+				this.#captured.set(id, captured);
+			}
+		});
+		this.#session = session;
+		try {
+			await session.start();
+		} catch (err) {
+			this.#session = null;
+			await session.dispose();
+			throw new Error(`alexa proxy-login: failed to start proxy — ${errMsg(err)}`);
+		}
+		return {
+			sessionId,
+			loginUrl: session.loginUrl,
+			amazonDomain
+		};
+	}
+	/** Live status for a session id (or null when it isn't the active one). */
+	status(sessionId) {
+		const session = this.#session;
+		if (session === null) return null;
+		const status = session.getStatus();
+		return status.sessionId === sessionId ? status : null;
+	}
+	/**
+	* Pull (and consume) the captured cookie material for a session. Returns null
+	* when nothing has been captured yet. The caller commits it onto a broker.
+	*/
+	takeCaptured(sessionId) {
+		const captured = this.#captured.get(sessionId) ?? null;
+		if (captured !== null) this.#captured.delete(sessionId);
+		return captured;
+	}
+	/** Cancel a specific session (no-op when it isn't active). */
+	async cancel(sessionId) {
+		const session = this.#session;
+		if (session === null) return;
+		if (session.getStatus().sessionId !== sessionId) return;
+		await this.cancelActive();
+		this.#captured.delete(sessionId);
+	}
+	/** Cancel + dispose whatever session is currently active. */
+	async cancelActive() {
+		const session = this.#session;
+		this.#session = null;
+		if (session === null) return;
+		try {
+			await session.cancel();
+		} catch (err) {
+			this.#logger.warn("alexa proxy-login: cancelActive failed", { meta: { error: errMsg(err) } });
+		}
+	}
+	/** Full teardown on addon shutdown. */
+	async dispose() {
+		await this.cancelActive();
+		this.#captured.clear();
+	}
+};
+/**
+* Best-effort primary non-loopback IPv4 of the host. Used when the operator
+* leaves `proxyHost` blank. Returns '' when none found (then the operator must
+* set it explicitly — common on multi-homed/containerised hosts).
+*/
+function detectPrimaryIpv4() {
+	const ifaces = networkInterfaces();
+	for (const addrs of Object.values(ifaces)) {
+		if (addrs === void 0) continue;
+		for (const addr of addrs) if (addr.family === "IPv4" && !addr.internal && addr.address.length > 0) return addr.address;
+	}
+	return "";
+}
+/**
+* Serialize the captured `cookieData` blob into the single STRING the broker
+* connection stores in its `cookie` field. `AlexaRemoteClient` already parses a
+* JSON-object cookie string back into the richer object form on init, so we
+* persist the object as JSON; a bare string passes through unchanged.
+*/
+function capturedToCookieString(captured) {
+	const { cookieData } = captured;
+	if (typeof cookieData === "string") return cookieData;
+	try {
+		return JSON.stringify(cookieData);
+	} catch {
+		return captured.cookie;
+	}
+}
+//#endregion
+//#region src/alexa-login-routes.ts
+var StartBodySchema = object({ amazonDomain: _enum([
+	"amazon.com",
+	"amazon.it",
+	"amazon.de",
+	"amazon.co.uk",
+	"amazon.fr",
+	"amazon.es",
+	"amazon.ca",
+	"amazon.com.au",
+	"amazon.co.jp",
+	"amazon.in",
+	"amazon.com.br",
+	"amazon.com.mx"
+]).default("amazon.com") });
+var StatusQuerySchema = object({ sessionId: string().min(1) });
+var CommitBodySchema = object({
+	sessionId: string().min(1),
+	/** Name for a NEW broker (when `brokerId` is omitted). */
+	name: string().min(1).default("Alexa account"),
+	/** Existing broker to RE-LINK; omit to create a fresh broker. */
+	brokerId: string().min(1).optional()
+});
+var CancelBodySchema = object({ sessionId: string().min(1) });
+/** Parse a JSON body that may arrive as an object or a raw string. */
+function asRecord(body) {
+	if (typeof body === "object" && body !== null && !Array.isArray(body)) return Object.fromEntries(Object.entries(body));
+	if (typeof body === "string" && body.length > 0) try {
+		const parsed = JSON.parse(body);
+		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) return Object.fromEntries(Object.entries(parsed));
+	} catch {}
+	return {};
+}
+function buildAlexaLoginRoutes(deps) {
+	const { logger, proxyLogin, commitCookie } = deps;
+	return [
+		{
+			method: "POST",
+			path: "/login/start",
+			access: "admin",
+			description: "Start the interactive Amazon proxy-login; returns the URL to open",
+			handler: async (req, reply) => {
+				const parsed = StartBodySchema.safeParse(asRecord(req.body));
+				if (!parsed.success) {
+					reply.code(400).send({
+						error: "invalid body",
+						detail: parsed.error.message
+					});
+					return;
+				}
+				try {
+					const result = await proxyLogin.start(parsed.data.amazonDomain);
+					reply.code(200).send(result);
+				} catch (err) {
+					logger.warn("alexa login/start failed", { meta: { error: errMsg(err) } });
+					reply.code(500).send({ error: errMsg(err) });
+				}
+			}
+		},
+		{
+			method: "GET",
+			path: "/login/status",
+			access: "admin",
+			description: "Poll the interactive login session status (no secrets returned)",
+			handler: async (req, reply) => {
+				const parsed = StatusQuerySchema.safeParse(req.query);
+				if (!parsed.success) {
+					reply.code(400).send({ error: "missing sessionId" });
+					return;
+				}
+				const status = proxyLogin.status(parsed.data.sessionId);
+				if (status === null) {
+					reply.code(404).send({ error: "unknown or expired session" });
+					return;
+				}
+				reply.code(200).send(status);
+			}
+		},
+		{
+			method: "POST",
+			path: "/login/commit",
+			access: "admin",
+			description: "Persist the captured cookie onto a new or existing broker",
+			handler: async (req, reply) => {
+				const parsed = CommitBodySchema.safeParse(asRecord(req.body));
+				if (!parsed.success) {
+					reply.code(400).send({
+						error: "invalid body",
+						detail: parsed.error.message
+					});
+					return;
+				}
+				const { sessionId, name, brokerId } = parsed.data;
+				const status = proxyLogin.status(sessionId);
+				const captured = proxyLogin.takeCaptured(sessionId);
+				if (captured === null) {
+					reply.code(409).send({ error: "no captured cookie for this session (login not completed yet?)" });
+					return;
+				}
+				const amazonDomain = status?.amazonDomain ?? "amazon.com";
+				try {
+					const result = await commitCookie({
+						cookie: capturedToCookieString(captured),
+						amazonDomain,
+						name,
+						...brokerId !== void 0 ? { brokerId } : {}
+					});
+					await proxyLogin.cancel(sessionId);
+					reply.code(200).send(result);
+				} catch (err) {
+					logger.warn("alexa login/commit failed", { meta: { error: errMsg(err) } });
+					reply.code(500).send({ error: errMsg(err) });
+				}
+			}
+		},
+		{
+			method: "POST",
+			path: "/login/cancel",
+			access: "admin",
+			description: "Cancel an in-flight interactive login session",
+			handler: async (req, reply) => {
+				const parsed = CancelBodySchema.safeParse(asRecord(req.body));
+				if (!parsed.success) {
+					reply.code(400).send({ error: "missing sessionId" });
+					return;
+				}
+				await proxyLogin.cancel(parsed.data.sessionId);
+				reply.code(200).send({ ok: true });
+			}
+		}
+	];
+}
+//#endregion
+//#region src/alexa-remote-decode.ts
+/**
 * Pure, total decoders translating `alexa-remote2` JSON response bodies into the
 * controller-agnostic shapes the addon consumes ({@link AlexaAppliance} /
 * {@link AlexaStateValue}). NO `alexa-remote2` import — these run against plain
@@ -65732,100 +66391,6 @@ var AlexaCommandSink = class {
 /** The single in-process command sink shared across the addon. */
 var alexaCommands = new AlexaCommandSink();
 //#endregion
-//#region src/config.ts
-/**
-* Alexa account connection settings for ONE broker (= one Amazon account).
-*
-* v1 uses the unofficial alexa-remote2 cookie / refresh-token flow. The operator
-* supplies the Amazon domain/region and either a captured cookie blob or a
-* refresh token (the proxy-login UX captures one of these). State is poll-only,
-* so a configurable poll interval is included.
-*/
-var alexaConnectionSchema = object({
-	/** Amazon domain/region. */
-	amazonDomain: string().min(1).default("amazon.com").describe("Amazon domain (region)"),
-	/**
-	* Captured cookie material — either a raw cookie string OR the full
-	* `cookieData` JSON registration blob produced by alexa-remote2's standalone
-	* proxy login (preferred: it carries the refresh token + lets the session
-	* auto-refresh). This is the primary auth input.
-	*/
-	cookie: string().default("").describe("Captured Alexa cookie / cookieData blob (from proxy login)"),
-	/**
-	* Refresh token. NOTE: a bare refresh token alone is NOT sufficient to init
-	* alexa-remote2 — supply the full cookie / cookieData blob (which embeds it).
-	* Retained for provenance / forward-compat.
-	*/
-	refreshToken: string().default("").describe("Alexa refresh token (must be inside cookie blob)"),
-	/** Device-registration secret some flows need. */
-	macDms: string().default("").describe("macDms device-registration secret (optional)"),
-	/** Poll interval for state sync (Alexa has no clean 3rd-party push). */
-	pollIntervalMs: preprocess((v) => v === "" || v === null ? void 0 : v, number().int().min(15e3).max(36e5).default(6e4)).describe("State poll interval (ms) — conservative to avoid Amazon throttling")
-});
-/** Translate a stored connection into the client's credentials shape. */
-function connectionToCredentials(conn) {
-	return {
-		amazonDomain: conn.amazonDomain,
-		...conn.cookie.length > 0 ? { cookie: conn.cookie } : {},
-		...conn.refreshToken.length > 0 ? { refreshToken: conn.refreshToken } : {},
-		...conn.macDms.length > 0 ? { macDms: conn.macDms } : {}
-	};
-}
-/** Top-level addon config — an ordered list of broker entries (default empty). */
-var alexaAddonConfigSchema = object({ brokers: array(object({
-	id: string().min(1),
-	name: string().min(1),
-	connection: alexaConnectionSchema,
-	integrationId: string().optional()
-})).default([]) });
-/** Narrow an `unknown` to a shallow plain-object record (cast-free boundary). */
-function toRecord(value) {
-	if (typeof value === "object" && value !== null && !Array.isArray(value)) return Object.fromEntries(Object.entries(value));
-	return {};
-}
-/** Coerce a loose settings blob through the connection schema, applying defaults. */
-function settingsToAlexaConnection(settings) {
-	return alexaConnectionSchema.parse(toRecord(settings));
-}
-/** Hand-written connection form for the broker/integration creation UI. */
-function buildConnectionFormSchema() {
-	return { sections: [{
-		id: "alexa-account",
-		title: "Amazon Alexa account",
-		description: "Link an Amazon account via the unofficial Alexa client. Supply a captured cookie OR a refresh token. NOTE: this is an unofficial integration — Amazon can change or break it without notice, and it may violate Amazon ToS. State is polled, not pushed.",
-		columns: 1,
-		fields: [
-			{
-				type: "text",
-				key: "amazonDomain",
-				label: "Amazon domain (region)",
-				placeholder: "amazon.com",
-				default: "amazon.com"
-			},
-			{
-				type: "password",
-				key: "cookie",
-				label: "Cookie blob (from proxy login)",
-				showToggle: true
-			},
-			{
-				type: "password",
-				key: "refreshToken",
-				label: "Refresh token (alternative to cookie)",
-				showToggle: true
-			},
-			{
-				type: "number",
-				key: "pollIntervalMs",
-				label: "State poll interval (ms)",
-				min: 15e3,
-				max: 36e5,
-				default: 6e4
-			}
-		]
-	}] };
-}
-//#endregion
 //#region src/alexa-integration-manager.ts
 /**
 * Wraps exactly one {@link AlexaClient} (= one Amazon account). Authenticates on
@@ -66992,7 +67557,13 @@ function isKnownCap(cap) {
 //#endregion
 //#region src/addon.ts
 /** Default config — a fresh install starts with no accounts. */
-var DEFAULTS = { brokers: [] };
+var DEFAULTS = {
+	brokers: [],
+	proxyLogin: {
+		proxyHost: "",
+		proxyPort: 3456
+	}
+};
 /** Device types an imported Alexa appliance can materialise as. */
 var ALEXA_DEVICE_TYPES = [
 	DeviceType.Switch,
@@ -67015,15 +67586,21 @@ var ALEXA_DEVICE_TYPES = [
 *
 * The Alexa cloud client is the real alexa-remote2 binding (`AlexaRemoteClient`,
 * see `alexa-remote-client.ts`); `StubAlexaClient` remains as a test double.
-* Auth is cookie / cookieData-blob based (no interactive proxy login inside the
-* hub) — supply a pre-obtained cookie from settings; the session is persisted to
-* the addon `dataDir` and auto-refreshed.
+* Auth is cookie / cookieData-blob based. The preferred onboarding path is the
+* interactive proxy login (alexa-remote2 proxy auth mode, driven by the
+* onboarding wizard via the addon-routes control plane): the operator opens a
+* local proxy URL in their browser, completes the real Amazon OAuth/2FA flow,
+* and the captured cookie is persisted automatically. Pasting a pre-obtained
+* cookie is kept as a fallback. Either way the cookie lands in the same
+* `connection.cookie` field; the session is persisted to the addon `dataDir`
+* and auto-refreshed.
 */
 var AlexaImportAddon = class extends BaseDeviceProvider {
 	addonId = "import-alexa";
 	providerName = "Alexa Import";
 	deviceClasses = Object.fromEntries(ALEXA_DEVICE_TYPES.map((t) => [t, AlexaDevice]));
 	registry = null;
+	proxyLogin = null;
 	constructor() {
 		super({ ...DEFAULTS });
 	}
@@ -67054,9 +67631,24 @@ var AlexaImportAddon = class extends BaseDeviceProvider {
 		});
 		alexaCommands.setDispatcher((brokerId, command) => this.requireRegistry().sendCommand(brokerId, command));
 		await this.registry.restore(this.config.brokers);
+		this.proxyLogin = new AlexaProxyLoginManager({
+			logger: this.ctx.logger,
+			getProxyConfig: () => {
+				const cfg = alexaProxyLoginSchema.parse(this.config.proxyLogin ?? {});
+				return {
+					proxyHost: cfg.proxyHost,
+					proxyPort: cfg.proxyPort
+				};
+			}
+		});
 		this.ctx.logger.info("Alexa: import addon initialised", { meta: { brokerCount: this.config.brokers.length } });
 		await this.reconcileIntegrationsToBrokers();
 		this.subscribeIntegrationLifecycle();
+		const loginRoutes = buildAlexaLoginRoutes({
+			logger: this.ctx.logger,
+			proxyLogin: this.proxyLogin,
+			commitCookie: (input) => this.commitCapturedCookie(input)
+		});
 		return [
 			...regs,
 			{
@@ -67066,6 +67658,10 @@ var AlexaImportAddon = class extends BaseDeviceProvider {
 			{
 				capability: deviceAdoptionCapability,
 				provider: this.buildAdoptionProvider()
+			},
+			{
+				capability: addonRoutesCapability,
+				provider: buildAddonRouteProvider("import-alexa", loginRoutes)
 			}
 		];
 	}
@@ -67115,6 +67711,12 @@ var AlexaImportAddon = class extends BaseDeviceProvider {
 	}
 	async onShutdown() {
 		alexaCommands.clear();
+		try {
+			await this.proxyLogin?.dispose();
+		} catch (err) {
+			this.ctx.logger.warn("Alexa: proxy-login dispose error", { meta: { error: errMsg(err) } });
+		}
+		this.proxyLogin = null;
 		try {
 			await this.registry?.shutdown();
 		} catch (err) {
@@ -67191,6 +67793,40 @@ var AlexaImportAddon = class extends BaseDeviceProvider {
 			logger: this.ctx.logger
 		});
 	}
+	/**
+	* Persist a cookie captured by the interactive proxy-login onto a broker. With
+	* a `brokerId` the broker is RE-LINKED (credentials swapped, devices kept);
+	* otherwise a NEW broker is created. The captured cookie goes into exactly the
+	* same `connection.cookie` field a pasted cookie would — so the registry /
+	* poll / adoption layers are unchanged.
+	*/
+	async commitCapturedCookie(input) {
+		const reg = this.requireRegistry();
+		if (input.brokerId !== void 0) {
+			const existing = this.config.brokers.find((b) => b.id === input.brokerId);
+			if (existing === void 0) throw new Error(`commitCookie: unknown broker "${input.brokerId}"`);
+			const connection = {
+				...existing.connection,
+				amazonDomain: input.amazonDomain,
+				cookie: input.cookie
+			};
+			const updated = await reg.updateEntry(input.brokerId, connection);
+			await this.updateGlobalSettings({ brokers: this.config.brokers.map((b) => b.id === input.brokerId ? updated : b) });
+			this.ctx.logger.info("Alexa: proxy-login cookie committed to existing broker", { meta: { brokerId: input.brokerId } });
+			return { brokerId: input.brokerId };
+		}
+		const connection = settingsToAlexaConnection({
+			amazonDomain: input.amazonDomain,
+			cookie: input.cookie
+		});
+		const entry = await reg.createEntry(input.name, connection);
+		await this.updateGlobalSettings({ brokers: [...this.config.brokers, entry] });
+		this.ctx.logger.info("Alexa: proxy-login cookie committed to new broker", { meta: {
+			brokerId: entry.id,
+			name: input.name
+		} });
+		return { brokerId: entry.id };
+	}
 	async cascadeRemoveDevicesForBroker(brokerId) {
 		const reg = this.ctx.kernel.deviceRegistry;
 		const devices = this.ctx.kernel.devices;
@@ -67319,6 +67955,24 @@ var AlexaImportAddon = class extends BaseDeviceProvider {
 				label: "Accounts are managed separately",
 				content: "This integration links to an Amazon Alexa account broker. Add, edit, or remove accounts from External systems → Brokers, then adopt the imported devices. The integration only stores a reference to its broker. NOTE: this is an unofficial integration that Amazon can change or break without notice."
 			}]
+		}, {
+			id: "alexa-proxy-login",
+			title: "Interactive login (proxy)",
+			description: "The \"Login to Amazon\" button in onboarding opens a local proxy that captures the cookie after you complete the real Amazon login (incl. 2FA). Because Amazon URLs are rewritten to this exact host:port, it must be a directly-reachable address — leave the host blank to auto-detect the server IP, and make sure the port is reachable from the browser you log in from.",
+			columns: 2,
+			fields: [{
+				type: "text",
+				key: "proxyLogin.proxyHost",
+				label: "Login proxy host/IP (blank = auto-detect)",
+				placeholder: "auto-detect"
+			}, {
+				type: "number",
+				key: "proxyLogin.proxyPort",
+				label: "Login proxy port",
+				min: 1,
+				max: 65535,
+				default: 3456
+			}]
 		}] });
 	}
 	async supportsManualCreation() {
@@ -67353,4 +68007,4 @@ function capsEqual(a, b) {
 	return true;
 }
 //#endregion
-export { AlexaImportAddon, alexaConnectionSchema as a, settingsToAlexaConnection as c, StubAlexaClient as d, createAlexaClient as f, alexaAddonConfigSchema as i, AlexaAuthError as l, mappableAppliance as n, buildConnectionFormSchema as o, mapAlexaCapabilitiesToCamStack as r, connectionToCredentials as s, buildAlexaApplianceCandidate as t, AlexaClientNotWiredError as u };
+export { AlexaImportAddon, AlexaClientNotWiredError as a, alexaAddonConfigSchema as c, connectionToCredentials as d, settingsToAlexaConnection as f, AlexaAuthError as i, alexaConnectionSchema as l, mappableAppliance as n, StubAlexaClient as o, mapAlexaCapabilitiesToCamStack as r, createAlexaClient as s, buildAlexaApplianceCandidate as t, buildConnectionFormSchema as u };