@camstack/types 1.2.50 → 1.2.52

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.50",
+  "version": "1.2.52",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",