tesla-fleet-api 0.4.0 → 0.6.0

package/dist/signing/keys.cjs

@@ -0,0 +1,191 @@
+const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+const require_exceptions = require("../exceptions.cjs");
+const require_crypto = require("./crypto.cjs");
+let node_crypto = require("node:crypto");
+node_crypto = require_runtime.__toESM(node_crypto, 1);
+let node_fs_promises = require("node:fs/promises");
+let node_timers_promises = require("node:timers/promises");
+// src/signing/keys.ts
+/** Read a key file for this long while another process finishes writing it. */
+const KEY_READ_RETRY_TIMEOUT_MS = 1e3;
+const KEY_READ_RETRY_INTERVAL_MS = 50;
+const KIND_NAMES = {
+	ec: "an EC P-256 private key",
+	rsa: "an RSA private key"
+};
+/** Whether `error` is the given Node system error, e.g. `ENOENT`. */
+function isSystemError(error, code) {
+	return error?.code === code;
+}
+/**
+* OpenSSL's error for a missing passphrase differs across Node versions
+* (`ERR_MISSING_PASSPHRASE`, `ERR_OSSL_CRYPTO_INTERRUPTED_OR_CANCELLED`), so
+* the PEM's own markers decide.
+*/
+function isEncryptedPem(pem) {
+	return /-----BEGIN ENCRYPTED PRIVATE KEY-----|Proc-Type:\s*4,ENCRYPTED/.test(pem.toString("latin1"));
+}
+/**
+* Parse a PEM as a private key of `kind`. A raw scalar carries no curve, so an
+* EC key on any curve but P-256 is the wrong type here. `subject` names the
+* source in errors; the key material never reaches one.
+*/
+function parsePrivateKey(pem, kind, subject) {
+	let key;
+	try {
+		key = node_crypto.default.createPrivateKey(pem);
+	} catch (error) {
+		if (isEncryptedPem(pem)) throw new require_exceptions.PrivateKeyError("encrypted", `${subject} is encrypted`, { cause: error });
+		throw new require_exceptions.PrivateKeyError("malformed", `${subject} is not a valid PEM private key`, { cause: error });
+	}
+	if (!(key.asymmetricKeyType === kind && (kind === "rsa" || key.asymmetricKeyDetails?.namedCurve === "prime256v1"))) throw new require_exceptions.PrivateKeyError("wrong_type", `${subject} is not ${KIND_NAMES[kind]}`);
+	return key;
+}
+/**
+* Read and parse a key file, waiting out one that is malformed only because
+* another process is still writing it.
+*/
+async function loadKeyFile(path, kind) {
+	const deadline = performance.now() + KEY_READ_RETRY_TIMEOUT_MS;
+	while (true) {
+		let pem;
+		try {
+			pem = await (0, node_fs_promises.readFile)(path);
+		} catch (error) {
+			throw new require_exceptions.PrivateKeyError("unreadable", `Could not read private key file at ${path}`, { cause: error });
+		}
+		try {
+			return parsePrivateKey(pem, kind, `Private key file at ${path}`);
+		} catch (error) {
+			if (error.reason !== "malformed" || performance.now() >= deadline) throw error;
+			await (0, node_timers_promises.setTimeout)(KEY_READ_RETRY_INTERVAL_MS);
+		}
+	}
+}
+/**
+* Load the key at `path`, or create it. The file is born exclusively at mode
+* 0600, so it is never world-readable; `chmod` covers a umask stricter than
+* that mode. A process that loses the create race reads the winner's file.
+*/
+async function loadOrCreateKeyFile(path, kind, generate) {
+	try {
+		return await loadKeyFile(path, kind);
+	} catch (error) {
+		if (!isSystemError(error.cause, "ENOENT")) throw error;
+	}
+	const pem = await generate();
+	let file;
+	try {
+		file = await (0, node_fs_promises.open)(path, "wx", 384);
+	} catch (error) {
+		if (isSystemError(error, "EEXIST")) return loadKeyFile(path, kind);
+		throw error;
+	}
+	try {
+		await file.chmod(384);
+		await file.writeFile(pem);
+	} finally {
+		await file.close();
+	}
+	return parsePrivateKey(pem, kind, `Private key file at ${path}`);
+}
+/** The raw 32-byte scalar of a P-256 key. JWK pads `d` to the field size, so leading zeros survive. */
+function rawScalar(key) {
+	return Buffer.from(key.export({ format: "jwk" }).d, "base64url");
+}
+/**
+* Get or create the P-256 key file at `path`.
+* @returns The raw 32-byte private key `Commands` takes.
+* @throws PrivateKeyError for an existing file that cannot be used.
+*/
+async function ecPrivateKeyFile(path) {
+	return rawScalar(await loadOrCreateKeyFile(path, "ec", generate_ec_private_key_pem));
+}
+/**
+* Get or create the RSA key file at `path`.
+* @param key_size Modulus length in bits for a new key.
+* @throws PrivateKeyError for an existing file that cannot be used.
+*/
+function rsaPrivateKeyFile(path, key_size) {
+	return loadOrCreateKeyFile(path, "rsa", () => generate_rsa_private_key_pem(key_size));
+}
+/** Generate a P-256 private key, as the SEC1 PEM Python's `get_private_key` writes. */
+function generate_ec_private_key_pem() {
+	return new Promise((resolve, reject) => {
+		node_crypto.default.generateKeyPair("ec", {
+			namedCurve: "P-256",
+			publicKeyEncoding: {
+				type: "spki",
+				format: "pem"
+			},
+			privateKeyEncoding: {
+				type: "sec1",
+				format: "pem"
+			}
+		}, (error, _publicKey, privateKey) => error ? reject(error) : resolve(privateKey));
+	});
+}
+/**
+* Generate an RSA private key off the event loop, as the PKCS#1 PEM Python's
+* `get_rsa_private_key` writes.
+* @param modulusLength Key size in bits; 4096 is what Powerwall v1r expects.
+*/
+function generate_rsa_private_key_pem(modulusLength = 4096) {
+	return new Promise((resolve, reject) => {
+		node_crypto.default.generateKeyPair("rsa", {
+			modulusLength,
+			publicExponent: 65537,
+			publicKeyEncoding: {
+				type: "spki",
+				format: "pem"
+			},
+			privateKeyEncoding: {
+				type: "pkcs1",
+				format: "pem"
+			}
+		}, (error, _publicKey, privateKey) => error ? reject(error) : resolve(privateKey));
+	});
+}
+/**
+* The raw 32-byte `Buffer` that `Commands` takes, from a P-256 PEM held in
+* memory.
+* @throws PrivateKeyError when the PEM cannot be used.
+*/
+function ec_private_key_from_pem(pem) {
+	return rawScalar(parsePrivateKey(pem, "ec", "Private key PEM"));
+}
+/**
+* The RSA public key in DER PKCS#1 form, the format an energy gateway expects
+* when registering an authorized client, from a private key PEM held in memory.
+* @throws PrivateKeyError when the PEM cannot be used.
+*/
+function rsa_public_der_pkcs1(pem) {
+	return rsaPublicDerPkcs1(parsePrivateKey(pem, "rsa", "Private key PEM"));
+}
+function rsaPublicDerPkcs1(key) {
+	return node_crypto.default.createPublicKey(key).export({
+		type: "pkcs1",
+		format: "der"
+	});
+}
+/** The public key of a raw P-256 private key, as a `KeyObject` for serialization. */
+function ecPublicKey(privateKey) {
+	const point = require_crypto.publicKeyFor(privateKey);
+	return node_crypto.default.createPublicKey({
+		key: {
+			kty: "EC",
+			crv: "P-256",
+			x: point.subarray(1, 33).toString("base64url"),
+			y: point.subarray(33).toString("base64url")
+		},
+		format: "jwk"
+	});
+}
+exports.ecPrivateKeyFile = ecPrivateKeyFile;
+exports.ecPublicKey = ecPublicKey;
+exports.ec_private_key_from_pem = ec_private_key_from_pem;
+exports.generate_ec_private_key_pem = generate_ec_private_key_pem;
+exports.generate_rsa_private_key_pem = generate_rsa_private_key_pem;
+exports.rsaPrivateKeyFile = rsaPrivateKeyFile;
+exports.rsaPublicDerPkcs1 = rsaPublicDerPkcs1;
+exports.rsa_public_der_pkcs1 = rsa_public_der_pkcs1;

package/dist/signing/keys.d.cts

@@ -0,0 +1,21 @@
+import crypto from "node:crypto";
+/** Generate a P-256 private key, as the SEC1 PEM Python's `get_private_key` writes. */
+export declare function generate_ec_private_key_pem(): Promise<string>;
+/**
+ * Generate an RSA private key off the event loop, as the PKCS#1 PEM Python's
+ * `get_rsa_private_key` writes.
+ * @param modulusLength Key size in bits; 4096 is what Powerwall v1r expects.
+ */
+export declare function generate_rsa_private_key_pem(modulusLength?: number): Promise<string>;
+/**
+ * The raw 32-byte `Buffer` that `Commands` takes, from a P-256 PEM held in
+ * memory.
+ * @throws PrivateKeyError when the PEM cannot be used.
+ */
+export declare function ec_private_key_from_pem(pem: string | Buffer): Buffer;
+/**
+ * The RSA public key in DER PKCS#1 form, the format an energy gateway expects
+ * when registering an authorized client, from a private key PEM held in memory.
+ * @throws PrivateKeyError when the PEM cannot be used.
+ */
+export declare function rsa_public_der_pkcs1(pem: string | Buffer): Buffer;

package/dist/signing/keys.d.mts

@@ -0,0 +1,21 @@
+import crypto from "node:crypto";
+/** Generate a P-256 private key, as the SEC1 PEM Python's `get_private_key` writes. */
+export declare function generate_ec_private_key_pem(): Promise<string>;
+/**
+ * Generate an RSA private key off the event loop, as the PKCS#1 PEM Python's
+ * `get_rsa_private_key` writes.
+ * @param modulusLength Key size in bits; 4096 is what Powerwall v1r expects.
+ */
+export declare function generate_rsa_private_key_pem(modulusLength?: number): Promise<string>;
+/**
+ * The raw 32-byte `Buffer` that `Commands` takes, from a P-256 PEM held in
+ * memory.
+ * @throws PrivateKeyError when the PEM cannot be used.
+ */
+export declare function ec_private_key_from_pem(pem: string | Buffer): Buffer;
+/**
+ * The RSA public key in DER PKCS#1 form, the format an energy gateway expects
+ * when registering an authorized client, from a private key PEM held in memory.
+ * @throws PrivateKeyError when the PEM cannot be used.
+ */
+export declare function rsa_public_der_pkcs1(pem: string | Buffer): Buffer;

package/dist/signing/keys.mjs

@@ -0,0 +1,182 @@
+import { PrivateKeyError } from "../exceptions.mjs";
+import { publicKeyFor } from "./crypto.mjs";
+import crypto from "node:crypto";
+import { open, readFile } from "node:fs/promises";
+import { setTimeout } from "node:timers/promises";
+// src/signing/keys.ts
+/** Read a key file for this long while another process finishes writing it. */
+const KEY_READ_RETRY_TIMEOUT_MS = 1e3;
+const KEY_READ_RETRY_INTERVAL_MS = 50;
+const KIND_NAMES = {
+	ec: "an EC P-256 private key",
+	rsa: "an RSA private key"
+};
+/** Whether `error` is the given Node system error, e.g. `ENOENT`. */
+function isSystemError(error, code) {
+	return error?.code === code;
+}
+/**
+* OpenSSL's error for a missing passphrase differs across Node versions
+* (`ERR_MISSING_PASSPHRASE`, `ERR_OSSL_CRYPTO_INTERRUPTED_OR_CANCELLED`), so
+* the PEM's own markers decide.
+*/
+function isEncryptedPem(pem) {
+	return /-----BEGIN ENCRYPTED PRIVATE KEY-----|Proc-Type:\s*4,ENCRYPTED/.test(pem.toString("latin1"));
+}
+/**
+* Parse a PEM as a private key of `kind`. A raw scalar carries no curve, so an
+* EC key on any curve but P-256 is the wrong type here. `subject` names the
+* source in errors; the key material never reaches one.
+*/
+function parsePrivateKey(pem, kind, subject) {
+	let key;
+	try {
+		key = crypto.createPrivateKey(pem);
+	} catch (error) {
+		if (isEncryptedPem(pem)) throw new PrivateKeyError("encrypted", `${subject} is encrypted`, { cause: error });
+		throw new PrivateKeyError("malformed", `${subject} is not a valid PEM private key`, { cause: error });
+	}
+	if (!(key.asymmetricKeyType === kind && (kind === "rsa" || key.asymmetricKeyDetails?.namedCurve === "prime256v1"))) throw new PrivateKeyError("wrong_type", `${subject} is not ${KIND_NAMES[kind]}`);
+	return key;
+}
+/**
+* Read and parse a key file, waiting out one that is malformed only because
+* another process is still writing it.
+*/
+async function loadKeyFile(path, kind) {
+	const deadline = performance.now() + KEY_READ_RETRY_TIMEOUT_MS;
+	while (true) {
+		let pem;
+		try {
+			pem = await readFile(path);
+		} catch (error) {
+			throw new PrivateKeyError("unreadable", `Could not read private key file at ${path}`, { cause: error });
+		}
+		try {
+			return parsePrivateKey(pem, kind, `Private key file at ${path}`);
+		} catch (error) {
+			if (error.reason !== "malformed" || performance.now() >= deadline) throw error;
+			await setTimeout(KEY_READ_RETRY_INTERVAL_MS);
+		}
+	}
+}
+/**
+* Load the key at `path`, or create it. The file is born exclusively at mode
+* 0600, so it is never world-readable; `chmod` covers a umask stricter than
+* that mode. A process that loses the create race reads the winner's file.
+*/
+async function loadOrCreateKeyFile(path, kind, generate) {
+	try {
+		return await loadKeyFile(path, kind);
+	} catch (error) {
+		if (!isSystemError(error.cause, "ENOENT")) throw error;
+	}
+	const pem = await generate();
+	let file;
+	try {
+		file = await open(path, "wx", 384);
+	} catch (error) {
+		if (isSystemError(error, "EEXIST")) return loadKeyFile(path, kind);
+		throw error;
+	}
+	try {
+		await file.chmod(384);
+		await file.writeFile(pem);
+	} finally {
+		await file.close();
+	}
+	return parsePrivateKey(pem, kind, `Private key file at ${path}`);
+}
+/** The raw 32-byte scalar of a P-256 key. JWK pads `d` to the field size, so leading zeros survive. */
+function rawScalar(key) {
+	return Buffer.from(key.export({ format: "jwk" }).d, "base64url");
+}
+/**
+* Get or create the P-256 key file at `path`.
+* @returns The raw 32-byte private key `Commands` takes.
+* @throws PrivateKeyError for an existing file that cannot be used.
+*/
+async function ecPrivateKeyFile(path) {
+	return rawScalar(await loadOrCreateKeyFile(path, "ec", generate_ec_private_key_pem));
+}
+/**
+* Get or create the RSA key file at `path`.
+* @param key_size Modulus length in bits for a new key.
+* @throws PrivateKeyError for an existing file that cannot be used.
+*/
+function rsaPrivateKeyFile(path, key_size) {
+	return loadOrCreateKeyFile(path, "rsa", () => generate_rsa_private_key_pem(key_size));
+}
+/** Generate a P-256 private key, as the SEC1 PEM Python's `get_private_key` writes. */
+function generate_ec_private_key_pem() {
+	return new Promise((resolve, reject) => {
+		crypto.generateKeyPair("ec", {
+			namedCurve: "P-256",
+			publicKeyEncoding: {
+				type: "spki",
+				format: "pem"
+			},
+			privateKeyEncoding: {
+				type: "sec1",
+				format: "pem"
+			}
+		}, (error, _publicKey, privateKey) => error ? reject(error) : resolve(privateKey));
+	});
+}
+/**
+* Generate an RSA private key off the event loop, as the PKCS#1 PEM Python's
+* `get_rsa_private_key` writes.
+* @param modulusLength Key size in bits; 4096 is what Powerwall v1r expects.
+*/
+function generate_rsa_private_key_pem(modulusLength = 4096) {
+	return new Promise((resolve, reject) => {
+		crypto.generateKeyPair("rsa", {
+			modulusLength,
+			publicExponent: 65537,
+			publicKeyEncoding: {
+				type: "spki",
+				format: "pem"
+			},
+			privateKeyEncoding: {
+				type: "pkcs1",
+				format: "pem"
+			}
+		}, (error, _publicKey, privateKey) => error ? reject(error) : resolve(privateKey));
+	});
+}
+/**
+* The raw 32-byte `Buffer` that `Commands` takes, from a P-256 PEM held in
+* memory.
+* @throws PrivateKeyError when the PEM cannot be used.
+*/
+function ec_private_key_from_pem(pem) {
+	return rawScalar(parsePrivateKey(pem, "ec", "Private key PEM"));
+}
+/**
+* The RSA public key in DER PKCS#1 form, the format an energy gateway expects
+* when registering an authorized client, from a private key PEM held in memory.
+* @throws PrivateKeyError when the PEM cannot be used.
+*/
+function rsa_public_der_pkcs1(pem) {
+	return rsaPublicDerPkcs1(parsePrivateKey(pem, "rsa", "Private key PEM"));
+}
+function rsaPublicDerPkcs1(key) {
+	return crypto.createPublicKey(key).export({
+		type: "pkcs1",
+		format: "der"
+	});
+}
+/** The public key of a raw P-256 private key, as a `KeyObject` for serialization. */
+function ecPublicKey(privateKey) {
+	const point = publicKeyFor(privateKey);
+	return crypto.createPublicKey({
+		key: {
+			kty: "EC",
+			crv: "P-256",
+			x: point.subarray(1, 33).toString("base64url"),
+			y: point.subarray(33).toString("base64url")
+		},
+		format: "jwk"
+	});
+}
+export { ecPrivateKeyFile, ecPublicKey, ec_private_key_from_pem, generate_ec_private_key_pem, generate_rsa_private_key_pem, rsaPrivateKeyFile, rsaPublicDerPkcs1, rsa_public_der_pkcs1 };

package/dist/signing/session.cjs

@@ -1,22 +1,38 @@
 const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+const require_exceptions = require("../exceptions.cjs");
 let crypto = require("crypto");
 crypto = require_runtime.__toESM(crypto, 1);
 let _teslemetry_tesla_protocol_command_signatures = require("@teslemetry/tesla-protocol/command/signatures");
 // src/signing/session.ts
+/** Wire limit of the `counter` and `expires_at` fields. */
+const UINT32_MAX = 4294967295;
+/** Seconds a signed command stays valid. BLE can be slow, so AES-GCM allows longer. */
+const HMAC_LIFETIME_S = 10;
+const AES_GCM_LIFETIME_S = 30;
+/** Response counters remembered per session, which bounds how far back a replay is caught. */
+const RESPONSE_COUNTER_CACHE_SIZE = 256;
 /**
 * Per-domain (VCSEC / Infotainment) signed-command session: tracks the
 * anti-replay counter/epoch handed out by the vehicle's handshake reply and
 * the HMAC keys derived from it.
 *
-* Deriving key material (`keysFor`) is split from committing it (`commit`)
-* because the caller must authenticate a `SessionInfo` reply - by verifying
-* its `session_info_tag` against the very keys derived here - *before*
-* trusting anything in it, including the vehicle public key the shared key
-* itself is derived from. See `Commands.validateAndUpdateSession`.
+* The vehicle's key is trusted once, at first contact, then pinned for the life
+* of the session, as in Tesla's Go SDK. ECDH is symmetric, so anyone who saw the
+* client's public key can tag a `SessionInfo` naming a key of their own: a tag
+* proves nothing about a key derived from the same reply. `trustedKeys` is the
+* only way a reply reaches key material, so once pinned it is verified with the
+* stored keys, and nothing clears the pin. A re-keyed vehicle needs a new instance.
+*
+* First contact itself is trust on first use. Deriving keys (`keysFor`) is still
+* split from committing them (`commit`), so a reply that fails its tag or carries
+* a whitelist rejection pins nothing. See `Commands.validate_msg`.
 *
 * A `Session` is not itself thread-safe; `withLock` serializes the
 * message-build step (which mutates `counter`) so concurrent commands on the
 * same domain cannot race on the same counter value.
+*
+* The derived keys are native private fields, read through accessors, so a
+* `JSON.stringify` or structured log of a session cannot reach them.
 */
 var Session = class {
 	deriveSharedKey;
@@ -24,26 +40,39 @@ var Session = class {
 	counter = 0;
 	epoch;
 	delta;
-	sharedKey;
-	hmacKey;
-	sessionInfoKey;
-	publicKey;
+	#publicKey;
+	#keys;
 	/** Clock time of the last *authenticated* SessionInfo committed for the current epoch, guarding against replay/rollback. */
 	lastAuthenticatedClockTime;
+	/** `(requestHash, counter)` pairs seen in this epoch, oldest first. */
+	responseCounters = /* @__PURE__ */ new Set();
 	queue = Promise.resolve();
 	constructor(domain, deriveSharedKey) {
 		this.deriveSharedKey = deriveSharedKey;
 		this.domain = domain;
 	}
+	/** The vehicle key pinned at first contact. There is deliberately no setter. */
+	get publicKey() {
+		return this.#publicKey;
+	}
+	get sharedKey() {
+		return this.#keys?.sharedKey;
+	}
+	get hmacKey() {
+		return this.#keys?.hmacKey;
+	}
+	get sessionInfoKey() {
+		return this.#keys?.sessionInfoKey;
+	}
 	/** Whether the handshake has completed and commands can be signed. */
 	get ready() {
-		return this.epoch !== void 0 && this.hmacKey !== void 0 && this.delta !== void 0;
+		return this.epoch !== void 0 && this.#keys !== void 0 && this.delta !== void 0;
 	}
 	/**
 	* Derive the shared key and its two HMAC sub-keys for a candidate vehicle
 	* public key, without touching any session state. Pure and side-effect
 	* free so a caller can verify authenticity first and discard the result
-	* if verification fails.
+	* if verification fails. Verifying a reply goes through `trustedKeys`.
 	*/
 	keysFor(vehiclePublicKey) {
 		const sharedKey = this.deriveSharedKey(vehiclePublicKey);
@@ -54,46 +83,91 @@ var Session = class {
 		};
 	}
 	/**
-	* Commit an already-authenticated `SessionInfo` plus the `keysFor` result
-	* derived from its public key. Per the vehicle-command protocol, the
-	* anti-replay counter must never roll back within the same epoch, and a
-	* clock time that regresses within the same epoch marks the reply as
-	* stale/replayed - returns `false` (without mutating any state) in that
-	* case so the caller can reject it.
+	* The keys to verify a reply naming `vehiclePublicKey` with: derived from it
+	* at first contact, and the stored keys from then on, never derived again.
+	* @throws SessionInfoAuthenticationFault when the session is pinned to another key.
+	*/
+	trustedKeys(vehiclePublicKey) {
+		if (this.#publicKey === void 0 || this.#keys === void 0) return this.keysFor(vehiclePublicKey);
+		if (!this.#publicKey.equals(vehiclePublicKey)) throw new require_exceptions.SessionInfoAuthenticationFault("Session info reply names a vehicle public key that has changed since first contact; discarded. If the vehicle was really re-keyed, build a new instance to trust it.");
+		return this.#keys;
+	}
+	/**
+	* Commit an already-authenticated `SessionInfo` plus its `trustedKeys`
+	* result. Keys are adopted at first contact only: after that, `keys` is
+	* ignored and a different public key is refused. Per the vehicle-command
+	* protocol, the anti-replay counter must never roll back within the same
+	* epoch, and a clock time that regresses within the same epoch marks the
+	* reply as stale/replayed - returns `false` (without mutating any state) in
+	* that case so the caller can reject it.
+	* @throws SessionInfoAuthenticationFault, changing nothing, for a different public key, or a clock or counter that could not sign a single command.
 	*/
 	commit(sessionInfo, keys) {
+		const trusted = this.#keys === void 0 ? keys : this.trustedKeys(Buffer.from(sessionInfo.publicKey));
 		const incomingEpoch = Buffer.from(sessionInfo.epoch);
 		const sameEpoch = this.epoch !== void 0 && this.epoch.equals(incomingEpoch);
 		if (sameEpoch && this.lastAuthenticatedClockTime !== void 0 && sessionInfo.clockTime < this.lastAuthenticatedClockTime) return false;
+		if (sessionInfo.clockTime + AES_GCM_LIFETIME_S > UINT32_MAX || sessionInfo.counter >= UINT32_MAX) throw new require_exceptions.SessionInfoAuthenticationFault("Session info reply has a clock or counter no command could be signed with; discarded.");
 		this.counter = sameEpoch ? Math.max(this.counter, sessionInfo.counter) : sessionInfo.counter;
 		this.epoch = incomingEpoch;
 		this.delta = Math.floor(Date.now() / 1e3) - sessionInfo.clockTime;
 		this.lastAuthenticatedClockTime = sessionInfo.clockTime;
-		this.publicKey = Buffer.from(sessionInfo.publicKey);
-		this.sharedKey = keys.sharedKey;
-		this.hmacKey = keys.hmacKey;
-		this.sessionInfoKey = keys.sessionInfoKey;
+		this.#publicKey = Buffer.from(sessionInfo.publicKey);
+		this.#keys = trusted;
+		if (!sameEpoch) this.responseCounters.clear();
 		return true;
 	}
 	/**
-	* Advance the anti-replay counter and return fresh signature metadata for
-	* an HMAC-personalized command. The command expires 10 seconds from now,
-	* corrected for clock drift against the vehicle (`delta`).
+	* Record an authenticated response's counter for the request it answers.
+	* @returns `false` if that pair was already seen, marking the response a replay.
 	*/
-	hmacPersonalized() {
+	record_response_counter(requestHash, counter) {
+		const identity = `${Buffer.from(requestHash).toString("hex")}:${counter}`;
+		if (this.responseCounters.has(identity)) return false;
+		this.responseCounters.add(identity);
+		if (this.responseCounters.size > RESPONSE_COUNTER_CACHE_SIZE) this.responseCounters.delete(this.responseCounters.values().next().value);
+		return true;
+	}
+	/**
+	* Advance the anti-replay counter for a command valid for `lifetimeSeconds`,
+	* corrected for clock drift against the vehicle (`delta`). The clock keeps
+	* running after `commit`, so its limit is checked here too; a session past it
+	* recovers when the vehicle starts a new epoch.
+	* @throws SessionInfoAuthenticationFault, leaving the counter alone, when either value would overflow its wire field.
+	*/
+	nextSignature(lifetimeSeconds) {
 		if (!this.ready || !this.epoch || this.delta === void 0) throw new Error("Session is not ready: perform the handshake first.");
+		const expiresAt = Math.floor(Date.now() / 1e3) - this.delta + lifetimeSeconds;
+		if (expiresAt > UINT32_MAX || this.counter >= UINT32_MAX) throw new require_exceptions.SessionInfoAuthenticationFault("Session has reached the limit of the vehicle clock or counter, so nothing was signed.");
 		this.counter++;
-		return _teslemetry_tesla_protocol_command_signatures.HMACPersonalizedSignatureData.create({
+		return {
 			epoch: this.epoch,
 			counter: this.counter,
-			expiresAt: Math.floor(Date.now() / 1e3) - this.delta + 10
+			expiresAt
+		};
+	}
+	/**
+	* Fresh signature metadata for an HMAC-personalized command, which expires
+	* 10 seconds from now.
+	*/
+	hmacPersonalized() {
+		return _teslemetry_tesla_protocol_command_signatures.HMACPersonalizedSignatureData.create(this.nextSignature(HMAC_LIFETIME_S));
+	}
+	/**
+	* Fresh signature metadata for an AES-GCM-personalized command, with a
+	* random nonce, which expires 30 seconds from now.
+	*/
+	aesGcmPersonalized() {
+		return _teslemetry_tesla_protocol_command_signatures.AESGCMPersonalizedSignatureData.create({
+			...this.nextSignature(AES_GCM_LIFETIME_S),
+			nonce: crypto.default.randomBytes(12)
 		});
 	}
 	/**
 	* Run `fn` with exclusive access to this session, queuing behind any
-	* in-flight caller. Held only for as long as `fn` takes - callers should
-	* keep it scoped to the synchronous message-build step, not a full
-	* network round trip.
+	* in-flight caller. Not reentrant: `fn` must not call `withLock` on this
+	* session. Infotainment holds it for the message build only, and VCSEC for
+	* the whole dispatch (see `Commands.dispatch`).
 	*/
 	async withLock(fn) {
 		const previous = this.queue;