tesla-fleet-api 0.3.0 → 0.5.0

package/dist/signing/session.d.cts

@@ -0,0 +1,106 @@
+import { Domain } from "@teslemetry/tesla-protocol/command/universal_message";
+import { AESGCMPersonalizedSignatureData, HMACPersonalizedSignatureData, SessionInfo } from "@teslemetry/tesla-protocol/command/signatures";
+/** Key material derived (but not yet trusted/committed) for a candidate vehicle public key. */
+export interface SessionKeys {
+  sharedKey: Buffer;
+  hmacKey: Buffer;
+  sessionInfoKey: Buffer;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare class Session {
+  #private;
+  private readonly deriveSharedKey;
+  readonly domain: Domain;
+  counter: number;
+  epoch?: Buffer;
+  delta?: number;
+  /** Clock time of the last *authenticated* SessionInfo committed for the current epoch, guarding against replay/rollback. */
+  private lastAuthenticatedClockTime?;
+  /** `(requestHash, counter)` pairs seen in this epoch, oldest first. */
+  private responseCounters;
+  private queue;
+  constructor(domain: Domain, deriveSharedKey: (vehiclePublicKey: Buffer) => Buffer);
+  /** The vehicle key pinned at first contact. There is deliberately no setter. */
+  get publicKey(): Buffer | undefined;
+  get sharedKey(): Buffer | undefined;
+  get hmacKey(): Buffer | undefined;
+  get sessionInfoKey(): Buffer | undefined;
+  /** Whether the handshake has completed and commands can be signed. */
+  get ready(): boolean;
+  /**
+   * 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. Verifying a reply goes through `trustedKeys`.
+   */
+  keysFor(vehiclePublicKey: Buffer): SessionKeys;
+  /**
+   * 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: Buffer): SessionKeys;
+  /**
+   * 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: SessionInfo, keys: SessionKeys): boolean;
+  /**
+   * Record an authenticated response's counter for the request it answers.
+   * @returns `false` if that pair was already seen, marking the response a replay.
+   */
+  record_response_counter(requestHash: Uint8Array, counter: number): boolean;
+  /**
+   * 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.
+   */
+  private nextSignature;
+  /**
+   * Fresh signature metadata for an HMAC-personalized command, which expires
+   * 10 seconds from now.
+   */
+  hmacPersonalized(): HMACPersonalizedSignatureData;
+  /**
+   * Fresh signature metadata for an AES-GCM-personalized command, with a
+   * random nonce, which expires 30 seconds from now.
+   */
+  aesGcmPersonalized(): AESGCMPersonalizedSignatureData;
+  /**
+   * Run `fn` with exclusive access to this session, queuing behind any
+   * 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`).
+   */
+  withLock<T>(fn: () => T | Promise<T>): Promise<T>;
+}

package/dist/signing/session.d.mts

@@ -0,0 +1,106 @@
+import { Domain } from "@teslemetry/tesla-protocol/command/universal_message";
+import { AESGCMPersonalizedSignatureData, HMACPersonalizedSignatureData, SessionInfo } from "@teslemetry/tesla-protocol/command/signatures";
+/** Key material derived (but not yet trusted/committed) for a candidate vehicle public key. */
+export interface SessionKeys {
+  sharedKey: Buffer;
+  hmacKey: Buffer;
+  sessionInfoKey: Buffer;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare class Session {
+  #private;
+  private readonly deriveSharedKey;
+  readonly domain: Domain;
+  counter: number;
+  epoch?: Buffer;
+  delta?: number;
+  /** Clock time of the last *authenticated* SessionInfo committed for the current epoch, guarding against replay/rollback. */
+  private lastAuthenticatedClockTime?;
+  /** `(requestHash, counter)` pairs seen in this epoch, oldest first. */
+  private responseCounters;
+  private queue;
+  constructor(domain: Domain, deriveSharedKey: (vehiclePublicKey: Buffer) => Buffer);
+  /** The vehicle key pinned at first contact. There is deliberately no setter. */
+  get publicKey(): Buffer | undefined;
+  get sharedKey(): Buffer | undefined;
+  get hmacKey(): Buffer | undefined;
+  get sessionInfoKey(): Buffer | undefined;
+  /** Whether the handshake has completed and commands can be signed. */
+  get ready(): boolean;
+  /**
+   * 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. Verifying a reply goes through `trustedKeys`.
+   */
+  keysFor(vehiclePublicKey: Buffer): SessionKeys;
+  /**
+   * 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: Buffer): SessionKeys;
+  /**
+   * 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: SessionInfo, keys: SessionKeys): boolean;
+  /**
+   * Record an authenticated response's counter for the request it answers.
+   * @returns `false` if that pair was already seen, marking the response a replay.
+   */
+  record_response_counter(requestHash: Uint8Array, counter: number): boolean;
+  /**
+   * 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.
+   */
+  private nextSignature;
+  /**
+   * Fresh signature metadata for an HMAC-personalized command, which expires
+   * 10 seconds from now.
+   */
+  hmacPersonalized(): HMACPersonalizedSignatureData;
+  /**
+   * Fresh signature metadata for an AES-GCM-personalized command, with a
+   * random nonce, which expires 30 seconds from now.
+   */
+  aesGcmPersonalized(): AESGCMPersonalizedSignatureData;
+  /**
+   * Run `fn` with exclusive access to this session, queuing behind any
+   * 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`).
+   */
+  withLock<T>(fn: () => T | Promise<T>): Promise<T>;
+}

package/dist/signing/session.mjs

@@ -0,0 +1,184 @@
+import { SessionInfoAuthenticationFault } from "../exceptions.mjs";
+import crypto from "crypto";
+import { AESGCMPersonalizedSignatureData, HMACPersonalizedSignatureData } from "@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.
+*
+* 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;
+	domain;
+	counter = 0;
+	epoch;
+	delta;
+	#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.#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. Verifying a reply goes through `trustedKeys`.
+	*/
+	keysFor(vehiclePublicKey) {
+		const sharedKey = this.deriveSharedKey(vehiclePublicKey);
+		return {
+			sharedKey,
+			hmacKey: crypto.createHmac("sha256", sharedKey).update("authenticated command").digest(),
+			sessionInfoKey: crypto.createHmac("sha256", sharedKey).update("session info").digest()
+		};
+	}
+	/**
+	* 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 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 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.#keys = trusted;
+		if (!sameEpoch) this.responseCounters.clear();
+		return true;
+	}
+	/**
+	* Record an authenticated response's counter for the request it answers.
+	* @returns `false` if that pair was already seen, marking the response a replay.
+	*/
+	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 SessionInfoAuthenticationFault("Session has reached the limit of the vehicle clock or counter, so nothing was signed.");
+		this.counter++;
+		return {
+			epoch: this.epoch,
+			counter: this.counter,
+			expiresAt
+		};
+	}
+	/**
+	* Fresh signature metadata for an HMAC-personalized command, which expires
+	* 10 seconds from now.
+	*/
+	hmacPersonalized() {
+		return 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 AESGCMPersonalizedSignatureData.create({
+			...this.nextSignature(AES_GCM_LIFETIME_S),
+			nonce: crypto.randomBytes(12)
+		});
+	}
+	/**
+	* Run `fn` with exclusive access to this session, queuing behind any
+	* 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;
+		let release;
+		this.queue = new Promise((resolve) => {
+			release = resolve;
+		});
+		await previous.catch(() => void 0);
+		try {
+			return await fn();
+		} finally {
+			release();
+		}
+	}
+};
+export { Session };