tesla-fleet-api 0.4.0 → 0.6.0

package/dist/signing/session.d.cts

@@ -1,5 +1,5 @@
 import { Domain } from "@teslemetry/tesla-protocol/command/universal_message";
-import { HMACPersonalizedSignatureData, SessionInfo } from "@teslemetry/tesla-protocol/command/signatures";
+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;
@@ -11,59 +11,96 @@ export interface SessionKeys {
  * 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.
  */
 export declare class Session {
+  #private;
   private readonly deriveSharedKey;
   readonly domain: Domain;
   counter: number;
   epoch?: Buffer;
   delta?: number;
-  sharedKey?: Buffer;
-  hmacKey?: Buffer;
-  sessionInfoKey?: Buffer;
-  publicKey?: Buffer;
   /** 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.
+   * if verification fails. Verifying a reply goes through `trustedKeys`.
    */
   keysFor(vehiclePublicKey: Buffer): SessionKeys;
   /**
-   * 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: 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;
   /**
-   * 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.
+   */
+  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. 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`).
    */
   withLock<T>(fn: () => T | Promise<T>): Promise<T>;
 }

package/dist/signing/session.d.mts

@@ -1,5 +1,5 @@
 import { Domain } from "@teslemetry/tesla-protocol/command/universal_message";
-import { HMACPersonalizedSignatureData, SessionInfo } from "@teslemetry/tesla-protocol/command/signatures";
+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;
@@ -11,59 +11,96 @@ export interface SessionKeys {
  * 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.
  */
 export declare class Session {
+  #private;
   private readonly deriveSharedKey;
   readonly domain: Domain;
   counter: number;
   epoch?: Buffer;
   delta?: number;
-  sharedKey?: Buffer;
-  hmacKey?: Buffer;
-  sessionInfoKey?: Buffer;
-  publicKey?: Buffer;
   /** 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.
+   * if verification fails. Verifying a reply goes through `trustedKeys`.
    */
   keysFor(vehiclePublicKey: Buffer): SessionKeys;
   /**
-   * 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: 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;
   /**
-   * 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.
+   */
+  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. 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`).
    */
   withLock<T>(fn: () => T | Promise<T>): Promise<T>;
 }

package/dist/signing/session.mjs

@@ -1,20 +1,36 @@
+import { SessionInfoAuthenticationFault } from "../exceptions.mjs";
 import crypto from "crypto";
-import { HMACPersonalizedSignatureData } from "@teslemetry/tesla-protocol/command/signatures";
+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.
 *
-* 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;
@@ -22,26 +38,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);
@@ -52,46 +81,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 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.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 SessionInfoAuthenticationFault("Session has reached the limit of the vehicle clock or counter, so nothing was signed.");
 		this.counter++;
-		return 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 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. 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;

package/dist/tariff.cjs

@@ -1,5 +1,31 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_exceptions = require("./exceptions.cjs");
 // src/tariff.ts
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Extract the `tariff_content_v2` object from a raw API response.
+*
+* Accepts the `site_info` read envelope (`{ response: { tariff_content_v2 } }`), the
+* `time_of_use_settings` write envelope (`{ tou_settings: { tariff_content_v2 } }`), or the bare
+* `tariff_content_v2` object itself. Throws {@link InvalidResponse} for a null body, an
+* unrecognized envelope, or an extracted object without the minimal Tariff V2 shape (`seasons`
+* and `energy_charges`) - checked identically on every path, since a malformed body (including an
+* empty `{}` nested under a recognized envelope) is not the same as "no tariff configured".
+*/
+function unwrapTariffV2(response) {
+	if (response == null) throw new require_exceptions.InvalidResponse("tariff response body was null");
+	if (!isObject(response)) throw new require_exceptions.InvalidResponse(String(response));
+	let candidate;
+	if ("tariff_content_v2" in response) candidate = response.tariff_content_v2;
+	else if ("response" in response || "tou_settings" in response) {
+		const inner = "response" in response ? response.response : response.tou_settings;
+		candidate = isObject(inner) ? inner.tariff_content_v2 : void 0;
+	} else candidate = response;
+	if (isObject(candidate) && "seasons" in candidate && "energy_charges" in candidate) return candidate;
+	throw new require_exceptions.InvalidResponse(response);
+}
 const MINUTES_PER_DAY = 1440;
 function formatParts(date, timeZone) {
 	const parts = new Intl.DateTimeFormat("en-US", {
@@ -290,3 +316,4 @@ function getTariffPeriods(tariff, now, opts) {
 	return resolution;
 }
 exports.getTariffPeriods = getTariffPeriods;
+exports.unwrapTariffV2 = unwrapTariffV2;

package/dist/tariff.d.cts

@@ -18,6 +18,17 @@ export interface TariffResolution {
   currency: string | null;
   upcoming: TariffPeriod[] | null;
 }
+/**
+ * Extract the `tariff_content_v2` object from a raw API response.
+ *
+ * Accepts the `site_info` read envelope (`{ response: { tariff_content_v2 } }`), the
+ * `time_of_use_settings` write envelope (`{ tou_settings: { tariff_content_v2 } }`), or the bare
+ * `tariff_content_v2` object itself. Throws {@link InvalidResponse} for a null body, an
+ * unrecognized envelope, or an extracted object without the minimal Tariff V2 shape (`seasons`
+ * and `energy_charges`) - checked identically on every path, since a malformed body (including an
+ * empty `{}` nested under a recognized envelope) is not the same as "no tariff configured".
+ */
+export declare function unwrapTariffV2(response: unknown): TariffContentV2;
 /**
  * Resolves the current buy/sell time-of-use rate for a Tariff V2 object at a given instant.
  * `tariff` carries no timezone; the caller must supply the site's IANA zone (e.g. from

package/dist/tariff.d.mts

@@ -18,6 +18,17 @@ export interface TariffResolution {
   currency: string | null;
   upcoming: TariffPeriod[] | null;
 }
+/**
+ * Extract the `tariff_content_v2` object from a raw API response.
+ *
+ * Accepts the `site_info` read envelope (`{ response: { tariff_content_v2 } }`), the
+ * `time_of_use_settings` write envelope (`{ tou_settings: { tariff_content_v2 } }`), or the bare
+ * `tariff_content_v2` object itself. Throws {@link InvalidResponse} for a null body, an
+ * unrecognized envelope, or an extracted object without the minimal Tariff V2 shape (`seasons`
+ * and `energy_charges`) - checked identically on every path, since a malformed body (including an
+ * empty `{}` nested under a recognized envelope) is not the same as "no tariff configured".
+ */
+export declare function unwrapTariffV2(response: unknown): TariffContentV2;
 /**
  * Resolves the current buy/sell time-of-use rate for a Tariff V2 object at a given instant.
  * `tariff` carries no timezone; the caller must supply the site's IANA zone (e.g. from

package/dist/tariff.mjs

@@ -1,4 +1,30 @@
+import { InvalidResponse } from "./exceptions.mjs";
 // src/tariff.ts
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Extract the `tariff_content_v2` object from a raw API response.
+*
+* Accepts the `site_info` read envelope (`{ response: { tariff_content_v2 } }`), the
+* `time_of_use_settings` write envelope (`{ tou_settings: { tariff_content_v2 } }`), or the bare
+* `tariff_content_v2` object itself. Throws {@link InvalidResponse} for a null body, an
+* unrecognized envelope, or an extracted object without the minimal Tariff V2 shape (`seasons`
+* and `energy_charges`) - checked identically on every path, since a malformed body (including an
+* empty `{}` nested under a recognized envelope) is not the same as "no tariff configured".
+*/
+function unwrapTariffV2(response) {
+	if (response == null) throw new InvalidResponse("tariff response body was null");
+	if (!isObject(response)) throw new InvalidResponse(String(response));
+	let candidate;
+	if ("tariff_content_v2" in response) candidate = response.tariff_content_v2;
+	else if ("response" in response || "tou_settings" in response) {
+		const inner = "response" in response ? response.response : response.tou_settings;
+		candidate = isObject(inner) ? inner.tariff_content_v2 : void 0;
+	} else candidate = response;
+	if (isObject(candidate) && "seasons" in candidate && "energy_charges" in candidate) return candidate;
+	throw new InvalidResponse(response);
+}
 const MINUTES_PER_DAY = 1440;
 function formatParts(date, timeZone) {
 	const parts = new Intl.DateTimeFormat("en-US", {
@@ -288,4 +314,4 @@ function getTariffPeriods(tariff, now, opts) {
 	if (opts.horizonHours) resolution.upcoming = buildUpcoming(tariff.seasons, tariff.energy_charges, sellSeasons, tariff.sell_tariff?.energy_charges, !!tariff.sell_tariff, wallClock, opts.horizonHours * 60, toDate);
 	return resolution;
 }
-export { getTariffPeriods };
+export { getTariffPeriods, unwrapTariffV2 };