@camstack/types 1.2.51 → 1.2.53

package/dist/interfaces/adoption-job.d.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+/**
+ * Adoption job — the background form of `device-adoption.adopt`.
+ *
+ * ## Why this exists
+ *
+ * `adopt({childNativeIds: [...]})` materialises one CamStack device per
+ * candidate PLUS every accessory child, and the whole array shares ONE UDS
+ * request deadline (60s). Measured on the live hub against Home Assistant:
+ * each device the kernel creates costs ~450 ms — `devices.create` pre-seeds
+ * meta with up to eleven SEQUENTIAL round trips (`setName`, `setType`,
+ * `setRole`, … `persistConfig`) before the class is constructed — and an
+ * accessory child costs the same as its parent. So the real unit of work is
+ * the CHILD, not the candidate:
+ *
+ * - 25 candidates averaging 6 children  → ~150 devices → **>60s, times out**
+ * - ONE candidate with 217 children     → ~217 devices → **>60s, times out**
+ *
+ * That second line is why this is a job and not a smaller batch. No chunking,
+ * no bounded concurrency over candidates and no per-call tuning can fix a
+ * shape where **N=1 already exceeds the deadline** — the count that blows the
+ * budget is the source system's accessory fan-out, which the operator does not
+ * choose and cannot see. A design that only works below some N is the same bug
+ * deferred.
+ *
+ * ## What the timeout did NOT do
+ *
+ * It did not stop the work. The UDS deadline ends the CALLER's wait; the
+ * provider's loop runs to completion. Measured: a 25-candidate adopt that
+ * "failed" at 60s had adopted 17 by 87s and all 25 by ~130s. The operator saw
+ * an error and had no way to learn that. Every field below exists so that
+ * question has an answer.
+ *
+ * ## Idempotency
+ *
+ * Jobs are in-RAM; a restart forgets them. That is safe here because adoption
+ * is keyed by a stable id (`ha:<broker>:dev:<nativeId>` and equivalents), so
+ * re-running a job re-adopts nothing: an already-adopted candidate is SKIPPED
+ * by the engine before any provider call and lands in `alreadyAdopted`. It is
+ * never a duplicate device, and never an error the operator has to interpret.
+ */
+export declare const AdoptionJobStateSchema: z.ZodEnum<{
+    done: "done";
+    failed: "failed";
+    running: "running";
+    cancelled: "cancelled";
+}>;
+export type AdoptionJobState = z.infer<typeof AdoptionJobStateSchema>;
+/**
+ * Per-candidate result. Every candidate the job was asked to adopt ends in
+ * exactly one of these buckets — there is no silent drop, and the operator can
+ * always answer "which of my 25 landed?".
+ *
+ * - `adopted` — created now by this job.
+ * - `already-adopted` — a device for this candidate existed before the job
+ *   reached it (a re-run, or a retry after a timeout). Not an error.
+ * - `failed` — the provider threw; `error` carries the message.
+ * - `cancelled` — the operator cancelled before this candidate was reached.
+ */
+export declare const AdoptionOutcomeSchema: z.ZodEnum<{
+    failed: "failed";
+    cancelled: "cancelled";
+    adopted: "adopted";
+    "already-adopted": "already-adopted";
+}>;
+export type AdoptionOutcome = z.infer<typeof AdoptionOutcomeSchema>;
+export declare const AdoptionCandidateResultSchema: z.ZodObject<{
+    childNativeId: z.ZodString;
+    outcome: z.ZodEnum<{
+        failed: "failed";
+        cancelled: "cancelled";
+        adopted: "adopted";
+        "already-adopted": "already-adopted";
+    }>;
+    parentDeviceId: z.ZodNullable<z.ZodNumber>;
+    accessoryCount: z.ZodNumber;
+    error: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AdoptionCandidateResult = z.infer<typeof AdoptionCandidateResultSchema>;
+export declare const AdoptionJobSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    addonId: z.ZodString;
+    integrationId: z.ZodString;
+    state: z.ZodEnum<{
+        done: "done";
+        failed: "failed";
+        running: "running";
+        cancelled: "cancelled";
+    }>;
+    total: z.ZodNumber;
+    processed: z.ZodNumber;
+    adopted: z.ZodNumber;
+    alreadyAdopted: z.ZodNumber;
+    failed: z.ZodNumber;
+    accessoriesCreated: z.ZodNumber;
+    currentChildNativeId: z.ZodNullable<z.ZodString>;
+    results: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        childNativeId: z.ZodString;
+        outcome: z.ZodEnum<{
+            failed: "failed";
+            cancelled: "cancelled";
+            adopted: "adopted";
+            "already-adopted": "already-adopted";
+        }>;
+        parentDeviceId: z.ZodNullable<z.ZodNumber>;
+        accessoryCount: z.ZodNumber;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+    startedAt: z.ZodNumber;
+    finishedAt: z.ZodNullable<z.ZodNumber>;
+    error: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AdoptionJob = z.infer<typeof AdoptionJobSchema>;

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