@camstack/system 1.2.66 → 1.2.68

package/dist/builtins/snapshot/index.js

@@ -3,7 +3,10 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CIkGOAcz.js");
+const require_dist = require("../../dist-Dhpte164.js");
+let _camstack_types_node = require("@camstack/types/node");
+let zod = require("zod");
+let node_crypto = require("node:crypto");
 let node_child_process = require("node:child_process");
 //#region src/builtins/snapshot/snapshot-coalescing.ts
 /**
@@ -645,7 +648,146 @@ var SnapshotSubscriptions = class {
 	}
 };
 //#endregion
+//#region src/builtins/snapshot/snapshot-link-url.ts
+/**
+* Signed, expiring links to a CLIENT-SIZED snapshot frame.
+*
+* ## Why a link plane exists at all
+*
+* The authenticated `/addon/snapshot/media/<id>.jpg` plane works, and it is not
+* going away. What it cannot do is guarantee that a client asking for a tile
+* actually REACHES the server — and that turned out to be the whole bug.
+*
+* Under D93 the image URL is versioned by the frame identity, and an image
+* request is what enrols a camera in the keep-warm loop. Both halves are
+* satisfied by the client's own image cache: `expo-image` is URL-keyed and never
+* revalidates, so a URL the app painted in a previous session is served from
+* disk with **zero network**. Measured on the live hub, reopening the app after
+* two minutes idle painted 15 of 16 tiles from disk — frames **168 s old**, with
+* not one HTTP request, therefore not one enrolment, therefore nothing warming.
+* The operator's report ("gli snapshot sono vecchi, devo aggiornare più volte")
+* is that measurement.
+*
+* A minted link breaks the loop from both ends. It is produced by an RPC —
+* `snapshot.getSnapshotLinks` — which no image cache can answer, so the demand
+* signal always lands; and it carries the capture identity the RPC just WAITED
+* for, rather than one a cache-only poll happened to be holding.
+*
+* ## What is signed, and what is only a cache key
+*
+* The signature covers `"<deviceId>:<width>"` and the expiry. The width is
+* inside it deliberately: a leaked 240 px tile link must not be replayable as a
+* request for the full 4 K frame. `v` (the capture identity) is NOT signed — it
+* exists only to key the client's image cache, so an unchanged frame is a
+* byte-identical URL and costs no bytes, and a new frame is a new URL and costs
+* exactly one fetch.
+*
+* `exp` is bucketed rather than exact. A URL that were unique per mint would
+* defeat the client cache completely — correct for freshness, and it would make
+* a phone re-download every tile on every 5 s poll whether or not anything
+* changed. Bucketing means the URL moves when the FRAME moves, and otherwise at
+* most once per bucket.
+*
+* Pure and side-effect-free; the addon owns the secret and the clock. Unit
+* tested in `__tests__/snapshot-link-url.spec.ts`.
+*/
+/**
+* How long a minted link stays valid.
+*
+* A snapshot is a live view of the operator's home, so this is short on purpose
+* — the exposure of a leaked link is bounded by it. Two minutes is long enough
+* that a page renders, re-renders and survives a brief backgrounding on the URL
+* it was given, and short enough that a link pasted somewhere is dead before it
+* is useful. The client re-mints on every overview poll (5 s), so it never
+* depends on the tail of this window.
+*/
+var SNAPSHOT_LINK_TTL_MS = 12e4;
+/**
+* Quantum the expiry is rounded UP to, so a link is stable between mints.
+*
+* Without it every mint produces a different `exp`, hence a different URL, hence
+* a full re-download of an unchanged frame on every poll. With it the URL is a
+* pure function of (device, width, frame, bucket) — so a tile fetches when its
+* frame moves, and at most once more per bucket.
+*/
+var SNAPSHOT_LINK_EXP_BUCKET_MS = 3e4;
+/** The token the signature is computed over. Width is part of the identity so a
+*  tile link cannot be escalated into a full-frame request. */
+function snapshotLinkId(deviceId, width) {
+	return `${String(deviceId)}:${width === void 0 ? "full" : String(width)}`;
+}
+/** The bucketed expiry for a link minted at `nowMs`. Always ≥ `nowMs + TTL`. */
+function snapshotLinkExpiry(nowMs, ttlMs = SNAPSHOT_LINK_TTL_MS, bucketMs = SNAPSHOT_LINK_EXP_BUCKET_MS) {
+	return Math.ceil((nowMs + ttlMs) / bucketMs) * bucketMs;
+}
+/**
+* The link, as a ROOT-RELATIVE path.
+*
+* Deliberately not absolute. The artifact and HA planes must mint absolute URLs
+* because the fetcher is a phone or a notifier backend that has no idea where
+* the hub is — and picking that base is the `hubUrl: localhost` trap the Alexa
+* work paid for. Here the fetcher is a client that is already connected to the
+* hub and holds its own `serverUrl`, so the correct base is the one it used to
+* make the call. Returning a path makes it impossible to hand a client a link
+* pointing somewhere it cannot reach.
+*/
+function buildSnapshotLinkUrl(input) {
+	const base = (input.routePrefix.startsWith("/") ? input.routePrefix : `/${input.routePrefix}`).replace(/\/+$/, "");
+	const id = snapshotLinkId(input.deviceId, input.width);
+	const sig = (0, _camstack_types_node.signExpiringUrl)(input.secret, id, input.expMs);
+	const params = new URLSearchParams();
+	if (input.width !== void 0) params.set("w", String(input.width));
+	if (input.capturedAt !== null) params.set("v", String(input.capturedAt));
+	params.set("exp", String(input.expMs));
+	params.set("sig", sig);
+	return `${base}/${String(input.deviceId)}.jpg?${params.toString()}`;
+}
+/**
+* Parse and VERIFY a link request in one step, so a caller cannot accidentally
+* use the device id before checking the signature. Null = refuse (404/403);
+* there is deliberately no way to distinguish "bad signature" from "expired"
+* from "malformed" at this boundary, so a public route cannot be probed.
+*/
+function parseVerifiedSnapshotLink(input) {
+	const qIdx = input.url.indexOf("?");
+	const rawPath = qIdx === -1 ? input.url : input.url.slice(0, qIdx);
+	const query = qIdx === -1 ? "" : input.url.slice(qIdx + 1);
+	const segment = rawPath.replace(/^\/+/, "");
+	if (segment.length === 0 || segment.includes("/")) return null;
+	const idPart = segment.replace(/\.jpe?g$/i, "");
+	if (!/^\d+$/.test(idPart)) return null;
+	const deviceId = Number.parseInt(idPart, 10);
+	if (!Number.isSafeInteger(deviceId) || deviceId <= 0) return null;
+	const params = new URLSearchParams(query);
+	const rawWidth = params.get("w");
+	if (rawWidth !== null && !/^\d+$/.test(rawWidth)) return null;
+	const width = rawWidth === null ? void 0 : Number.parseInt(rawWidth, 10);
+	if (width !== void 0 && (!Number.isSafeInteger(width) || width <= 0)) return null;
+	return (0, _camstack_types_node.verifyExpiringUrl)({
+		secret: input.secret,
+		id: snapshotLinkId(deviceId, width),
+		exp: params.get("exp") ?? void 0,
+		sig: params.get("sig") ?? void 0,
+		nowMs: input.nowMs
+	}) ? {
+		deviceId,
+		width
+	} : null;
+}
+//#endregion
 //#region src/builtins/snapshot/snapshot.addon.ts
+/**
+* How long `getSnapshotLinks` waits for the capture it triggered before minting
+* the link over whatever frame it has.
+*
+* Sized against the paint budget, not against the slowest camera. A cold fleet
+* is paced by `MAX_CONCURRENT_GRABS`, so waiting for the last of sixteen would
+* hold the whole grid for tens of seconds — and the frame that lands late is not
+* lost, it populates the cache and the client's next 5 s poll picks it up. The
+* value matches `SWR_STALE_WAIT_MS`'s intent: long enough that a warm broker
+* answers inside it, short enough that a dead camera cannot stall the batch.
+*/
+var LINK_MINT_DEADLINE_MS = 2500;
 /** Default cache window for non-battery cams (seconds). 10s feels live. */
 var NON_BATTERY_DEFAULT_MAX_AGE_S = 10;
 /** Default cache window for battery cams (seconds). 1h ≈ "don't wake the cam unless asked". */
@@ -712,6 +854,17 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	*/
 	mediaDataPlane = null;
 	/**
+	* The PUBLIC, signature-authenticated twin of the media plane. Null when the
+	* host has no `ctx.dataPlane` facility, or before the per-install secret has
+	* been minted — in which case `getSnapshotLinks` reports `url: null` and the
+	* client keeps using the authenticated plane exactly as before.
+	*/
+	linkDataPlane = null;
+	/** Per-install HMAC secret for link signatures. Minted once and persisted: a
+	*  secret that rolled on every boot would invalidate every link a client is
+	*  currently holding, which is a fleet-wide blank grid after each restart. */
+	linkSecret = null;
+	/**
 	* Who is being looked at, inferred from data-plane traffic. The keep-warm
 	* loop's entire bound — see `snapshot-keep-warm.ts`.
 	*/
@@ -743,9 +896,11 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			getDeviceLiveContribution: async () => null,
 			applyDeviceSettingsPatch: (input) => this.saveDeviceSettingsPatch(input.deviceId, input.patch),
 			getStatus: async (input) => this.getStatus(input.deviceId),
-			getSnapshotOverview: (input) => this.getSnapshotOverview(input)
+			getSnapshotOverview: (input) => this.getSnapshotOverview(input),
+			getSnapshotLinks: (input) => this.getSnapshotLinks(input)
 		};
 		await this.serveMediaDataPlane();
+		await this.serveLinkDataPlane();
 		this.scheduleWarmTick();
 		return [{
 			capability: require_dist.snapshotCapability,
@@ -779,6 +934,184 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		}
 	}
 	/**
+	* Serve the PUBLIC link plane: `GET /addon/snapshot/link/<deviceId>.jpg?w&v&exp&sig`.
+	*
+	* `access: 'public'` is deliberate and is the only interesting decision here.
+	* The authority is the HMAC, exactly as for the notification artifact plane
+	* and the Home Assistant media plane — but unlike those, what sits behind it
+	* is a LIVE view of the operator's home, so the compensating choices are
+	* explicit: a short TTL (`SNAPSHOT_LINK_TTL_MS`), the width inside the signed
+	* identity so a leaked tile cannot be escalated to the full frame, and
+	* **`force` is not honoured on this route at all** — a public URL must never
+	* be able to wake a battery camera.
+	*
+	* A leaked link therefore grants: one camera, at one thumbnail width, for at
+	* most the TTL. No token, no other device, no session.
+	*/
+	async serveLinkDataPlane() {
+		try {
+			const secret = await this.ensureLinkSecret();
+			if (secret === null) return;
+			const prefix = this.linkRoutePrefix();
+			const handler = createSnapshotMediaHandler({
+				getMedia: (deviceId, streamId, _force, width) => this.resolveSnapshotMedia(deviceId, streamId, false, width),
+				peekFresh: (deviceId, streamId) => this.peekFreshFrame(deviceId, streamId)
+			});
+			this.linkDataPlane = await this.ctx.dataPlane?.serve({
+				prefix: "link",
+				access: "public",
+				handler: (req, res) => this.handleLinkRequest(req, res, secret, handler)
+			}) ?? null;
+			this.ctx.logger.info("snapshot link data-plane served", { meta: {
+				served: this.linkDataPlane !== null,
+				prefix
+			} });
+		} catch (err) {
+			this.ctx.logger.warn("snapshot link data-plane failed to serve", { meta: { error: require_dist.errMsg(err) } });
+			this.linkDataPlane = null;
+		}
+	}
+	/**
+	* Verify first, then hand the request to the ordinary media handler with a
+	* REWRITTEN url carrying only the signed `(deviceId, width)`.
+	*
+	* Rewriting rather than passing the original through is what stops an unsigned
+	* query parameter reaching the capture path: `force`, `streamId` and any other
+	* lever the authenticated plane honours are simply not present in what the
+	* handler parses.
+	*/
+	async handleLinkRequest(req, res, secret, inner) {
+		const verified = parseVerifiedSnapshotLink({
+			url: req.url ?? "/",
+			secret,
+			nowMs: Date.now()
+		});
+		if (verified === null) {
+			res.writeHead(404).end();
+			return;
+		}
+		const rewritten = `/${String(verified.deviceId)}.jpg${verified.width === void 0 ? "" : `?w=${String(verified.width)}`}`;
+		const original = req.url;
+		try {
+			req.url = rewritten;
+			await inner(req, res);
+		} finally {
+			req.url = original;
+		}
+	}
+	linkRoutePrefix() {
+		return `/addon/${require_dist.bareAddonId(this.ctx.id)}/link`;
+	}
+	/** Mint-once-and-persist the signing secret. Null if it cannot be stored — a
+	*  secret held only in memory would break every outstanding link on restart,
+	*  so no plane is better than a plane whose links die unpredictably. */
+	async ensureLinkSecret() {
+		if (this.linkSecret !== null) return this.linkSecret;
+		try {
+			const state = this.state("snapshotLinkSecret", zod.z.string(), "");
+			let secret = await state.get();
+			if (secret === "") {
+				secret = (0, node_crypto.randomUUID)().replace(/-/g, "");
+				await state.set(secret);
+			}
+			this.linkSecret = secret;
+			return secret;
+		} catch (err) {
+			this.ctx.logger.warn("snapshot: could not establish link signing secret", { meta: { error: require_dist.errMsg(err) } });
+			return null;
+		}
+	}
+	/**
+	* Mint signed links for the tiles a surface is rendering — and, in the same
+	* call, make those tiles CURRENT.
+	*
+	* This is the demand signal the design was missing. Under D93 enrolment rode
+	* on the image request, and D93/D94/D95 each fixed a different way for that
+	* request not to happen; none of them could fix the last one, because the
+	* client's own image cache answers a repeated URL with no network at all. An
+	* RPC has no such cache in front of it.
+	*
+	* So: note every target (creating a subscription, which `getSnapshotOverview`
+	* deliberately cannot), then join the ordinary non-forced capture path and
+	* wait a BOUNDED time for it. What comes back is the identity of the frame the
+	* link will actually serve.
+	*
+	* The bound matters more than its exact value. A cold fleet is paced by
+	* `MAX_CONCURRENT_GRABS`, so sixteen cameras cannot all capture at once and
+	* the last of them would hold the whole batch well past any sensible paint
+	* budget. Devices that miss the bound return their real, older `capturedAt` —
+	* honest rather than blocking — and the client's next poll carries them
+	* forward.
+	*/
+	async getSnapshotLinks(input) {
+		const secret = await this.ensureLinkSecret();
+		const now = Date.now();
+		const expMs = snapshotLinkExpiry(now, SNAPSHOT_LINK_TTL_MS);
+		const served = this.linkDataPlane !== null && secret !== null;
+		const prefix = this.linkRoutePrefix();
+		const rows = await Promise.all(input.targets.map(async (target) => {
+			const { deviceId } = target;
+			const width = target.width === void 0 ? void 0 : snapSnapshotWidth(target.width);
+			this.subscriptions.note(deviceId, void 0, width, now);
+			const sleeping = await this.isSleepingBatteryDevice(deviceId);
+			if (!sleeping) await this.awaitFreshEnough(deviceId);
+			const capturedAt = this.cache.latest(deviceId)?.ts ?? null;
+			const answeredAt = Date.now();
+			return {
+				deviceId,
+				url: served && secret !== null ? buildSnapshotLinkUrl({
+					routePrefix: prefix,
+					deviceId,
+					width,
+					capturedAt,
+					secret,
+					expMs
+				}) : null,
+				capturedAt,
+				ageMs: capturedAt === null ? null : answeredAt - capturedAt,
+				expiresAt: served ? expMs : null,
+				width: width ?? null,
+				neverCaptured: capturedAt === null,
+				sleeping
+			};
+		}));
+		this.ctx.logger.debug("snapshot: minted links", { meta: {
+			targets: input.targets.length,
+			served,
+			stale: rows.filter((r) => r.ageMs !== null && r.ageMs > 15e3).length
+		} });
+		return rows;
+	}
+	/**
+	* Join the ordinary capture path for one device and wait, bounded, for it.
+	*
+	* Deliberately `getSnapshot` with `force: false` and nothing else: every gate
+	* that already owns this decision — the per-device max-age, the single flight,
+	* the grab pool, the sleeping-battery refusal — applies unchanged. A fresh
+	* cache returns immediately; a stale one starts the refresh. There is no
+	* second freshness policy here, which is the mistake D93 called out.
+	*/
+	async awaitFreshEnough(deviceId) {
+		if (!(await raceForResult(this.getSnapshot({
+			deviceId,
+			force: false
+		}).catch(() => null), LINK_MINT_DEADLINE_MS)).settled) this.ctx.logger.debug("snapshot: link mint gave up waiting; serving the older frame", {
+			tags: { deviceId },
+			meta: { deadlineMs: LINK_MINT_DEADLINE_MS }
+		});
+	}
+	/** True only for a BATTERY device that is currently asleep. Kept as one
+	*  question so the link path cannot accidentally treat "battery" as "asleep"
+	*  and stop refreshing a camera that is awake and streaming. */
+	async isSleepingBatteryDevice(deviceId) {
+		try {
+			if ((await this.lookupDeviceMeta(deviceId))?.isBattery !== true) return false;
+			return await this.isDeviceSleeping(deviceId);
+		} catch {
+			return false;
+		}
+	}
+	/**
 	* Resolve a device (+ optional stream, + force) to renderable JPEG bytes for
 	* the HTTP endpoint. Runs the same coalesced capture ladder as the tRPC
 	* `getSnapshot` (so every consumer shares one upstream pull), then decodes the
@@ -975,6 +1308,10 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			await this.mediaDataPlane.dispose().catch(() => void 0);
 			this.mediaDataPlane = null;
 		}
+		if (this.linkDataPlane) {
+			await this.linkDataPlane.dispose().catch(() => void 0);
+			this.linkDataPlane = null;
+		}
 		this.cache.clear();
 		this.variants.clear();
 		this.captureFlight.clear();