tesla-fleet-api 0.4.0 → 0.5.0

package/dist/router/energysite.cjs

@@ -0,0 +1,65 @@
+const require_base = require("./base.cjs");
+// src/router/energysite.ts
+/** The `live_status` keys a local Powerwall owns. */
+const LOCAL_LIVE_STATUS_KEYS = [
+	"solar_power",
+	"energy_left",
+	"total_pack_energy",
+	"percentage_charged",
+	"battery_power",
+	"load_power",
+	"grid_power",
+	"generator_power",
+	"grid_status",
+	"island_status"
+];
+/** The `site_info` keys a local Powerwall owns. */
+const LOCAL_SITE_INFO_KEYS = ["backup_reserve_percent", "default_real_mode"];
+/**
+* Overlay `owned_keys` present in `local` onto a copy of `cloud`. Every other key
+* keeps its cloud value.
+*
+* A local `live_status` returns every cloud key, with `null` for the ones it
+* cannot serve, so presence cannot be the ownership test. A fixed owned-key set
+* overlays local readings without clobbering cloud values, and lets a local outage
+* fall back to the cloud value rather than to an unavailable one.
+*
+* A key overlays only when it is owned, present, and not null: null means "not
+* served this tick" and the cloud value is kept. Any other falsy value (`0`,
+* `false`, `""`) overlays, because a zero reading must win. `local` of null, a
+* failed poll, yields a copy of `cloud`.
+*/
+function merge_local_into_cloud(cloud, local, owned_keys) {
+	const merged = { ...cloud };
+	if (local == null) return merged;
+	for (const key of owned_keys) {
+		const value = local[key];
+		if (value !== void 0 && value !== null) merged[key] = value;
+	}
+	return merged;
+}
+/** Overlay a local `live_status` onto the cloud document. See {@link merge_local_into_cloud}. */
+function merge_live_status(cloud, local) {
+	return merge_local_into_cloud(cloud, local, LOCAL_LIVE_STATUS_KEYS);
+}
+/** Overlay a local `site_info` onto the cloud document. See {@link merge_local_into_cloud}. */
+function merge_site_info(cloud, local) {
+	return merge_local_into_cloud(cloud, local, LOCAL_SITE_INFO_KEYS);
+}
+var EnergySiteRouterBase = class extends require_base.Router {
+	/** The site id of the first backend that has one. */
+	get energy_site_id() {
+		return this._first_attribute("energy_site_id");
+	}
+	/** Logs `transport=lan` for the local primary. Cloud fallbacks keep `backend=`. */
+	_backend_field(backend) {
+		return backend === this.primary ? "transport=lan" : super._backend_field(backend);
+	}
+};
+const EnergySiteRouter = EnergySiteRouterBase;
+exports.EnergySiteRouter = EnergySiteRouter;
+exports.LOCAL_LIVE_STATUS_KEYS = LOCAL_LIVE_STATUS_KEYS;
+exports.LOCAL_SITE_INFO_KEYS = LOCAL_SITE_INFO_KEYS;
+exports.merge_live_status = merge_live_status;
+exports.merge_local_into_cloud = merge_local_into_cloud;
+exports.merge_site_info = merge_site_info;

package/dist/router/energysite.d.cts

@@ -0,0 +1,47 @@
+import { Backends, MemberOf, Routed, Router, RouterOptions } from "./base.cjs";
+/** The `live_status` keys a local Powerwall owns. */
+export declare const LOCAL_LIVE_STATUS_KEYS: readonly ["solar_power", "energy_left", "total_pack_energy", "percentage_charged", "battery_power", "load_power", "grid_power", "generator_power", "grid_status", "island_status"];
+/** The `site_info` keys a local Powerwall owns. */
+export declare const LOCAL_SITE_INFO_KEYS: readonly ["backup_reserve_percent", "default_real_mode"];
+/**
+ * Overlay `owned_keys` present in `local` onto a copy of `cloud`. Every other key
+ * keeps its cloud value.
+ *
+ * A local `live_status` returns every cloud key, with `null` for the ones it
+ * cannot serve, so presence cannot be the ownership test. A fixed owned-key set
+ * overlays local readings without clobbering cloud values, and lets a local outage
+ * fall back to the cloud value rather than to an unavailable one.
+ *
+ * A key overlays only when it is owned, present, and not null: null means "not
+ * served this tick" and the cloud value is kept. Any other falsy value (`0`,
+ * `false`, `""`) overlays, because a zero reading must win. `local` of null, a
+ * failed poll, yields a copy of `cloud`.
+ */
+export declare function merge_local_into_cloud<T extends object>(cloud: T, local: object | null, owned_keys: readonly string[]): T;
+/** Overlay a local `live_status` onto the cloud document. See {@link merge_local_into_cloud}. */
+export declare function merge_live_status<T extends object>(cloud: T, local: object | null): T;
+/** Overlay a local `site_info` onto the cloud document. See {@link merge_local_into_cloud}. */
+export declare function merge_site_info<T extends object>(cloud: T, local: object | null): T;
+declare class EnergySiteRouterBase<Bs extends Backends> extends Router<Bs> {
+  /** The site id of the first backend that has one. */
+  get energy_site_id(): MemberOf<Bs[number], "energy_site_id">;
+  /** Logs `transport=lan` for the local primary. Cloud fallbacks keep `backend=`. */
+  protected _backend_field(backend: object): string;
+}
+/**
+ * A router over energy sites: a local primary, such as `PowerwallEnergySite`,
+ * and one or more cloud fallbacks. See `Router` for dispatch, failover and the
+ * replay warning.
+ *
+ * There is no per-method list. A method the local backend omits goes straight to
+ * the cloud, and registration and discovery (`add_authorized_client`,
+ * `find_gateway_address`) belong on `router.secondary` directly. A local-only
+ * caller that must not fail over uses `router.primary`.
+ *
+ * A failed-over write can run twice. `operation`, `backup` and
+ * `grid_import_export` all write `config.json`, so do not split them across
+ * backends: one write would stomp the other.
+ */
+export type EnergySiteRouter<Bs extends Backends> = EnergySiteRouterBase<Bs> & Routed<Bs[number]>;
+export declare const EnergySiteRouter: new <const Bs extends Backends>(backends: Bs, options?: RouterOptions) => EnergySiteRouter<Bs>;
+export {};

package/dist/router/energysite.d.mts

@@ -0,0 +1,47 @@
+import { Backends, MemberOf, Routed, Router, RouterOptions } from "./base.mjs";
+/** The `live_status` keys a local Powerwall owns. */
+export declare const LOCAL_LIVE_STATUS_KEYS: readonly ["solar_power", "energy_left", "total_pack_energy", "percentage_charged", "battery_power", "load_power", "grid_power", "generator_power", "grid_status", "island_status"];
+/** The `site_info` keys a local Powerwall owns. */
+export declare const LOCAL_SITE_INFO_KEYS: readonly ["backup_reserve_percent", "default_real_mode"];
+/**
+ * Overlay `owned_keys` present in `local` onto a copy of `cloud`. Every other key
+ * keeps its cloud value.
+ *
+ * A local `live_status` returns every cloud key, with `null` for the ones it
+ * cannot serve, so presence cannot be the ownership test. A fixed owned-key set
+ * overlays local readings without clobbering cloud values, and lets a local outage
+ * fall back to the cloud value rather than to an unavailable one.
+ *
+ * A key overlays only when it is owned, present, and not null: null means "not
+ * served this tick" and the cloud value is kept. Any other falsy value (`0`,
+ * `false`, `""`) overlays, because a zero reading must win. `local` of null, a
+ * failed poll, yields a copy of `cloud`.
+ */
+export declare function merge_local_into_cloud<T extends object>(cloud: T, local: object | null, owned_keys: readonly string[]): T;
+/** Overlay a local `live_status` onto the cloud document. See {@link merge_local_into_cloud}. */
+export declare function merge_live_status<T extends object>(cloud: T, local: object | null): T;
+/** Overlay a local `site_info` onto the cloud document. See {@link merge_local_into_cloud}. */
+export declare function merge_site_info<T extends object>(cloud: T, local: object | null): T;
+declare class EnergySiteRouterBase<Bs extends Backends> extends Router<Bs> {
+  /** The site id of the first backend that has one. */
+  get energy_site_id(): MemberOf<Bs[number], "energy_site_id">;
+  /** Logs `transport=lan` for the local primary. Cloud fallbacks keep `backend=`. */
+  protected _backend_field(backend: object): string;
+}
+/**
+ * A router over energy sites: a local primary, such as `PowerwallEnergySite`,
+ * and one or more cloud fallbacks. See `Router` for dispatch, failover and the
+ * replay warning.
+ *
+ * There is no per-method list. A method the local backend omits goes straight to
+ * the cloud, and registration and discovery (`add_authorized_client`,
+ * `find_gateway_address`) belong on `router.secondary` directly. A local-only
+ * caller that must not fail over uses `router.primary`.
+ *
+ * A failed-over write can run twice. `operation`, `backup` and
+ * `grid_import_export` all write `config.json`, so do not split them across
+ * backends: one write would stomp the other.
+ */
+export type EnergySiteRouter<Bs extends Backends> = EnergySiteRouterBase<Bs> & Routed<Bs[number]>;
+export declare const EnergySiteRouter: new <const Bs extends Backends>(backends: Bs, options?: RouterOptions) => EnergySiteRouter<Bs>;
+export {};

package/dist/router/energysite.mjs

@@ -0,0 +1,60 @@
+import { Router } from "./base.mjs";
+// src/router/energysite.ts
+/** The `live_status` keys a local Powerwall owns. */
+const LOCAL_LIVE_STATUS_KEYS = [
+	"solar_power",
+	"energy_left",
+	"total_pack_energy",
+	"percentage_charged",
+	"battery_power",
+	"load_power",
+	"grid_power",
+	"generator_power",
+	"grid_status",
+	"island_status"
+];
+/** The `site_info` keys a local Powerwall owns. */
+const LOCAL_SITE_INFO_KEYS = ["backup_reserve_percent", "default_real_mode"];
+/**
+* Overlay `owned_keys` present in `local` onto a copy of `cloud`. Every other key
+* keeps its cloud value.
+*
+* A local `live_status` returns every cloud key, with `null` for the ones it
+* cannot serve, so presence cannot be the ownership test. A fixed owned-key set
+* overlays local readings without clobbering cloud values, and lets a local outage
+* fall back to the cloud value rather than to an unavailable one.
+*
+* A key overlays only when it is owned, present, and not null: null means "not
+* served this tick" and the cloud value is kept. Any other falsy value (`0`,
+* `false`, `""`) overlays, because a zero reading must win. `local` of null, a
+* failed poll, yields a copy of `cloud`.
+*/
+function merge_local_into_cloud(cloud, local, owned_keys) {
+	const merged = { ...cloud };
+	if (local == null) return merged;
+	for (const key of owned_keys) {
+		const value = local[key];
+		if (value !== void 0 && value !== null) merged[key] = value;
+	}
+	return merged;
+}
+/** Overlay a local `live_status` onto the cloud document. See {@link merge_local_into_cloud}. */
+function merge_live_status(cloud, local) {
+	return merge_local_into_cloud(cloud, local, LOCAL_LIVE_STATUS_KEYS);
+}
+/** Overlay a local `site_info` onto the cloud document. See {@link merge_local_into_cloud}. */
+function merge_site_info(cloud, local) {
+	return merge_local_into_cloud(cloud, local, LOCAL_SITE_INFO_KEYS);
+}
+var EnergySiteRouterBase = class extends Router {
+	/** The site id of the first backend that has one. */
+	get energy_site_id() {
+		return this._first_attribute("energy_site_id");
+	}
+	/** Logs `transport=lan` for the local primary. Cloud fallbacks keep `backend=`. */
+	_backend_field(backend) {
+		return backend === this.primary ? "transport=lan" : super._backend_field(backend);
+	}
+};
+const EnergySiteRouter = EnergySiteRouterBase;
+export { EnergySiteRouter, LOCAL_LIVE_STATUS_KEYS, LOCAL_SITE_INFO_KEYS, merge_live_status, merge_local_into_cloud, merge_site_info };

package/dist/router.cjs

@@ -0,0 +1,13 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_base = require("./router/base.cjs");
+const require_energysite = require("./router/energysite.cjs");
+exports.EnergySiteRouter = require_energysite.EnergySiteRouter;
+exports.FAILOVER_SAFE_ERRORS = require_base.FAILOVER_SAFE_ERRORS;
+exports.LOCAL_LIVE_STATUS_KEYS = require_energysite.LOCAL_LIVE_STATUS_KEYS;
+exports.LOCAL_SITE_INFO_KEYS = require_energysite.LOCAL_SITE_INFO_KEYS;
+exports.Router = require_base.Router;
+exports.VehicleRouter = require_base.VehicleRouter;
+exports.is_failover_safe = require_base.is_failover_safe;
+exports.merge_live_status = require_energysite.merge_live_status;
+exports.merge_local_into_cloud = require_energysite.merge_local_into_cloud;
+exports.merge_site_info = require_energysite.merge_site_info;

package/dist/router.d.cts

@@ -1 +1,3 @@
-export {}
+import { Backends, FAILOVER_SAFE_ERRORS, HealthCheck, ResultHandler, Routed, Router, RouterOptions, VehicleRouter, is_failover_safe } from "./router/base.cjs";
+import { EnergySiteRouter, LOCAL_LIVE_STATUS_KEYS, LOCAL_SITE_INFO_KEYS, merge_live_status, merge_local_into_cloud, merge_site_info } from "./router/energysite.cjs";
+export { type Backends, EnergySiteRouter, FAILOVER_SAFE_ERRORS, type HealthCheck, LOCAL_LIVE_STATUS_KEYS, LOCAL_SITE_INFO_KEYS, type ResultHandler, type Routed, Router, type RouterOptions, VehicleRouter, is_failover_safe, merge_live_status, merge_local_into_cloud, merge_site_info };

package/dist/router.d.mts

@@ -1 +1,3 @@
-export {}
+import { Backends, FAILOVER_SAFE_ERRORS, HealthCheck, ResultHandler, Routed, Router, RouterOptions, VehicleRouter, is_failover_safe } from "./router/base.mjs";
+import { EnergySiteRouter, LOCAL_LIVE_STATUS_KEYS, LOCAL_SITE_INFO_KEYS, merge_live_status, merge_local_into_cloud, merge_site_info } from "./router/energysite.mjs";
+export { type Backends, EnergySiteRouter, FAILOVER_SAFE_ERRORS, type HealthCheck, LOCAL_LIVE_STATUS_KEYS, LOCAL_SITE_INFO_KEYS, type ResultHandler, type Routed, Router, type RouterOptions, VehicleRouter, is_failover_safe, merge_live_status, merge_local_into_cloud, merge_site_info };

package/dist/router.mjs

@@ -1 +1,3 @@
-export {};
+import { FAILOVER_SAFE_ERRORS, Router, VehicleRouter, is_failover_safe } from "./router/base.mjs";
+import { EnergySiteRouter, LOCAL_LIVE_STATUS_KEYS, LOCAL_SITE_INFO_KEYS, merge_live_status, merge_local_into_cloud, merge_site_info } from "./router/energysite.mjs";
+export { EnergySiteRouter, FAILOVER_SAFE_ERRORS, LOCAL_LIVE_STATUS_KEYS, LOCAL_SITE_INFO_KEYS, Router, VehicleRouter, is_failover_safe, merge_live_status, merge_local_into_cloud, merge_site_info };

package/dist/signing/crypto.cjs

@@ -3,6 +3,7 @@ let crypto = require("crypto");
 crypto = require_runtime.__toESM(crypto, 1);
 // src/signing/crypto.ts
 const CURVE = "prime256v1";
+const AES_GCM_TAG_LENGTH = 16;
 /** Derive the uncompressed public key point for a raw P-256 private scalar. */
 function publicKeyFor(privateKey) {
 	const ecdh = crypto.default.createECDH(CURVE);
@@ -20,12 +21,39 @@ function deriveSharedKey(privateKey, vehiclePublicKey) {
 	const secret = ecdh.computeSecret(vehiclePublicKey);
 	return crypto.default.createHash("sha1").update(secret).digest().subarray(0, 16);
 }
+/** SHA-256 of a metadata string: the AAD of the protocol's AES-GCM operations. */
+function sha256(data) {
+	return crypto.default.createHash("sha256").update(data).digest();
+}
+/** AES-128-GCM with a detached 16-byte tag, as the vehicle-command protocol carries it. */
+function aesGcmEncrypt(key, nonce, plaintext, aad) {
+	const cipher = crypto.default.createCipheriv("aes-128-gcm", key, nonce, { authTagLength: AES_GCM_TAG_LENGTH });
+	cipher.setAAD(aad);
+	return {
+		ciphertext: Buffer.concat([cipher.update(plaintext), cipher.final()]),
+		tag: cipher.getAuthTag()
+	};
+}
+/**
+* Open an AES-128-GCM message. `authTagLength` makes a tag of any other length
+* fail, where the default would accept one truncated by an attacker.
+* @throws Error when the tag does not verify.
+*/
+function aesGcmDecrypt(key, nonce, ciphertext, tag, aad) {
+	const decipher = crypto.default.createDecipheriv("aes-128-gcm", key, nonce, { authTagLength: AES_GCM_TAG_LENGTH });
+	decipher.setAAD(aad);
+	decipher.setAuthTag(tag);
+	return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
 /** Big-endian uint32, as used throughout the signed-command metadata tags. */
 function uint32BE(value) {
 	const buffer = Buffer.alloc(4);
 	buffer.writeUInt32BE(value >>> 0, 0);
 	return buffer;
 }
+exports.aesGcmDecrypt = aesGcmDecrypt;
+exports.aesGcmEncrypt = aesGcmEncrypt;
 exports.deriveSharedKey = deriveSharedKey;
 exports.publicKeyFor = publicKeyFor;
+exports.sha256 = sha256;
 exports.uint32BE = uint32BE;

package/dist/signing/crypto.mjs

@@ -1,6 +1,7 @@
 import crypto from "crypto";
 // src/signing/crypto.ts
 const CURVE = "prime256v1";
+const AES_GCM_TAG_LENGTH = 16;
 /** Derive the uncompressed public key point for a raw P-256 private scalar. */
 function publicKeyFor(privateKey) {
 	const ecdh = crypto.createECDH(CURVE);
@@ -18,10 +19,34 @@ function deriveSharedKey(privateKey, vehiclePublicKey) {
 	const secret = ecdh.computeSecret(vehiclePublicKey);
 	return crypto.createHash("sha1").update(secret).digest().subarray(0, 16);
 }
+/** SHA-256 of a metadata string: the AAD of the protocol's AES-GCM operations. */
+function sha256(data) {
+	return crypto.createHash("sha256").update(data).digest();
+}
+/** AES-128-GCM with a detached 16-byte tag, as the vehicle-command protocol carries it. */
+function aesGcmEncrypt(key, nonce, plaintext, aad) {
+	const cipher = crypto.createCipheriv("aes-128-gcm", key, nonce, { authTagLength: AES_GCM_TAG_LENGTH });
+	cipher.setAAD(aad);
+	return {
+		ciphertext: Buffer.concat([cipher.update(plaintext), cipher.final()]),
+		tag: cipher.getAuthTag()
+	};
+}
+/**
+* Open an AES-128-GCM message. `authTagLength` makes a tag of any other length
+* fail, where the default would accept one truncated by an attacker.
+* @throws Error when the tag does not verify.
+*/
+function aesGcmDecrypt(key, nonce, ciphertext, tag, aad) {
+	const decipher = crypto.createDecipheriv("aes-128-gcm", key, nonce, { authTagLength: AES_GCM_TAG_LENGTH });
+	decipher.setAAD(aad);
+	decipher.setAuthTag(tag);
+	return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
 /** Big-endian uint32, as used throughout the signed-command metadata tags. */
 function uint32BE(value) {
 	const buffer = Buffer.alloc(4);
 	buffer.writeUInt32BE(value >>> 0, 0);
 	return buffer;
 }
-export { deriveSharedKey, publicKeyFor, uint32BE };
+export { aesGcmDecrypt, aesGcmEncrypt, deriveSharedKey, publicKeyFor, sha256, uint32BE };

package/dist/signing/energy.cjs

@@ -0,0 +1,123 @@
+const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+const require_energyisland = require("../energyisland.cjs");
+const require_crypto = require("./crypto.cjs");
+const require_keys = require("./keys.cjs");
+let _teslemetry_tesla_protocol_energy_device_transport = require("@teslemetry/tesla-protocol/energy_device/transport");
+let node_crypto = require("node:crypto");
+node_crypto = require_runtime.__toESM(node_crypto, 1);
+let _teslemetry_tesla_protocol_energy_device_authorization_types = require("@teslemetry/tesla-protocol/energy_device/authorization_types");
+let _teslemetry_tesla_protocol_energy_device_signed_message = require("@teslemetry/tesla-protocol/energy_device/signed_message");
+// src/signing/energy.ts
+/** The cloud round trip needs more than the 12 s LAN TTL; 30 s worked live through `device_command`. */
+const ENERGY_SIGNATURE_TTL_SECONDS = 30;
+/** ts-proto's value for an enum input it does not recognise. */
+const UNRECOGNIZED_ENUM = -1;
+/** Encode one tag-length-value entry. */
+function tlv(tag, value) {
+	return Buffer.concat([Buffer.from([tag, value.length]), value]);
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A proto field name in the camelCase form ts-proto generates. */
+function camelCase(name) {
+	return name.replace(/_([a-z0-9])/g, (_, character) => character.toUpperCase());
+}
+/** Convert every key from Python's proto field names; ts-proto's `fromJSON` reads camelCase only. */
+function camelCaseKeys(value) {
+	if (Array.isArray(value)) return value.map(camelCaseKeys);
+	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [camelCase(key), camelCaseKeys(item)]));
+	return value;
+}
+/**
+* Reject input `fromJSON` dropped or could not read, as Python's `ParseDict`
+* does: otherwise a mistyped field would be signed and sent without it.
+*/
+function assertParsed(input, parsed, path) {
+	if (Array.isArray(input) && Array.isArray(parsed)) input.forEach((item, index) => assertParsed(item, parsed[index], `${path}[${index}]`));
+	else if (isPlainObject(input) && isPlainObject(parsed) && !(parsed instanceof Date) && !ArrayBuffer.isView(parsed)) for (const [key, item] of Object.entries(input)) {
+		if (!(key in parsed)) throw new TypeError(`Unknown energy device command field ${path}.${key}`);
+		assertParsed(item, parsed[key], `${path}.${key}`);
+	}
+	else if (parsed instanceof Date && Number.isNaN(parsed.getTime()) || parsed === UNRECOGNIZED_ENUM && input !== UNRECOGNIZED_ENUM) throw new TypeError(`Invalid value for energy device command field ${path}`);
+}
+/**
+* Builds RSA-signed `RoutableMessage` bytes for one energy device key.
+*
+* The key must be an RSA key registered on the gateway with
+* `add_authorized_client` and in state `VERIFIED`. An ECC key cannot sign this
+* scheme: the `SignatureData` oneof has only `rsa_data`.
+*/
+var EnergyDeviceSigner = class {
+	/** The signer's public key, PKCS#1 DER. */
+	publicKeyDer;
+	/** Seconds a signed message stays valid. */
+	ttl;
+	#privateKey;
+	/**
+	* @param privateKey The RSA private key.
+	* @param ttl Seconds a signed message stays valid. `V1rTransport` passes 12.
+	* @throws TypeError for anything but an RSA private key.
+	*/
+	constructor(privateKey, ttl = 30) {
+		if (privateKey?.type !== "private" || privateKey.asymmetricKeyType !== "rsa") throw new TypeError("Energy device signing requires an RSA private key");
+		this.#privateKey = privateKey;
+		this.publicKeyDer = require_keys.rsaPublicDerPkcs1(privateKey);
+		this.ttl = ttl;
+	}
+	/**
+	* Serialize a cloud `MessageEnvelope` addressed to `din`.
+	*
+	* `category`, `command` and `params` are the snake_case proto field names
+	* the unsigned `grpc_command` sends, so every command can be signed without
+	* per-command code. `delivery_channel` stays unset, as in the envelope
+	* proven on the cloud path.
+	* @throws TypeError for a field the message does not have, or an island mode that is not 1 or 6.
+	*/
+	static envelope(din, category, command, params) {
+		if (category === "teg" && command === "set_island_mode_request") require_energyisland.validate_island_mode(params?.mode, params?.force);
+		const input = camelCaseKeys({ [category]: { [command]: params ?? {} } });
+		const envelope = _teslemetry_tesla_protocol_energy_device_transport.MessageEnvelope.fromJSON(input);
+		assertParsed(input, envelope, "message");
+		envelope.sender = { authorizedClient: _teslemetry_tesla_protocol_energy_device_authorization_types.AuthorizedClientType.AUTHORIZED_CLIENT_TYPE_CUSTOMER_MOBILE_APP };
+		envelope.recipient = { din };
+		return _teslemetry_tesla_protocol_energy_device_transport.MessageEnvelope.encode(envelope).finish();
+	}
+	/**
+	* Wrap `envelope` in a signed `RoutableMessage` and serialize it.
+	*
+	* RSA-4096 blocks for milliseconds, so this signs on the thread pool.
+	* @param envelope The serialized `MessageEnvelope`.
+	* @param din The gateway DIN the envelope and the request target.
+	* @param options `now` (in seconds) and `messageUuid` exist for test vectors.
+	*/
+	async sign(envelope, din, options = {}) {
+		if (din.length > 255 || /\P{ASCII}/u.test(din)) throw new TypeError("A gateway DIN must be at most 255 ASCII characters");
+		const expiresAt = Math.ceil(options.now ?? Date.now() / 1e3) + this.ttl;
+		const signedData = Buffer.concat([
+			tlv(_teslemetry_tesla_protocol_energy_device_signed_message.Tag.TAG_SIGNATURE_TYPE, Buffer.from([_teslemetry_tesla_protocol_energy_device_signed_message.SignatureType.SIGNATURE_TYPE_RSA])),
+			tlv(_teslemetry_tesla_protocol_energy_device_signed_message.Tag.TAG_DOMAIN, Buffer.from([_teslemetry_tesla_protocol_energy_device_signed_message.Domain.DOMAIN_ENERGY_DEVICE])),
+			tlv(_teslemetry_tesla_protocol_energy_device_signed_message.Tag.TAG_PERSONALIZATION, Buffer.from(din, "ascii")),
+			tlv(_teslemetry_tesla_protocol_energy_device_signed_message.Tag.TAG_EXPIRES_AT, require_crypto.uint32BE(expiresAt)),
+			Buffer.from([_teslemetry_tesla_protocol_energy_device_signed_message.Tag.TAG_END]),
+			envelope
+		]);
+		const signature = await new Promise((resolve, reject) => {
+			node_crypto.default.sign("sha512", signedData, this.#privateKey, (error, result) => error ? reject(error) : resolve(result));
+		});
+		return _teslemetry_tesla_protocol_energy_device_signed_message.RoutableMessage.encode(_teslemetry_tesla_protocol_energy_device_signed_message.RoutableMessage.create({
+			toDestination: { domain: _teslemetry_tesla_protocol_energy_device_signed_message.Domain.DOMAIN_ENERGY_DEVICE },
+			protobufMessageAsBytes: envelope,
+			signatureData: {
+				signerIdentity: { publicKey: this.publicKeyDer },
+				rsaData: {
+					expiresAt,
+					signature
+				}
+			},
+			uuid: options.messageUuid ?? node_crypto.default.randomBytes(16)
+		})).finish();
+	}
+};
+exports.ENERGY_SIGNATURE_TTL_SECONDS = ENERGY_SIGNATURE_TTL_SECONDS;
+exports.EnergyDeviceSigner = EnergyDeviceSigner;

package/dist/signing/energy.d.cts

@@ -0,0 +1,45 @@
+import crypto from "node:crypto";
+/** The cloud round trip needs more than the 12 s LAN TTL; 30 s worked live through `device_command`. */
+export declare const ENERGY_SIGNATURE_TTL_SECONDS = 30;
+/**
+ * Builds RSA-signed `RoutableMessage` bytes for one energy device key.
+ *
+ * The key must be an RSA key registered on the gateway with
+ * `add_authorized_client` and in state `VERIFIED`. An ECC key cannot sign this
+ * scheme: the `SignatureData` oneof has only `rsa_data`.
+ */
+export declare class EnergyDeviceSigner {
+  #private;
+  /** The signer's public key, PKCS#1 DER. */
+  readonly publicKeyDer: Buffer;
+  /** Seconds a signed message stays valid. */
+  readonly ttl: number;
+  /**
+   * @param privateKey The RSA private key.
+   * @param ttl Seconds a signed message stays valid. `V1rTransport` passes 12.
+   * @throws TypeError for anything but an RSA private key.
+   */
+  constructor(privateKey: crypto.KeyObject, ttl?: number);
+  /**
+   * Serialize a cloud `MessageEnvelope` addressed to `din`.
+   *
+   * `category`, `command` and `params` are the snake_case proto field names
+   * the unsigned `grpc_command` sends, so every command can be signed without
+   * per-command code. `delivery_channel` stays unset, as in the envelope
+   * proven on the cloud path.
+   * @throws TypeError for a field the message does not have, or an island mode that is not 1 or 6.
+   */
+  static envelope(din: string, category: string, command: string, params?: Record<string, unknown> | null): Uint8Array;
+  /**
+   * Wrap `envelope` in a signed `RoutableMessage` and serialize it.
+   *
+   * RSA-4096 blocks for milliseconds, so this signs on the thread pool.
+   * @param envelope The serialized `MessageEnvelope`.
+   * @param din The gateway DIN the envelope and the request target.
+   * @param options `now` (in seconds) and `messageUuid` exist for test vectors.
+   */
+  sign(envelope: Uint8Array, din: string, options?: {
+    now?: number;
+    messageUuid?: Uint8Array;
+  }): Promise<Uint8Array>;
+}

package/dist/signing/energy.d.mts

@@ -0,0 +1,45 @@
+import crypto from "node:crypto";
+/** The cloud round trip needs more than the 12 s LAN TTL; 30 s worked live through `device_command`. */
+export declare const ENERGY_SIGNATURE_TTL_SECONDS = 30;
+/**
+ * Builds RSA-signed `RoutableMessage` bytes for one energy device key.
+ *
+ * The key must be an RSA key registered on the gateway with
+ * `add_authorized_client` and in state `VERIFIED`. An ECC key cannot sign this
+ * scheme: the `SignatureData` oneof has only `rsa_data`.
+ */
+export declare class EnergyDeviceSigner {
+  #private;
+  /** The signer's public key, PKCS#1 DER. */
+  readonly publicKeyDer: Buffer;
+  /** Seconds a signed message stays valid. */
+  readonly ttl: number;
+  /**
+   * @param privateKey The RSA private key.
+   * @param ttl Seconds a signed message stays valid. `V1rTransport` passes 12.
+   * @throws TypeError for anything but an RSA private key.
+   */
+  constructor(privateKey: crypto.KeyObject, ttl?: number);
+  /**
+   * Serialize a cloud `MessageEnvelope` addressed to `din`.
+   *
+   * `category`, `command` and `params` are the snake_case proto field names
+   * the unsigned `grpc_command` sends, so every command can be signed without
+   * per-command code. `delivery_channel` stays unset, as in the envelope
+   * proven on the cloud path.
+   * @throws TypeError for a field the message does not have, or an island mode that is not 1 or 6.
+   */
+  static envelope(din: string, category: string, command: string, params?: Record<string, unknown> | null): Uint8Array;
+  /**
+   * Wrap `envelope` in a signed `RoutableMessage` and serialize it.
+   *
+   * RSA-4096 blocks for milliseconds, so this signs on the thread pool.
+   * @param envelope The serialized `MessageEnvelope`.
+   * @param din The gateway DIN the envelope and the request target.
+   * @param options `now` (in seconds) and `messageUuid` exist for test vectors.
+   */
+  sign(envelope: Uint8Array, din: string, options?: {
+    now?: number;
+    messageUuid?: Uint8Array;
+  }): Promise<Uint8Array>;
+}