@basmilius/apple-common 0.9.16 → 0.9.17

package/dist/index.d.mts

@@ -86,6 +86,7 @@ declare class Logger {
 declare class Reporter {
   #private;
   all(): void;
+  none(): void;
   disable(group: DebugGroup): void;
   enable(group: DebugGroup): void;
   isEnabled(group: DebugGroup): boolean;
@@ -107,19 +108,82 @@ declare abstract class BasePairing {
   constructor(context: Context);
   tlv(buffer: Buffer): Map<number, Buffer>;
 }
+/**
+ * Implements the HAP (HomeKit Accessory Protocol) Pair-Setup flow using SRP-6a.
+ *
+ * The pairing process uses Secure Remote Password (SRP) for PIN-based authentication,
+ * followed by Ed25519 signature exchange for long-term identity establishment.
+ *
+ * Flow: M1 (salt exchange) → M2 (SRP proof) → M3 (server proof) → M4 (shared secret)
+ *       → M5 (encrypted credential exchange) → M6 (accessory verification)
+ *
+ * For transient pairing (HomePod), only M1-M4 are needed — no long-term credentials are stored.
+ */
 declare class AccessoryPair extends BasePairing {
   #private;
   constructor(context: Context, requestHandler: RequestHandler);
   start(): Promise<void>;
   pin(askPin: () => Promise<string>): Promise<AccessoryCredentials>;
   transient(): Promise<AccessoryKeys>;
+  /**
+   * SRP Step 1: Initiates pair-setup by requesting the accessory's SRP public key and salt.
+   *
+   * Sends: TLV with Method=PairSetup, State=M1, optional Flags (e.g. TransientPairing).
+   * Receives: Accessory's SRP public key (B) and salt for key derivation.
+   */
   m1(additionalTlv?: [number, number | Buffer][]): Promise<PairM1>;
+  /**
+   * SRP Step 2: Generates client proof using the PIN.
+   *
+   * Creates an SRP client with the accessory's salt and public key, then computes
+   * the client's public key (A) and proof (M1) which proves knowledge of the PIN.
+   */
   m2(m1: PairM1, pin?: string): Promise<PairM2>;
+  /**
+   * SRP Step 3: Sends the client's public key and proof; receives the server's proof.
+   *
+   * Sends: TLV with State=M3, client SRP public key (A), and client proof (M1).
+   * Receives: Server's M2-proof, confirming the accessory also knows the PIN.
+   */
   m3(m2: PairM2): Promise<PairM3>;
+  /**
+   * SRP Step 4: Verifies the server's proof and derives the shared secret.
+   *
+   * Validates the server's M2-proof, then computes the SRP session key (K).
+   * This shared secret is the root key for all subsequent HKDF derivations.
+   */
   m4(m3: PairM3): Promise<PairM4>;
+  /**
+   * HAP Step 5: Encrypted credential exchange — controller sends its identity.
+   *
+   * Derives a signing key (HKDF with "Pair-Setup-Controller-Sign-Salt/Info") and
+   * a session key (HKDF with "Pair-Setup-Encrypt-Salt/Info") from the SRP shared secret.
+   * Signs [signingKey || pairingId || Ed25519PublicKey] and sends it encrypted
+   * via ChaCha20-Poly1305 (nonce "PS-Msg05").
+   *
+   * Receives: Encrypted accessory credentials (decrypted in M6).
+   */
   m5(m4: PairM4): Promise<PairM5>;
+  /**
+   * HAP Step 6: Verifies the accessory's identity and extracts long-term credentials.
+   *
+   * Decrypts the accessory's response from M5 via ChaCha20-Poly1305 (nonce "PS-Msg06").
+   * Derives "Accessory X" (HKDF with "Pair-Setup-Accessory-Sign-Salt/Info"), then
+   * verifies the Ed25519 signature over [accessoryX || accessoryId || accessoryPublicKey].
+   *
+   * Returns the accessory's long-term public key and identifier for future Pair-Verify sessions.
+   */
   m6(m4: PairM4, m5: PairM5): Promise<AccessoryCredentials>;
 }
+/**
+ * Implements the HAP (HomeKit Accessory Protocol) Pair-Verify flow using Curve25519 ECDH.
+ *
+ * Used to re-authenticate a previously paired accessory without needing the PIN again.
+ * Establishes a new session with forward secrecy via ephemeral Curve25519 key exchange.
+ *
+ * Flow: M1 (ephemeral key exchange) → M2 (signature verification)
+ *       → M3 (controller proof) → M4 (session key derivation)
+ */
 declare class AccessoryVerify extends BasePairing {
   #private;
   constructor(context: Context, requestHandler: RequestHandler);

package/dist/index.mjs

@@ -693,6 +693,8 @@ var Discovery = class Discovery {
 			const cached = Discovery.#cache.get(this.#service);
 			if (cached && cached.expiresAt > Date.now()) return cached.results;
 		}
+		const now = Date.now();
+		for (const [key, entry] of Discovery.#cache) if (entry.expiresAt <= now) Discovery.#cache.delete(key);
 		const mapped = (await multicast([this.#service], 4)).map(toDiscoveryResult);
 		Discovery.#cache.set(this.#service, {
 			results: mapped,
@@ -1049,6 +1051,9 @@ var Reporter = class {
 			"warn"
 		];
 	}
+	none() {
+		this.#enabled = [];
+	}
 	disable(group) {
 		if (this.#enabled.includes(group)) this.#enabled.splice(this.#enabled.indexOf(group), 1);
 	}
@@ -3135,6 +3140,17 @@ var BasePairing = class {
 		return data;
 	}
 };
+/**
+* Implements the HAP (HomeKit Accessory Protocol) Pair-Setup flow using SRP-6a.
+*
+* The pairing process uses Secure Remote Password (SRP) for PIN-based authentication,
+* followed by Ed25519 signature exchange for long-term identity establishment.
+*
+* Flow: M1 (salt exchange) → M2 (SRP proof) → M3 (server proof) → M4 (shared secret)
+*       → M5 (encrypted credential exchange) → M6 (accessory verification)
+*
+* For transient pairing (HomePod), only M1-M4 are needed — no long-term credentials are stored.
+*/
 var AccessoryPair = class extends BasePairing {
 	#name;
 	#pairingId;
@@ -3189,6 +3205,12 @@ var AccessoryPair = class extends BasePairing {
 			controllerToAccessoryKey
 		};
 	}
+	/**
+	* SRP Step 1: Initiates pair-setup by requesting the accessory's SRP public key and salt.
+	*
+	* Sends: TLV with Method=PairSetup, State=M1, optional Flags (e.g. TransientPairing).
+	* Receives: Accessory's SRP public key (B) and salt for key derivation.
+	*/
 	async m1(additionalTlv = []) {
 		const response = await this.#requestHandler("m1", TLV8.encode([
 			[TLV8.Value.Method, TLV8.Method.PairSetup],
@@ -3201,6 +3223,12 @@ var AccessoryPair = class extends BasePairing {
 			salt: data.get(TLV8.Value.Salt)
 		};
 	}
+	/**
+	* SRP Step 2: Generates client proof using the PIN.
+	*
+	* Creates an SRP client with the accessory's salt and public key, then computes
+	* the client's public key (A) and proof (M1) which proves knowledge of the PIN.
+	*/
 	async m2(m1, pin = AIRPLAY_TRANSIENT_PIN) {
 		const srpKey = await import_srp.SRP.genKey(32);
 		this.#srp = new import_srp.SrpClient(import_srp.SRP.params.hap, m1.salt, Buffer.from("Pair-Setup"), Buffer.from(pin), srpKey, true);
@@ -3210,6 +3238,12 @@ var AccessoryPair = class extends BasePairing {
 			proof: this.#srp.computeM1()
 		};
 	}
+	/**
+	* SRP Step 3: Sends the client's public key and proof; receives the server's proof.
+	*
+	* Sends: TLV with State=M3, client SRP public key (A), and client proof (M1).
+	* Receives: Server's M2-proof, confirming the accessory also knows the PIN.
+	*/
 	async m3(m2) {
 		const response = await this.#requestHandler("m3", TLV8.encode([
 			[TLV8.Value.State, TLV8.State.M3],
@@ -3218,10 +3252,26 @@ var AccessoryPair = class extends BasePairing {
 		]));
 		return { serverProof: this.tlv(response).get(TLV8.Value.Proof) };
 	}
+	/**
+	* SRP Step 4: Verifies the server's proof and derives the shared secret.
+	*
+	* Validates the server's M2-proof, then computes the SRP session key (K).
+	* This shared secret is the root key for all subsequent HKDF derivations.
+	*/
 	async m4(m3) {
 		this.#srp.checkM2(m3.serverProof);
 		return { sharedSecret: this.#srp.computeK() };
 	}
+	/**
+	* HAP Step 5: Encrypted credential exchange — controller sends its identity.
+	*
+	* Derives a signing key (HKDF with "Pair-Setup-Controller-Sign-Salt/Info") and
+	* a session key (HKDF with "Pair-Setup-Encrypt-Salt/Info") from the SRP shared secret.
+	* Signs [signingKey || pairingId || Ed25519PublicKey] and sends it encrypted
+	* via ChaCha20-Poly1305 (nonce "PS-Msg05").
+	*
+	* Receives: Encrypted accessory credentials (decrypted in M6).
+	*/
 	async m5(m4) {
 		const iosDeviceX = hkdf({
 			hash: "sha512",
@@ -3260,6 +3310,15 @@ var AccessoryPair = class extends BasePairing {
 			sessionKey
 		};
 	}
+	/**
+	* HAP Step 6: Verifies the accessory's identity and extracts long-term credentials.
+	*
+	* Decrypts the accessory's response from M5 via ChaCha20-Poly1305 (nonce "PS-Msg06").
+	* Derives "Accessory X" (HKDF with "Pair-Setup-Accessory-Sign-Salt/Info"), then
+	* verifies the Ed25519 signature over [accessoryX || accessoryId || accessoryPublicKey].
+	*
+	* Returns the accessory's long-term public key and identifier for future Pair-Verify sessions.
+	*/
 	async m6(m4, m5) {
 		const data = Chacha20.decrypt(m5.sessionKey, Buffer.from("PS-Msg06"), null, m5.data, m5.authTag);
 		const tlv = TLV8.decode(data);
@@ -3288,6 +3347,15 @@ var AccessoryPair = class extends BasePairing {
 		};
 	}
 };
+/**
+* Implements the HAP (HomeKit Accessory Protocol) Pair-Verify flow using Curve25519 ECDH.
+*
+* Used to re-authenticate a previously paired accessory without needing the PIN again.
+* Establishes a new session with forward secrecy via ephemeral Curve25519 key exchange.
+*
+* Flow: M1 (ephemeral key exchange) → M2 (signature verification)
+*       → M3 (controller proof) → M4 (session key derivation)
+*/
 var AccessoryVerify = class extends BasePairing {
 	#ephemeralKeyPair;
 	#requestHandler;
@@ -3302,6 +3370,12 @@ var AccessoryVerify = class extends BasePairing {
 		await this.#m3(credentials.pairingId, credentials.secretKey, m2);
 		return await this.#m4(m2, credentials.pairingId);
 	}
+	/**
+	* Pair-Verify Step 1: Ephemeral Curve25519 key exchange initiation.
+	*
+	* Sends: TLV with State=M1 and controller's ephemeral Curve25519 public key.
+	* Receives: Accessory's ephemeral public key and encrypted identity proof.
+	*/
 	async #m1() {
 		const response = await this.#requestHandler("m1", TLV8.encode([[TLV8.Value.State, TLV8.State.M1], [TLV8.Value.PublicKey, Buffer.from(this.#ephemeralKeyPair.publicKey)]]));
 		const data = this.tlv(response);
@@ -3311,6 +3385,16 @@ var AccessoryVerify = class extends BasePairing {
 			serverPublicKey
 		};
 	}
+	/**
+	* Pair-Verify Step 2: ECDH shared secret derivation and accessory signature verification.
+	*
+	* Computes the Curve25519 shared secret, derives a session key via HKDF
+	* ("Pair-Verify-Encrypt-Salt/Info"), then decrypts the accessory's response
+	* via ChaCha20-Poly1305 (nonce "PV-Msg02").
+	*
+	* Verifies the accessory's Ed25519 signature over [serverPubKey || accessoryId || clientPubKey]
+	* and checks the accessory identifier matches the stored credentials.
+	*/
 	async #m2(localAccessoryIdentifier, longTermPublicKey, m1) {
 		const sharedSecret = Buffer.from(Curve25519.generateSharedSecKey(this.#ephemeralKeyPair.secretKey, m1.serverPublicKey));
 		const sessionKey = hkdf({
@@ -3339,6 +3423,13 @@ var AccessoryVerify = class extends BasePairing {
 			sharedSecret
 		};
 	}
+	/**
+	* Pair-Verify Step 3: Controller authentication proof.
+	*
+	* Signs [clientEphemeralPubKey || pairingId || serverEphemeralPubKey] with the
+	* controller's long-term Ed25519 secret key. Encrypts the signed TLV via
+	* ChaCha20-Poly1305 (nonce "PV-Msg03") and sends it to the accessory.
+	*/
 	async #m3(pairingId, secretKey, m2) {
 		const iosDeviceInfo = Buffer.concat([
 			this.#ephemeralKeyPair.publicKey,
@@ -3352,6 +3443,12 @@ var AccessoryVerify = class extends BasePairing {
 		await this.#requestHandler("m3", TLV8.encode([[TLV8.Value.State, TLV8.State.M3], [TLV8.Value.EncryptedData, encrypted]]));
 		return {};
 	}
+	/**
+	* Pair-Verify Step 4: Returns the established session keys.
+	*
+	* The shared secret from the ECDH exchange is used by the caller to derive
+	* encryption keys (via HKDF with "Control-Salt" and "Control-Read/Write-Encryption-Key").
+	*/
 	async #m4(m2, pairingId) {
 		return {
 			accessoryToControllerKey: Buffer.alloc(0),

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@basmilius/apple-common",
     "description": "Common features shared across various apple protocol packages.",
-    "version": "0.9.16",
+    "version": "0.9.17",
     "type": "module",
     "license": "MIT",
     "author": {
@@ -45,8 +45,8 @@
         }
     },
     "dependencies": {
-        "@basmilius/apple-encoding": "0.9.16",
-        "@basmilius/apple-encryption": "0.9.16"
+        "@basmilius/apple-encoding": "0.9.17",
+        "@basmilius/apple-encryption": "0.9.17"
     },
     "devDependencies": {
         "@types/bun": "^1.3.11",