@corewire/core 0.0.0 → 1.0.0-next.1

package/dist/index.d.mts

@@ -0,0 +1,82 @@
+import { a as ReporterEntry, c as TrafficDirection, d as TrafficSink, f as reporter, i as Reporter, l as TrafficEntry, n as LogSink, o as ReporterSink, r as Logger, s as ReporterSinkOptions, t as DebugGroup, u as TrafficProtocol } from "./reporter-Dn7n2TXN.mjs";
+import { t as EventMap } from "./types-qzabRJJ9.mjs";
+
+//#region src/errors.d.ts
+/** Base class of the CoreWire errors, so one `instanceof` check catches all of them. */
+declare class AppleProtocolError extends Error {
+  constructor(message: string);
+}
+/** Thrown when a TCP connection fails to open or breaks. */
+declare class ConnectionError extends AppleProtocolError {
+  constructor(message: string);
+}
+/** Thrown when a TCP connection attempt exceeds the configured socket timeout. */
+declare class ConnectionTimeoutError extends ConnectionError {
+  constructor(message?: string);
+}
+/** Thrown when a connection or session closes before an operation finishes, or when an operation runs on a closed one. */
+declare class ConnectionClosedError extends ConnectionError {
+  constructor(message?: string);
+}
+/** Thrown when a HAP pair-setup or pair-verify fails. */
+declare class PairingError extends AppleProtocolError {
+  constructor(message: string);
+}
+/**
+* Thrown when the accessory's identity verification fails, such as an invalid
+* Ed25519 signature or mismatched accessory identifier during pair-verify.
+*/
+declare class AuthenticationError extends PairingError {
+  constructor(message: string);
+}
+/**
+* Thrown when stored credentials are invalid, missing, or incompatible
+* with the accessory (e.g. after a factory reset).
+*/
+declare class CredentialsError extends PairingError {
+  constructor(message: string);
+}
+/** Thrown when a protocol command fails to execute on the target device. */
+declare class CommandError extends AppleProtocolError {
+  constructor(message: string);
+}
+/** Thrown when a protocol setup step fails (e.g. an RTSP SETUP). */
+declare class SetupError extends AppleProtocolError {
+  constructor(message: string);
+}
+/** Thrown when mDNS device discovery fails or a device cannot be found after retries. */
+declare class DiscoveryError extends AppleProtocolError {
+  constructor(message: string);
+}
+/** Thrown when encrypting or decrypting a message fails. */
+declare class EncryptionError extends AppleProtocolError {
+  constructor(message: string);
+}
+/** Thrown when a response from the accessory is malformed or has an unexpected format. */
+declare class InvalidResponseError extends AppleProtocolError {
+  constructor(message: string);
+}
+/** Thrown when a protocol operation exceeds its expected time limit. */
+declare class TimeoutError extends AppleProtocolError {
+  constructor(message: string);
+}
+/** Thrown when a media playback operation fails on the target device. */
+declare class PlaybackError extends AppleProtocolError {
+  constructor(message: string);
+}
+/** Thrown when the authentication tag of a ChaCha20-Poly1305 message does not match, because the ciphertext changed or the key or nonce is wrong. */
+declare class DecryptionError extends EncryptionError {
+  constructor(message?: string);
+}
+/** Thrown when the accessory answers a pairing message with a TLV8 error or back-off. */
+declare class TLV8PairingError extends PairingError {
+  /** The TLV8 error code of the accessory; undefined when it sent none. */
+  readonly code: number | undefined;
+  constructor(message: string, code?: number);
+}
+//#endregion
+//#region src/utils.d.ts
+/** Resolves after `ms` milliseconds. */
+declare function waitFor(ms: number): Promise<void>;
+//#endregion
+export { AppleProtocolError, AuthenticationError, CommandError, ConnectionClosedError, ConnectionError, ConnectionTimeoutError, CredentialsError, type DebugGroup, DecryptionError, DiscoveryError, EncryptionError, type EventMap, InvalidResponseError, type LogSink, Logger, PairingError, PlaybackError, type Reporter, type ReporterEntry, type ReporterSink, type ReporterSinkOptions, SetupError, TLV8PairingError, TimeoutError, type TrafficDirection, type TrafficEntry, type TrafficProtocol, type TrafficSink, reporter, waitFor };

package/dist/index.mjs

@@ -0,0 +1,5 @@
+import { a as ConnectionError, c as DecryptionError, d as InvalidResponseError, f as PairingError, g as TimeoutError, h as TLV8PairingError, i as ConnectionClosedError, l as DiscoveryError, m as SetupError, n as AuthenticationError, o as ConnectionTimeoutError, p as PlaybackError, r as CommandError, s as CredentialsError, t as AppleProtocolError, u as EncryptionError } from "./errors-DVv1n4fL.mjs";
+import { n as reporter, t as Logger } from "./reporter-DfM6vPT0.mjs";
+import { t as waitFor } from "./utils-DY5OKUuy.mjs";
+
+export { AppleProtocolError, AuthenticationError, CommandError, ConnectionClosedError, ConnectionError, ConnectionTimeoutError, CredentialsError, DecryptionError, DiscoveryError, EncryptionError, InvalidResponseError, Logger, PairingError, PlaybackError, SetupError, TLV8PairingError, TimeoutError, reporter, waitFor };

package/dist/pairing.d.mts

@@ -0,0 +1,169 @@
+import { c as Context } from "./index-BJKNwUmq.mjs";
+
+//#region src/pairing/cipher.d.ts
+/** The HAP channel keys, named from the controller's side: we decrypt with `Control-Read-Encryption-Key`. */
+declare function deriveControlKeys(sharedSecret: Buffer): {
+  accessoryToControllerKey: Buffer;
+  controllerToAccessoryKey: Buffer;
+};
+//#endregion
+//#region src/pairing/types.d.ts
+/** The HAP pairing message a controller sends: M1, M3 or M5. */
+type PairingStep = "m1" | "m3" | "m5";
+/**
+* Carries one pairing message to the accessory and resolves with its reply. Pairing only knows
+* TLV8; the protocol knows the frame (an HTTP body, an OPack frame). Some protocols frame the
+* first message differently, hence the step.
+*/
+type PairingTransport = (payload: Buffer, step: PairingStep) => Promise<Buffer>;
+/** Long-term credentials from a PIN pair-setup, reused by every later pair-verify. */
+type AccessoryCredentials = {
+  readonly accessoryIdentifier: string;
+  readonly accessoryLongTermPublicKey: Buffer; /** This controller's pairing identifier (an uppercase UUID). */
+  readonly pairingId: Buffer; /** This controller's Ed25519 key pair. */
+  readonly publicKey: Buffer;
+  readonly secretKey: Buffer;
+};
+/** Session keys from a transient pair-setup or a pair-verify. */
+type AccessoryKeys = {
+  readonly pairingId: Buffer; /** Root key for the HKDF derivation of the channel keys. */
+  readonly sharedSecret: Buffer; /** Empty after a bare pair-verify; the protocol derives its own channel keys from {@link sharedSecret}. */
+  readonly accessoryToControllerKey: Buffer;
+  readonly controllerToAccessoryKey: Buffer;
+};
+/** The persistent identity an accessory presents. Persist it, or paired controllers lose their pairing. */
+type AccessoryIdentity = {
+  /** A MAC-like pairing identifier, e.g. "AA:BB:CC:DD:EE:FF". */readonly identifier: string;
+  readonly publicKey: Buffer;
+  readonly secretKey: Buffer;
+};
+/** A controller that completed pair-setup with the accessory. */
+type PairedController = {
+  readonly identifier: string;
+  readonly longTermPublicKey: Buffer;
+};
+/** Looks up a paired controller's long-term public key; undefined rejects the pair-verify. */
+type ControllerResolver = (pairingId: string) => Buffer | undefined;
+/** Options shared by the controller and accessory sides. */
+type PairingOptions = {
+  /** AES-128-CTR instead of ChaCha20-Poly1305 for the encrypted sub-TLVs, for legacy devices. */readonly useAes?: boolean;
+};
+//#endregion
+//#region src/pairing/client.d.ts
+/**
+* Runs HAP pair-setup as the controller, with SRP-6a followed by an Ed25519 identity exchange.
+*
+* A PIN pairing runs M1 to M6 and yields long-term credentials. A transient pairing stops after M4
+* with the fixed {@link TRANSIENT_PAIRING_PIN} and yields session keys only. The steps are public
+* for a caller that has to wait for the PIN between M1 and M2.
+*/
+declare class PairSetup {
+  #private;
+  constructor(context: Context, transport: PairingTransport, options?: PairingOptions);
+  /** Generates the controller's long-term Ed25519 key pair. Call before {@link pin}. */
+  start(): Promise<void>;
+  /**
+  * Runs a PIN pairing from M1 to M6. It calls `askPin` after M1, once the accessory shows the PIN.
+  *
+  * @throws {PairingError} If a step fails.
+  */
+  pin(askPin: () => Promise<string>): Promise<AccessoryCredentials>;
+  /** Runs a transient pairing from M1 to M4 without a PIN. The keys hold for this connection only. */
+  transient(): Promise<AccessoryKeys>;
+  /** Asks the accessory for its SRP public key and salt. */
+  m1(additionalTlv?: [number, number | Buffer][]): Promise<PairM1>;
+  /** Computes the SRP public key and the proof that we know the PIN. Sends nothing. */
+  m2(m1: PairM1, pin?: string): Promise<PairM2>;
+  /** Sends our SRP public key and proof, and receives the accessory's proof. */
+  m3(m2: PairM2): Promise<PairM3>;
+  /** Checks the accessory's proof and derives the SRP shared secret. Sends nothing. */
+  m4(m3: PairM3): Promise<PairM4>;
+  /** Sends our signed, encrypted identity and receives the accessory's encrypted identity. */
+  m5(m4: PairM4): Promise<PairM5>;
+  /**
+  * Decrypts and verifies the accessory's identity from M5. Sends nothing.
+  *
+  * @throws {AuthenticationError} If the accessory signature is invalid.
+  */
+  m6(m4: PairM4, m5: PairM5): Promise<AccessoryCredentials>;
+}
+/**
+* Runs HAP pair-verify as the controller. An ephemeral Curve25519 exchange proves both long-term
+* identities from an earlier pair-setup, so every session gets fresh keys without the PIN.
+*/
+declare class PairVerify {
+  #private;
+  constructor(context: Context, transport: PairingTransport, options?: PairingOptions);
+  /**
+  * Verifies the pairing and returns the shared secret. The channel keys stay empty, because
+  * each protocol derives its own from the secret.
+  *
+  * @throws {AuthenticationError} If the accessory's identity does not match the credentials.
+  */
+  start(credentials: AccessoryCredentials): Promise<AccessoryKeys>;
+}
+type PairM1 = {
+  readonly publicKey: Buffer;
+  readonly salt: Buffer;
+};
+type PairM2 = {
+  readonly publicKey: Buffer;
+  readonly proof: Buffer;
+};
+type PairM3 = {
+  readonly serverProof: Buffer;
+};
+type PairM4 = {
+  readonly sharedSecret: Buffer;
+};
+type PairM5 = {
+  /** The sealed identity of the accessory, which {@link PairSetup.m6} opens. */readonly encryptedData: Buffer;
+  readonly sessionKey: Buffer;
+};
+//#endregion
+//#region src/pairing/const.d.ts
+/** The fixed setup code of a HAP transient pair-setup. */
+declare const TRANSIENT_PAIRING_PIN = "3939";
+//#endregion
+//#region src/pairing/server.d.ts
+/**
+* Answers HAP pair-setup as the accessory, M1, M3 and M5 with M2, M4 and M6. After M5,
+* {@link controller} holds the verified controller identity to persist.
+*/
+declare class PairSetupServer {
+  #private;
+  get controller(): PairedController | undefined;
+  /** The SRP session key, available after M3. */
+  get sharedSecret(): Buffer | undefined;
+  constructor(context: Context, identity: AccessoryIdentity, pin: string, options?: PairingOptions);
+  /**
+  * Answers one pair-setup request with the next message.
+  *
+  * @throws {PairingError} If the request carries an unexpected state.
+  * @throws {AuthenticationError} If the PIN proof or the controller signature is wrong.
+  */
+  handle(request: Buffer): Promise<Buffer>;
+}
+/**
+* Answers HAP pair-verify as the accessory, M1 and M3 with M2 and M4. Once M3 verifies the
+* controller, {@link sharedSecret} feeds the channel key derivation.
+*/
+declare class PairVerifyServer {
+  #private;
+  /** The pairing identifier of the verified controller, available after M3. */
+  get pairingId(): Buffer | undefined;
+  /** The Curve25519 shared secret, available after M1. */
+  get sharedSecret(): Buffer | undefined;
+  constructor(context: Context, identity: AccessoryIdentity, resolveController: ControllerResolver, options?: PairingOptions);
+  /**
+  * Answers one pair-verify request with the next message.
+  *
+  * @throws {PairingError} If the request carries an unexpected state.
+  * @throws {AuthenticationError} If the controller is unknown or its signature is wrong.
+  */
+  handle(request: Buffer): Promise<Buffer>;
+}
+/** Generates an accessory identity with a random MAC-style identifier and a new Ed25519 key pair. */
+declare function generateAccessoryIdentity(): AccessoryIdentity;
+//#endregion
+export { type AccessoryCredentials, type AccessoryIdentity, type AccessoryKeys, type ControllerResolver, PairSetup, PairSetupServer, PairVerify, PairVerifyServer, type PairedController, type PairingOptions, type PairingStep, type PairingTransport, TRANSIENT_PAIRING_PIN, deriveControlKeys, generateAccessoryIdentity };