@camstack/types 1.2.51 → 1.2.52

package/dist/addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_event_category = require("./event-category-BE4PDZ_3.js");
-const require_sleep = require("./sleep-ocMLM2o5.js");
+const require_sleep = require("./sleep-DfF6vKCf.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 //#region src/generated/collection-array-methods.ts
 /**

package/dist/addon.mjs

@@ -1,5 +1,5 @@
 import { t as EventCategory } from "./event-category-41fKf-q9.mjs";
-import { C as DeviceType, F as readNodePin, L as ReadinessRegistry, O as expandCapMethods, P as nodePin, R as ReadinessTimeoutError, V as scopeKey, a as asJsonObject, d as DEVICE_SCOPED_CAPS, f as isDeviceScopedCap, gt as normalizeAddonInitResult, ht as BaseAddon, mt as DisposerChain, p as createDeviceProxy, pt as DATAPLANE_SECRET_HEADER, s as asString, t as sleep, u as parseJsonUnknown, v as deviceOpsCapability, w as adminUiCapability, y as viewerUiCapability, yt as emitReadiness } from "./sleep-7WqNZVcL.mjs";
+import { C as DeviceType, F as readNodePin, L as ReadinessRegistry, O as expandCapMethods, P as nodePin, R as ReadinessTimeoutError, V as scopeKey, a as asJsonObject, d as DEVICE_SCOPED_CAPS, f as isDeviceScopedCap, gt as normalizeAddonInitResult, ht as BaseAddon, mt as DisposerChain, p as createDeviceProxy, pt as DATAPLANE_SECRET_HEADER, s as asString, t as sleep, u as parseJsonUnknown, v as deviceOpsCapability, w as adminUiCapability, y as viewerUiCapability, yt as emitReadiness } from "./sleep-CT4lN1ij.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 //#region src/generated/collection-array-methods.ts
 /**

package/dist/capabilities/snapshot.cap.d.ts

@@ -82,6 +82,62 @@ export declare const snapshotCapability: {
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind> & {
             readonly systemOnly: true;
         };
+        /**
+         * Signed, expiring links to a CLIENT-SIZED frame — and the demand signal
+         * that makes those frames current.
+         *
+         * ## The problem it replaces
+         *
+         * `getSnapshotOverview` is cache-only by contract: it answers from whatever
+         * the wrapper happens to hold and never captures. Under D93 the client
+         * versions its image URL on that answer, and an image REQUEST is what enrols
+         * a camera in the keep-warm loop. Both of those are satisfiable by the
+         * client's own image cache — `expo-image` is URL-keyed and never revalidates
+         * — so a URL painted in a previous session comes off disk with no network,
+         * no enrolment, and nothing warming. Measured on the live hub: reopening
+         * after two minutes idle painted 15 of 16 tiles at **168 s old** with zero
+         * HTTP requests, and the fleet only recovered because a later poll happened
+         * to observe a different identity.
+         *
+         * ## The two properties that fix it
+         *
+         * **It is an RPC, so no client cache can answer it.** The demand signal
+         * always reaches the wrapper. This method therefore MAY create keep-warm
+         * subscriptions, where `getSnapshotOverview` must never (D93) — the
+         * distinction is not "one is newer" but that the overview poll is app-wide
+         * (a creating overview would warm every camera on the install) while this is
+         * called by a rendered surface naming the tiles it is actually painting, at
+         * the width it is painting them.
+         *
+         * **It waits, briefly and boundedly, for the capture it triggered.** The
+         * returned `capturedAt` is the frame the link will serve, not the frame the
+         * cache held when the client asked, so a first paint is honest and current
+         * instead of a generation behind. A device that does not settle inside the
+         * bound still gets a link and its real (older) `capturedAt` — the next poll
+         * carries it forward.
+         *
+         * `force` is never set on behalf of a client here. A sleeping battery camera
+         * is reported with `sleeping: true` and the last frame it produced, however
+         * old; the wrapper's existing sleep gate owns that decision and this method
+         * adds no second one.
+         */
+        readonly getSnapshotLinks: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            targets: z.ZodArray<z.ZodObject<{
+                deviceId: z.ZodNumber;
+                width: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            url: z.ZodNullable<z.ZodString>;
+            capturedAt: z.ZodNullable<z.ZodNumber>;
+            ageMs: z.ZodNullable<z.ZodNumber>;
+            expiresAt: z.ZodNullable<z.ZodNumber>;
+            width: z.ZodNullable<z.ZodNumber>;
+            neverCaptured: z.ZodBoolean;
+            sleeping: z.ZodBoolean;
+        }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind> & {
+            readonly systemOnly: true;
+        };
     };
     readonly status: {
         readonly schema: z.ZodObject<{

package/dist/generated/addon-api.d.ts

@@ -6575,6 +6575,13 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof snapshotCapability.methods.getSnapshotOverview.output>;
             meta: object;
         }>;
+        getSnapshotLinks: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof snapshotCapability.methods.getSnapshotLinks.input>;
+            output: z.infer<typeof snapshotCapability.methods.getSnapshotLinks.output>;
+            meta: object;
+        }>;
     }>>;
     ssoBridge: TRPCBuiltRouter<{
         ctx: TrpcContext;

package/dist/generated/method-access-map.d.ts

@@ -6,7 +6,7 @@
  * scope+access check inside `protectedProcedure` (see
  * `server/backend/src/api/trpc/trpc.middleware.ts`).
  *
- * Coverage: 900 method paths across 121 capabilities.
+ * Coverage: 901 method paths across 121 capabilities.
  */
 import type { CapabilityMethodAccess } from '../capabilities/capability-definition.js';
 export interface MethodAccessRecord {

package/dist/index.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_event_category = require("./event-category-BE4PDZ_3.js");
-const require_sleep = require("./sleep-ocMLM2o5.js");
+const require_sleep = require("./sleep-DfF6vKCf.js");
 const require_canonical_hash = require("./canonical-hash-DNV8S5ET.js");
 const require_enums = require("./enums.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
@@ -17308,6 +17308,77 @@ var snapshotCapability = {
 			lastCapturedAt: zod.z.number().nullable(),
 			cacheAgeMs: zod.z.number().nullable(),
 			etag: zod.z.string().nullable()
+		}))),
+		/**
+		* Signed, expiring links to a CLIENT-SIZED frame — and the demand signal
+		* that makes those frames current.
+		*
+		* ## The problem it replaces
+		*
+		* `getSnapshotOverview` is cache-only by contract: it answers from whatever
+		* the wrapper happens to hold and never captures. Under D93 the client
+		* versions its image URL on that answer, and an image REQUEST is what enrols
+		* a camera in the keep-warm loop. Both of those are satisfiable by the
+		* client's own image cache — `expo-image` is URL-keyed and never revalidates
+		* — so a URL painted in a previous session comes off disk with no network,
+		* no enrolment, and nothing warming. Measured on the live hub: reopening
+		* after two minutes idle painted 15 of 16 tiles at **168 s old** with zero
+		* HTTP requests, and the fleet only recovered because a later poll happened
+		* to observe a different identity.
+		*
+		* ## The two properties that fix it
+		*
+		* **It is an RPC, so no client cache can answer it.** The demand signal
+		* always reaches the wrapper. This method therefore MAY create keep-warm
+		* subscriptions, where `getSnapshotOverview` must never (D93) — the
+		* distinction is not "one is newer" but that the overview poll is app-wide
+		* (a creating overview would warm every camera on the install) while this is
+		* called by a rendered surface naming the tiles it is actually painting, at
+		* the width it is painting them.
+		*
+		* **It waits, briefly and boundedly, for the capture it triggered.** The
+		* returned `capturedAt` is the frame the link will serve, not the frame the
+		* cache held when the client asked, so a first paint is honest and current
+		* instead of a generation behind. A device that does not settle inside the
+		* bound still gets a link and its real (older) `capturedAt` — the next poll
+		* carries it forward.
+		*
+		* `force` is never set on behalf of a client here. A sleeping battery camera
+		* is reported with `sleeping: true` and the last frame it produced, however
+		* old; the wrapper's existing sleep gate owns that decision and this method
+		* adds no second one.
+		*/
+		getSnapshotLinks: require_sleep.systemMethod(zod.z.object({ 
+		/** The tiles a surface is actually rendering. One entry per (device,
+		*  width) the caller will paint — the width is snapped to the server's
+		*  ladder and becomes part of the link's SIGNED identity. */
+targets: zod.z.array(zod.z.object({
+			deviceId: zod.z.number(),
+			/** Target width in px. Omit for the frame as captured — correct
+			*  for a full-bleed surface, wrong (and expensive) for a grid. */
+			width: zod.z.number().int().positive().optional()
+		})).min(1).max(200) }), zod.z.array(zod.z.object({
+			deviceId: zod.z.number(),
+			/** Root-relative signed path, or null when the link plane is not
+			*  served (no data-plane facility). Present even for a device that has
+			*  never captured — the request is what triggers the first one (D94). */
+			url: zod.z.string().nullable(),
+			/** Epoch ms of the frame this link serves. Null = never captured.
+			*  THE honest age: the tRPC path carried none before this. */
+			capturedAt: zod.z.number().nullable(),
+			/** Age of that frame at the moment the answer was built. */
+			ageMs: zod.z.number().nullable(),
+			/** Epoch ms after which `url` stops verifying. */
+			expiresAt: zod.z.number().nullable(),
+			/** Ladder rung the bytes are at; null = the frame as captured. */
+			width: zod.z.number().nullable(),
+			/** The device has never produced a frame. An empty state, not a
+			*  failure — and never a reason to withhold the link (D94). */
+			neverCaptured: zod.z.boolean(),
+			/** A sleeping battery camera: the frame is deliberately stale and will
+			*  NOT refresh in the background. A surface should say so rather than
+			*  present it as current. */
+			sleeping: zod.z.boolean()
 		})))
 	},
 	status: {
@@ -34981,6 +35052,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"snapshot.getSnapshotLinks": {
+		capName: "snapshot",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"snapshot.getSnapshotOverview": {
 		capName: "snapshot",
 		capScope: "device",

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { t as EventCategory } from "./event-category-41fKf-q9.mjs";
-import { $ as FrameHandleSchema, A as method, B as readinessKey, C as DeviceType, Ct as collectHydratedFieldEntries, D as event, E as DEVICE_STATUS_METHOD, Et as resolveHydratedFieldValue, F as readNodePin, G as CamProfileSchema, H as BrokerStatsSchema, I as toNodeId, J as CameraStreamSchema, K as CamStreamKindSchema, L as ReadinessRegistry, M as systemMethod, N as CAP_NODE_PIN_CONTEXT_KEY, O as expandCapMethods, P as nodePin, Q as FrameHandleFormatSchema, R as ReadinessTimeoutError, S as DeviceRole, St as WELL_KNOWN_TAB_MAP, T as DEVICE_SETTINGS_CONTRIBUTION_METHODS, Tt as hydrateSchema, U as BrokerStatusSchema, V as scopeKey, W as CAM_PROFILE_ORDER, X as DecodedFrameSchema, Y as DecodedAudioChunkSchema, Z as EncodedPacketSchema, _ as RawStateResultSchema, _t as createDurableState, a as asJsonObject, at as SubscribeAudioChunksInputSchema, b as ChargingStatus, bt as isEvent, c as parseJsonArray, ct as SubscribeFramesResultSchema, d as DEVICE_SCOPED_CAPS, dt as parseProfileBrokerId, et as ProfileRtspEntrySchema, f as isDeviceScopedCap, ft as selectAssignedProfileSlots, g as createSliceHandle, gt as normalizeAddonInitResult, h as createMirrorSource, ht as BaseAddon, i as asJsonArray, it as StreamSourceSchema, j as resolveCapMount, k as isDeviceConfigCap, l as parseJsonObject, lt as makeProfileBrokerId, m as createLazyTrpcSource, mt as DisposerChain, n as sleepCancellable, nt as ProfileSlotStatusSchema, o as asNumber, ot as SubscribeAudioChunksResultSchema, p as createDeviceProxy, pt as DATAPLANE_SECRET_HEADER, q as CamStreamResolutionSchema, r as asBoolean, rt as StreamSourceEntrySchema, s as asString, st as SubscribeFramesInputSchema, t as sleep, tt as ProfileSlotSchema, u as parseJsonUnknown, ut as makeSourceBrokerId, v as deviceOpsCapability, vt as createEvent, w as adminUiCapability, wt as collectHydratedFieldValues, x as DeviceFeature, xt as WELL_KNOWN_TABS, y as viewerUiCapability, yt as emitReadiness, z as emitDownForOwnedCaps } from "./sleep-7WqNZVcL.mjs";
+import { $ as FrameHandleSchema, A as method, B as readinessKey, C as DeviceType, Ct as collectHydratedFieldEntries, D as event, E as DEVICE_STATUS_METHOD, Et as resolveHydratedFieldValue, F as readNodePin, G as CamProfileSchema, H as BrokerStatsSchema, I as toNodeId, J as CameraStreamSchema, K as CamStreamKindSchema, L as ReadinessRegistry, M as systemMethod, N as CAP_NODE_PIN_CONTEXT_KEY, O as expandCapMethods, P as nodePin, Q as FrameHandleFormatSchema, R as ReadinessTimeoutError, S as DeviceRole, St as WELL_KNOWN_TAB_MAP, T as DEVICE_SETTINGS_CONTRIBUTION_METHODS, Tt as hydrateSchema, U as BrokerStatusSchema, V as scopeKey, W as CAM_PROFILE_ORDER, X as DecodedFrameSchema, Y as DecodedAudioChunkSchema, Z as EncodedPacketSchema, _ as RawStateResultSchema, _t as createDurableState, a as asJsonObject, at as SubscribeAudioChunksInputSchema, b as ChargingStatus, bt as isEvent, c as parseJsonArray, ct as SubscribeFramesResultSchema, d as DEVICE_SCOPED_CAPS, dt as parseProfileBrokerId, et as ProfileRtspEntrySchema, f as isDeviceScopedCap, ft as selectAssignedProfileSlots, g as createSliceHandle, gt as normalizeAddonInitResult, h as createMirrorSource, ht as BaseAddon, i as asJsonArray, it as StreamSourceSchema, j as resolveCapMount, k as isDeviceConfigCap, l as parseJsonObject, lt as makeProfileBrokerId, m as createLazyTrpcSource, mt as DisposerChain, n as sleepCancellable, nt as ProfileSlotStatusSchema, o as asNumber, ot as SubscribeAudioChunksResultSchema, p as createDeviceProxy, pt as DATAPLANE_SECRET_HEADER, q as CamStreamResolutionSchema, r as asBoolean, rt as StreamSourceEntrySchema, s as asString, st as SubscribeFramesInputSchema, t as sleep, tt as ProfileSlotSchema, u as parseJsonUnknown, ut as makeSourceBrokerId, v as deviceOpsCapability, vt as createEvent, w as adminUiCapability, wt as collectHydratedFieldValues, x as DeviceFeature, xt as WELL_KNOWN_TABS, y as viewerUiCapability, yt as emitReadiness, z as emitDownForOwnedCaps } from "./sleep-CT4lN1ij.mjs";
 import { a as buildAudioArgs, c as buildVideoArgs, d as logBannerArgs, f as pickVideoEncoder, i as audioPlanFromEncodeProfile, l as invocationFromEncodeProfile, n as Fmp4BoxSplitter, o as buildFfmpegArgs, r as AUDIO_PRESETS, s as buildInputArgs, t as canonicalHash, u as isSoftwareDecode } from "./canonical-hash-rO1sRmEK.mjs";
 import { EventSourceType } from "./enums.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
@@ -17307,6 +17307,77 @@ var snapshotCapability = {
 			lastCapturedAt: z.number().nullable(),
 			cacheAgeMs: z.number().nullable(),
 			etag: z.string().nullable()
+		}))),
+		/**
+		* Signed, expiring links to a CLIENT-SIZED frame — and the demand signal
+		* that makes those frames current.
+		*
+		* ## The problem it replaces
+		*
+		* `getSnapshotOverview` is cache-only by contract: it answers from whatever
+		* the wrapper happens to hold and never captures. Under D93 the client
+		* versions its image URL on that answer, and an image REQUEST is what enrols
+		* a camera in the keep-warm loop. Both of those are satisfiable by the
+		* client's own image cache — `expo-image` is URL-keyed and never revalidates
+		* — so a URL painted in a previous session comes off disk with no network,
+		* no enrolment, and nothing warming. Measured on the live hub: reopening
+		* after two minutes idle painted 15 of 16 tiles at **168 s old** with zero
+		* HTTP requests, and the fleet only recovered because a later poll happened
+		* to observe a different identity.
+		*
+		* ## The two properties that fix it
+		*
+		* **It is an RPC, so no client cache can answer it.** The demand signal
+		* always reaches the wrapper. This method therefore MAY create keep-warm
+		* subscriptions, where `getSnapshotOverview` must never (D93) — the
+		* distinction is not "one is newer" but that the overview poll is app-wide
+		* (a creating overview would warm every camera on the install) while this is
+		* called by a rendered surface naming the tiles it is actually painting, at
+		* the width it is painting them.
+		*
+		* **It waits, briefly and boundedly, for the capture it triggered.** The
+		* returned `capturedAt` is the frame the link will serve, not the frame the
+		* cache held when the client asked, so a first paint is honest and current
+		* instead of a generation behind. A device that does not settle inside the
+		* bound still gets a link and its real (older) `capturedAt` — the next poll
+		* carries it forward.
+		*
+		* `force` is never set on behalf of a client here. A sleeping battery camera
+		* is reported with `sleeping: true` and the last frame it produced, however
+		* old; the wrapper's existing sleep gate owns that decision and this method
+		* adds no second one.
+		*/
+		getSnapshotLinks: systemMethod(z.object({ 
+		/** The tiles a surface is actually rendering. One entry per (device,
+		*  width) the caller will paint — the width is snapped to the server's
+		*  ladder and becomes part of the link's SIGNED identity. */
+targets: z.array(z.object({
+			deviceId: z.number(),
+			/** Target width in px. Omit for the frame as captured — correct
+			*  for a full-bleed surface, wrong (and expensive) for a grid. */
+			width: z.number().int().positive().optional()
+		})).min(1).max(200) }), z.array(z.object({
+			deviceId: z.number(),
+			/** Root-relative signed path, or null when the link plane is not
+			*  served (no data-plane facility). Present even for a device that has
+			*  never captured — the request is what triggers the first one (D94). */
+			url: z.string().nullable(),
+			/** Epoch ms of the frame this link serves. Null = never captured.
+			*  THE honest age: the tRPC path carried none before this. */
+			capturedAt: z.number().nullable(),
+			/** Age of that frame at the moment the answer was built. */
+			ageMs: z.number().nullable(),
+			/** Epoch ms after which `url` stops verifying. */
+			expiresAt: z.number().nullable(),
+			/** Ladder rung the bytes are at; null = the frame as captured. */
+			width: z.number().nullable(),
+			/** The device has never produced a frame. An empty state, not a
+			*  failure — and never a reason to withhold the link (D94). */
+			neverCaptured: z.boolean(),
+			/** A sleeping battery camera: the frame is deliberately stale and will
+			*  NOT refresh in the background. A surface should say so rather than
+			*  present it as current. */
+			sleeping: z.boolean()
 		})))
 	},
 	status: {
@@ -34980,6 +35051,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"snapshot.getSnapshotLinks": {
+		capName: "snapshot",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"snapshot.getSnapshotOverview": {
 		capName: "snapshot",
 		capScope: "device",

package/dist/node.d.ts

@@ -4,6 +4,8 @@ export { ensureFfmpeg, getFfmpegDownloadUrl } from './deps/ffmpeg-downloader.js'
 export { ensurePython, installPythonPackages, installPythonRequirements, getPythonDownloadUrl, PYTHON_VERSION, } from './deps/python-downloader.js';
 export { FilesystemStorageProvider } from './storage/filesystem-storage-provider.js';
 export { canonicalHash } from './utils/canonical-hash.js';
+export { signExpiringUrl, verifyExpiringUrl } from './utils/expiring-url-signature.js';
+export type { VerifyExpiringUrlInput } from './utils/expiring-url-signature.js';
 export { canonicalDeviceFingerprint, diffExportTargets, resolveExportFingerprint, } from './utils/export-reconciler.js';
 export type { DeviceExportShape, ExportDelta, ExportTargetEntry, } from './utils/export-reconciler.js';
 export { FfmpegProcess } from './ffmpeg/process.js';

package/dist/node.js

@@ -601,6 +601,61 @@ var FilesystemStorageProvider = class {
 	}
 };
 //#endregion
+//#region src/utils/expiring-url-signature.ts
+/**
+* The ONE derivation of "a signed, expiring URL".
+*
+* This repo mints unguessable, self-expiring links in three places now — the
+* notification artifact plane, the Home Assistant media plane, and the snapshot
+* link plane. The first two grew independently and are byte-identical logic
+* (`hmac(secret, "<id>:<exp>")`, expiry checked before a constant-time compare),
+* each restating the crypto locally because **addons never import each other**.
+*
+* That reason is real, and the conclusion drawn from it was wrong. Two copies of
+* a signing scheme is how one of them quietly ends up with a different TTL, a
+* different compare, or a missing expiry check, and nothing fails until a link
+* that should have died keeps working. The fix is the same one D52 applies to
+* crop geometry: one derivation, in a place every addon may depend on. A
+* framework package is exactly that place — `@camstack/types/node`, off the root
+* entry because `node:crypto` must never be traversed by a browser bundler.
+*
+* What this module deliberately does NOT decide: the TTL, the base URL, the
+* shape of `id`, and the access level of the route. Those are per-plane policy
+* and each caller states them where a reader can see them.
+*/
+/**
+* The signature over `(id, expMs)`.
+*
+* `id` is whatever the plane uses to name the thing being served — an artifact
+* id, a track id, a `<deviceId>:<width>` pair. It is joined with `:` so a caller
+* must not put a `:` inside a field whose boundary matters; where a plane has
+* more than one field, it composes them itself and owns that ambiguity.
+*/
+function signExpiringUrl(secret, id, expMs) {
+	return (0, node_crypto.createHmac)("sha256", secret).update(`${id}:${String(expMs)}`).digest("hex");
+}
+/**
+* Verify a request's `(id, exp, sig)`.
+*
+* **Expiry is checked BEFORE the compare**, so an expired link is refused
+* whether or not its signature is valid — a leaked URL stops working on its own
+* and cannot be kept alive by holding a correct signature. The compare itself is
+* constant-time so a public route cannot be probed for the signature byte by
+* byte.
+*/
+function verifyExpiringUrl(input) {
+	const { secret, id, exp, sig, nowMs } = input;
+	if (exp === void 0 || sig === void 0) return false;
+	const expMs = typeof exp === "number" ? exp : Number(exp);
+	if (!Number.isFinite(expMs)) return false;
+	if (expMs <= nowMs) return false;
+	const expected = signExpiringUrl(secret, id, expMs);
+	const a = Buffer.from(expected, "utf8");
+	const b = Buffer.from(sig, "utf8");
+	if (a.length !== b.length) return false;
+	return (0, node_crypto.timingSafeEqual)(a, b);
+}
+//#endregion
 //#region src/utils/export-reconciler.ts
 /**
 * Compute the stable 64-char lowercase-hex fingerprint of a device's
@@ -1446,3 +1501,5 @@ exports.getPythonDownloadUrl = getPythonDownloadUrl;
 exports.installPythonPackages = installPythonPackages;
 exports.installPythonRequirements = installPythonRequirements;
 exports.resolveExportFingerprint = resolveExportFingerprint;
+exports.signExpiringUrl = signExpiringUrl;
+exports.verifyExpiringUrl = verifyExpiringUrl;

package/dist/node.mjs

@@ -1,6 +1,6 @@
 import { n as Fmp4BoxSplitter, o as buildFfmpegArgs, t as canonicalHash, u as isSoftwareDecode } from "./canonical-hash-rO1sRmEK.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import * as fs from "node:fs";
 import { chmodSync, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
@@ -578,6 +578,61 @@ var FilesystemStorageProvider = class {
 	}
 };
 //#endregion
+//#region src/utils/expiring-url-signature.ts
+/**
+* The ONE derivation of "a signed, expiring URL".
+*
+* This repo mints unguessable, self-expiring links in three places now — the
+* notification artifact plane, the Home Assistant media plane, and the snapshot
+* link plane. The first two grew independently and are byte-identical logic
+* (`hmac(secret, "<id>:<exp>")`, expiry checked before a constant-time compare),
+* each restating the crypto locally because **addons never import each other**.
+*
+* That reason is real, and the conclusion drawn from it was wrong. Two copies of
+* a signing scheme is how one of them quietly ends up with a different TTL, a
+* different compare, or a missing expiry check, and nothing fails until a link
+* that should have died keeps working. The fix is the same one D52 applies to
+* crop geometry: one derivation, in a place every addon may depend on. A
+* framework package is exactly that place — `@camstack/types/node`, off the root
+* entry because `node:crypto` must never be traversed by a browser bundler.
+*
+* What this module deliberately does NOT decide: the TTL, the base URL, the
+* shape of `id`, and the access level of the route. Those are per-plane policy
+* and each caller states them where a reader can see them.
+*/
+/**
+* The signature over `(id, expMs)`.
+*
+* `id` is whatever the plane uses to name the thing being served — an artifact
+* id, a track id, a `<deviceId>:<width>` pair. It is joined with `:` so a caller
+* must not put a `:` inside a field whose boundary matters; where a plane has
+* more than one field, it composes them itself and owns that ambiguity.
+*/
+function signExpiringUrl(secret, id, expMs) {
+	return createHmac("sha256", secret).update(`${id}:${String(expMs)}`).digest("hex");
+}
+/**
+* Verify a request's `(id, exp, sig)`.
+*
+* **Expiry is checked BEFORE the compare**, so an expired link is refused
+* whether or not its signature is valid — a leaked URL stops working on its own
+* and cannot be kept alive by holding a correct signature. The compare itself is
+* constant-time so a public route cannot be probed for the signature byte by
+* byte.
+*/
+function verifyExpiringUrl(input) {
+	const { secret, id, exp, sig, nowMs } = input;
+	if (exp === void 0 || sig === void 0) return false;
+	const expMs = typeof exp === "number" ? exp : Number(exp);
+	if (!Number.isFinite(expMs)) return false;
+	if (expMs <= nowMs) return false;
+	const expected = signExpiringUrl(secret, id, expMs);
+	const a = Buffer.from(expected, "utf8");
+	const b = Buffer.from(sig, "utf8");
+	if (a.length !== b.length) return false;
+	return timingSafeEqual(a, b);
+}
+//#endregion
 //#region src/utils/export-reconciler.ts
 /**
 * Compute the stable 64-char lowercase-hex fingerprint of a device's
@@ -1403,4 +1458,4 @@ var Fmp4FragmentChild = class {
 	}
 };
 //#endregion
-export { FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, resolveExportFingerprint };
+export { FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, resolveExportFingerprint, signExpiringUrl, verifyExpiringUrl };

package/dist/{sleep-7WqNZVcL.mjs → sleep-CT4lN1ij.mjs}

@@ -3279,6 +3279,7 @@ function createDeviceProxy(api, binding, opts) {
 			getSnapshot: (input) => dispatch("snapshot", "snapshot", "getSnapshot", "query", input),
 			invalidateCache: (input) => dispatch("snapshot", "snapshot", "invalidateCache", "mutation", input),
 			getSnapshotOverview: (input) => dispatch("snapshot", "snapshot", "getSnapshotOverview", "query", input),
+			getSnapshotLinks: (input) => dispatch("snapshot", "snapshot", "getSnapshotLinks", "query", input),
 			getStatus: (input) => dispatch("snapshot", "snapshot", "getStatus", "query", input),
 			getDeviceSettingsContribution: (input) => dispatch("snapshot", "snapshot", "getDeviceSettingsContribution", "query", input),
 			getDeviceLiveContribution: (input) => dispatch("snapshot", "snapshot", "getDeviceLiveContribution", "query", input),

package/dist/{sleep-ocMLM2o5.js → sleep-DfF6vKCf.js}

@@ -3279,6 +3279,7 @@ function createDeviceProxy(api, binding, opts) {
 			getSnapshot: (input) => dispatch("snapshot", "snapshot", "getSnapshot", "query", input),
 			invalidateCache: (input) => dispatch("snapshot", "snapshot", "invalidateCache", "mutation", input),
 			getSnapshotOverview: (input) => dispatch("snapshot", "snapshot", "getSnapshotOverview", "query", input),
+			getSnapshotLinks: (input) => dispatch("snapshot", "snapshot", "getSnapshotLinks", "query", input),
 			getStatus: (input) => dispatch("snapshot", "snapshot", "getStatus", "query", input),
 			getDeviceSettingsContribution: (input) => dispatch("snapshot", "snapshot", "getDeviceSettingsContribution", "query", input),
 			getDeviceLiveContribution: (input) => dispatch("snapshot", "snapshot", "getDeviceLiveContribution", "query", input),

package/dist/utils/expiring-url-signature.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The signature over `(id, expMs)`.
+ *
+ * `id` is whatever the plane uses to name the thing being served — an artifact
+ * id, a track id, a `<deviceId>:<width>` pair. It is joined with `:` so a caller
+ * must not put a `:` inside a field whose boundary matters; where a plane has
+ * more than one field, it composes them itself and owns that ambiguity.
+ */
+export declare function signExpiringUrl(secret: string, id: string, expMs: number): string;
+export interface VerifyExpiringUrlInput {
+    readonly secret: string;
+    readonly id: string;
+    /** Raw query value — a string off the wire, or already a number. */
+    readonly exp: string | number | undefined;
+    readonly sig: string | undefined;
+    readonly nowMs: number;
+}
+/**
+ * Verify a request's `(id, exp, sig)`.
+ *
+ * **Expiry is checked BEFORE the compare**, so an expired link is refused
+ * whether or not its signature is valid — a leaked URL stops working on its own
+ * and cannot be kept alive by holding a correct signature. The compare itself is
+ * constant-time so a public route cannot be probed for the signature byte by
+ * byte.
+ */
+export declare function verifyExpiringUrl(input: VerifyExpiringUrlInput): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.51",
+  "version": "1.2.52",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",