From d7bb7e0524e3682d32e302b9c69ce15cbb78b24e Mon Sep 17 00:00:00 2001 From: seydx Date: Tue, 15 Sep 2026 01:59:53 +0200 Subject: [PATCH 1/4] add SecureVideoController for the iOS 27 secure video camera services --- src/lib/Characteristic.ts | 135 ++ src/lib/Service.ts | 40 + src/lib/camera/CMAFIngest.spec.ts | 118 ++ src/lib/camera/CMAFIngest.ts | 418 ++++++ src/lib/camera/HDSSnapshotTransport.ts | 209 +++ src/lib/camera/RecordingManagement.ts | 11 +- src/lib/camera/SecureVideoCredentials.ts | 58 + src/lib/camera/SecureVideoTypes.spec.ts | 199 +++ src/lib/camera/SecureVideoTypes.ts | 1260 +++++++++++++++++ src/lib/camera/index.ts | 4 + .../controller/SecureVideoController.spec.ts | 257 ++++ src/lib/controller/SecureVideoController.ts | 1212 ++++++++++++++++ src/lib/controller/index.ts | 1 + .../CharacteristicDefinitions.spec.ts | 162 +++ .../definitions/CharacteristicDefinitions.ts | 490 +++++++ .../definitions/ServiceDefinitions.spec.ts | 176 +++ src/lib/definitions/ServiceDefinitions.ts | 174 +++ .../definitions/generator-configuration.ts | 323 +++++ 18 files changed, 5244 insertions(+), 3 deletions(-) create mode 100644 src/lib/camera/CMAFIngest.spec.ts create mode 100644 src/lib/camera/CMAFIngest.ts create mode 100644 src/lib/camera/HDSSnapshotTransport.ts create mode 100644 src/lib/camera/SecureVideoCredentials.ts create mode 100644 src/lib/camera/SecureVideoTypes.spec.ts create mode 100644 src/lib/camera/SecureVideoTypes.ts create mode 100644 src/lib/controller/SecureVideoController.spec.ts create mode 100644 src/lib/controller/SecureVideoController.ts diff --git a/src/lib/Characteristic.ts b/src/lib/Characteristic.ts index 75270b51d..8b3d06f8f 100644 --- a/src/lib/Characteristic.ts +++ b/src/lib/Characteristic.ts @@ -23,8 +23,20 @@ import type { AudioFeedback, BatteryLevel, Brightness, + BufferActivityCommand, + BufferEventCommand, + BufferEventSequenceNumber, + BufferUploadCommand, ButtonEvent, + CameraCapabilitiesConfiguration, + CameraClientCertificate, + CameraClientCertificateStatus, + CameraClientCSR, + CameraKey, + CameraKeyID, CameraOperatingModeIndicator, + CameraRecordingPublishingPoint, + CameraZones, CarbonDioxideDetected, CarbonDioxideLevel, CarbonDioxidePeakLevel, @@ -42,6 +54,7 @@ import type { ConfiguredName, ConnectionHealthMonitor, ContactSensorState, + ContributingSensors, CoolingThresholdTemperature, CryptoHash, CurrentAirPurifierState, @@ -111,6 +124,7 @@ import type { MetricsBufferFullState, Model, MotionDetected, + MotionEnabled, MultifunctionButton, Mute, Name, @@ -158,6 +172,7 @@ import type { RotationDirection, RotationSpeed, RouterStatus, + RTPStreamingControl, Saturation, SecuritySystemAlarmType, SecuritySystemCurrentState, @@ -168,6 +183,7 @@ import type { SelectedRTPStreamConfiguration, SelectedSessionKeepaliveConfigurationList, SelectedSleepConfiguration, + SensorUUID, SerialNumber, ServiceLabelIndex, ServiceLabelNamespace, @@ -194,11 +210,13 @@ import type { StatusJammed, StatusLowBattery, StatusTampered, + StreamingEnabled, StreamingStatus, SulphurDioxideDensity, SupportedAssetTypes, SupportedAudioRecordingConfiguration, SupportedAudioStreamConfiguration, + SupportedAudioStreamTiers, SupportedCameraRecordingConfiguration, SupportedCharacteristicValueTransitionConfiguration, SupportedDataStreamTransportConfiguration, @@ -213,6 +231,7 @@ import type { SupportedTransferTransportConfiguration, SupportedVideoRecordingConfiguration, SupportedVideoStreamConfiguration, + SupportedVideoStreamTiers, SwingMode, TapType, TargetAirPurifierState, @@ -254,6 +273,14 @@ import type { WANConfigurationList, WANStatusList, WaterLevel, + WebRTCNumberOfActiveSessions, + WebRTCProvideAnswer, + WebRTCReoffer, + WebRTCSolicitOffer, + WebRTCStreamingControl, + WebRTCSupportedAudioStreamTiers, + WebRTCSupportedVideoStreamTiers, + WebRTCUpdateSession, WiFiCapabilities, WiFiConfigurationControl, WiFiSatelliteStatus, @@ -809,14 +836,62 @@ export class Characteristic extends EventEmitter { * @group Characteristic Definitions */ public static Brightness: typeof Brightness; + /** + * @group Characteristic Definitions + */ + public static BufferActivityCommand: typeof BufferActivityCommand; + /** + * @group Characteristic Definitions + */ + public static BufferEventCommand: typeof BufferEventCommand; + /** + * @group Characteristic Definitions + */ + public static BufferEventSequenceNumber: typeof BufferEventSequenceNumber; + /** + * @group Characteristic Definitions + */ + public static BufferUploadCommand: typeof BufferUploadCommand; /** * @group Characteristic Definitions */ public static ButtonEvent: typeof ButtonEvent; + /** + * @group Characteristic Definitions + */ + public static CameraCapabilitiesConfiguration: typeof CameraCapabilitiesConfiguration; + /** + * @group Characteristic Definitions + */ + public static CameraClientCertificate: typeof CameraClientCertificate; + /** + * @group Characteristic Definitions + */ + public static CameraClientCertificateStatus: typeof CameraClientCertificateStatus; + /** + * @group Characteristic Definitions + */ + public static CameraClientCSR: typeof CameraClientCSR; + /** + * @group Characteristic Definitions + */ + public static CameraKey: typeof CameraKey; + /** + * @group Characteristic Definitions + */ + public static CameraKeyID: typeof CameraKeyID; /** * @group Characteristic Definitions */ public static CameraOperatingModeIndicator: typeof CameraOperatingModeIndicator; + /** + * @group Characteristic Definitions + */ + public static CameraRecordingPublishingPoint: typeof CameraRecordingPublishingPoint; + /** + * @group Characteristic Definitions + */ + public static CameraZones: typeof CameraZones; /** * @group Characteristic Definitions */ @@ -885,6 +960,10 @@ export class Characteristic extends EventEmitter { * @group Characteristic Definitions */ public static ContactSensorState: typeof ContactSensorState; + /** + * @group Characteristic Definitions + */ + public static ContributingSensors: typeof ContributingSensors; /** * @group Characteristic Definitions */ @@ -1161,6 +1240,10 @@ export class Characteristic extends EventEmitter { * @group Characteristic Definitions */ public static MotionDetected: typeof MotionDetected; + /** + * @group Characteristic Definitions + */ + public static MotionEnabled: typeof MotionEnabled; /** * @group Characteristic Definitions */ @@ -1352,6 +1435,10 @@ export class Characteristic extends EventEmitter { * @group Characteristic Definitions */ public static RouterStatus: typeof RouterStatus; + /** + * @group Characteristic Definitions + */ + public static RTPStreamingControl: typeof RTPStreamingControl; /** * @group Characteristic Definitions */ @@ -1392,6 +1479,10 @@ export class Characteristic extends EventEmitter { * @group Characteristic Definitions */ public static SelectedSleepConfiguration: typeof SelectedSleepConfiguration; + /** + * @group Characteristic Definitions + */ + public static SensorUUID: typeof SensorUUID; /** * @group Characteristic Definitions */ @@ -1496,6 +1587,10 @@ export class Characteristic extends EventEmitter { * @group Characteristic Definitions */ public static StatusTampered: typeof StatusTampered; + /** + * @group Characteristic Definitions + */ + public static StreamingEnabled: typeof StreamingEnabled; /** * @group Characteristic Definitions */ @@ -1516,6 +1611,10 @@ export class Characteristic extends EventEmitter { * @group Characteristic Definitions */ public static SupportedAudioStreamConfiguration: typeof SupportedAudioStreamConfiguration; + /** + * @group Characteristic Definitions + */ + public static SupportedAudioStreamTiers: typeof SupportedAudioStreamTiers; /** * @group Characteristic Definitions */ @@ -1572,6 +1671,10 @@ export class Characteristic extends EventEmitter { * @group Characteristic Definitions */ public static SupportedVideoStreamConfiguration: typeof SupportedVideoStreamConfiguration; + /** + * @group Characteristic Definitions + */ + public static SupportedVideoStreamTiers: typeof SupportedVideoStreamTiers; /** * @group Characteristic Definitions */ @@ -1742,6 +1845,38 @@ export class Characteristic extends EventEmitter { * @group Characteristic Definitions */ public static WaterLevel: typeof WaterLevel; + /** + * @group Characteristic Definitions + */ + public static WebRTCNumberOfActiveSessions: typeof WebRTCNumberOfActiveSessions; + /** + * @group Characteristic Definitions + */ + public static WebRTCProvideAnswer: typeof WebRTCProvideAnswer; + /** + * @group Characteristic Definitions + */ + public static WebRTCReoffer: typeof WebRTCReoffer; + /** + * @group Characteristic Definitions + */ + public static WebRTCSolicitOffer: typeof WebRTCSolicitOffer; + /** + * @group Characteristic Definitions + */ + public static WebRTCStreamingControl: typeof WebRTCStreamingControl; + /** + * @group Characteristic Definitions + */ + public static WebRTCSupportedAudioStreamTiers: typeof WebRTCSupportedAudioStreamTiers; + /** + * @group Characteristic Definitions + */ + public static WebRTCSupportedVideoStreamTiers: typeof WebRTCSupportedVideoStreamTiers; + /** + * @group Characteristic Definitions + */ + public static WebRTCUpdateSession: typeof WebRTCUpdateSession; /** * @group Characteristic Definitions */ diff --git a/src/lib/Service.ts b/src/lib/Service.ts index 7ef7633e7..fd9c4db85 100644 --- a/src/lib/Service.ts +++ b/src/lib/Service.ts @@ -16,9 +16,17 @@ import type { Assistant, AudioStreamManagement, Battery, + CameraBufferManagement, + CameraCapabilities, + CameraClientCertificateManagement, + CameraGlobalOperatingMode, + CameraKeyManagement, + CameraMotionZones, + CameraMultiTierRTPStreamManagement, CameraOperatingMode, CameraRecordingManagement, CameraRTPStreamManagement, + CameraWebRTCStreamManagement, CarbonDioxideSensor, CarbonMonoxideSensor, CloudRelay, @@ -212,6 +220,34 @@ export class Service extends EventEmitter { * @group Service Definitions */ public static Battery: typeof Battery; + /** + * @group Service Definitions + */ + public static CameraBufferManagement: typeof CameraBufferManagement; + /** + * @group Service Definitions + */ + public static CameraCapabilities: typeof CameraCapabilities; + /** + * @group Service Definitions + */ + public static CameraClientCertificateManagement: typeof CameraClientCertificateManagement; + /** + * @group Service Definitions + */ + public static CameraGlobalOperatingMode: typeof CameraGlobalOperatingMode; + /** + * @group Service Definitions + */ + public static CameraKeyManagement: typeof CameraKeyManagement; + /** + * @group Service Definitions + */ + public static CameraMotionZones: typeof CameraMotionZones; + /** + * @group Service Definitions + */ + public static CameraMultiTierRTPStreamManagement: typeof CameraMultiTierRTPStreamManagement; /** * @group Service Definitions */ @@ -224,6 +260,10 @@ export class Service extends EventEmitter { * @group Service Definitions */ public static CameraRTPStreamManagement: typeof CameraRTPStreamManagement; + /** + * @group Service Definitions + */ + public static CameraWebRTCStreamManagement: typeof CameraWebRTCStreamManagement; /** * @group Service Definitions */ diff --git a/src/lib/camera/CMAFIngest.spec.ts b/src/lib/camera/CMAFIngest.spec.ts new file mode 100644 index 000000000..e36978867 --- /dev/null +++ b/src/lib/camera/CMAFIngest.spec.ts @@ -0,0 +1,118 @@ +import crypto from "crypto"; +import { + buildMediaPlaylist, + buildMultivariantPlaylist, + deriveClipKey, + mapStatus, + ntpToDate, + sealSegment, + sealSessionValue, +} from "./CMAFIngest"; +import { CMAFError } from "./SecureVideoTypes"; + +const cameraKey = crypto.randomBytes(32); +const key = deriveClipKey(0x1234n, cameraKey); + +function open(sealed: Buffer): Buffer { + const iv = sealed.subarray(0, 16); + const tag = sealed.subarray(sealed.length - 16); + const decipher = crypto.createDecipheriv("aes-256-gcm", key.contentKey, iv, { authTagLength: 16 }); + decipher.setAuthTag(tag); + return Buffer.concat([decipher.update(sealed.subarray(16, sealed.length - 16)), decipher.final()]); +} + +describe("CMAFIngest", () => { + test("derives the clip key id and content key from the camera key", () => { + // key number in the upper bits, key type CMAF (1) at bit 14 + expect(key.keyIdString).toBe("0000000012344000"); + expect(key.contentKey).toHaveLength(32); + expect(key.contentKey).toEqual(Buffer.from(crypto.hkdfSync("sha256", cameraKey, Buffer.alloc(0), "HomeKit 1.0 CMAF Content", 32))); + expect(deriveClipKey(0x1234n, cameraKey).contentKey).toEqual(key.contentKey); + }); + + test("seals segments as iv, ciphertext, tag", () => { + const plaintext = crypto.randomBytes(1000); + const sealed = sealSegment(key, plaintext); + expect(sealed).toHaveLength(plaintext.length + 32); + expect(open(sealed)).toEqual(plaintext); + expect(sealSegment(key, plaintext)).not.toEqual(sealed); + }); + + test("seals session data values as base64 json", () => { + const value = JSON.parse(Buffer.from(sealSessionValue(key, "2026-09-15T00:00:00Z"), "base64").toString("utf8")); + expect(value.method).toBe("AES-256-GCM"); + expect(value.keyIDString).toBe(key.keyIdString); + const sealed = Buffer.concat([ + Buffer.from(value.initializationVector, "base64"), + Buffer.from(value.ciphertext, "base64"), + Buffer.from(value.tag, "base64"), + ]); + expect(open(sealed).toString("utf8")).toBe("2026-09-15T00:00:00Z"); + }); + + test("builds the multivariant playlist", () => { + const sensor = "6d3b7b46-8a7d-4a8f-9c5a-1f7e0f0c0b1a"; + const playlist = buildMultivariantPlaylist(key, new Date("2026-09-15T00:00:00.000Z"), sensor, { + codecs: "hvc1.1.6.L120.B0", + width: 1920, + height: 1080, + bitrate: 1700000, + }); + const lines = playlist.split("\n"); + expect(lines[0]).toBe("#EXTM3U"); + expect(lines).toContain(`#EXT-X-SESSION-KEY:METHOD=AES-256-GCM,URI="${key.keyIdString}"`); + expect(lines).toContain(`#EXT-X-SESSION-DATA:DATA-ID="com.apple.homekit.sensor-id",VALUE="${sensor}"`); + expect(lines).toContain("#EXT-X-STREAM-INF:BANDWIDTH=1700000,CODECS=\"hvc1.1.6.L120.B0\",RESOLUTION=1920x1080"); + expect(lines[lines.indexOf("#EXT-X-STREAM-INF:BANDWIDTH=1700000,CODECS=\"hvc1.1.6.L120.B0\",RESOLUTION=1920x1080") + 1]).toBe("video/index.m3u8"); + + const timestamp = lines.find(line => line.includes("com.apple.encrypted-datetime.timestamp"))!; + const value = JSON.parse(Buffer.from(/VALUE="([^"]+)"/.exec(timestamp)![1], "base64").toString("utf8")); + const sealed = Buffer.concat([ + Buffer.from(value.initializationVector, "base64"), + Buffer.from(value.ciphertext, "base64"), + Buffer.from(value.tag, "base64"), + ]); + expect(open(sealed).toString("utf8")).toBe("2026-09-15T00:00:00Z"); + }); + + test("builds the media playlist from the segment durations", () => { + const initial = buildMediaPlaylist(key, [], false).split("\n"); + expect(initial).toContain("#EXT-X-TARGETDURATION:2"); + expect(initial).toContain("#EXT-X-MEDIA-SEQUENCE:1001"); + expect(initial).toContain("#EXT-X-MAP:URI=\"video.init\""); + expect(initial).toContain(`#EXT-X-KEY:METHOD=AES-256-GCM,URI="${key.keyIdString}"`); + expect(initial.some(line => line.startsWith("#EXTINF"))).toBe(false); + expect(initial).not.toContain("#EXT-X-ENDLIST"); + + const ended = buildMediaPlaylist(key, [4, 4.5], true).split("\n"); + expect(ended).toContain("#EXT-X-TARGETDURATION:5"); + expect(ended.slice(ended.indexOf("#EXTINF:4.000,"))).toEqual([ + "#EXTINF:4.000,", + "segment_1001.m4s", + "#EXTINF:4.500,", + "segment_1002.m4s", + "#EXT-X-ENDLIST", + "", + ]); + }); + + test("maps http statuses to cmaf errors", () => { + expect(mapStatus(400)).toBe(CMAFError.HTTP_BAD_REQUEST); + expect(mapStatus(401)).toBe(CMAFError.HTTP_INVALID_TOKEN); + expect(mapStatus(403)).toBe(CMAFError.HTTP_INVALID_TOKEN); + expect(mapStatus(404)).toBe(CMAFError.HTTP_NOT_FOUND); + expect(mapStatus(412)).toBe(CMAFError.HTTP_INIT_MISSING); + expect(mapStatus(415)).toBe(CMAFError.HTTP_UNSUPPORTED_MEDIA_TYPE); + expect(mapStatus(503)).toBe(CMAFError.HTTP_SERVICE_UNAVAILABLE); + expect(mapStatus(500)).toBe(CMAFError.HTTP_INTERNAL_SERVER_ERROR); + expect(mapStatus(418)).toBe(CMAFError.UNKNOWN); + }); + + test("converts ntp timestamps", () => { + const unixSeconds = Math.floor(Date.UTC(2026, 8, 14, 14, 54, 44) / 1000); + const ntp = (BigInt(unixSeconds) + 2_208_988_800n) << 32n; + expect(ntpToDate(ntp).toISOString()).toBe("2026-09-14T14:54:44.000Z"); + expect(Math.abs(ntpToDate(undefined).getTime() - Date.now())).toBeLessThan(1000); + expect(Math.abs(ntpToDate(5n).getTime() - Date.now())).toBeLessThan(1000); + }); +}); diff --git a/src/lib/camera/CMAFIngest.ts b/src/lib/camera/CMAFIngest.ts new file mode 100644 index 000000000..cdc1c8f55 --- /dev/null +++ b/src/lib/camera/CMAFIngest.ts @@ -0,0 +1,418 @@ +import crypto from "crypto"; +import createDebug from "debug"; +import http2 from "http2"; + +import { BufferUploadCommandType, CMAFError } from "./SecureVideoTypes"; + +import type { BufferUploadCommandRequest } from "./SecureVideoTypes"; +import type { CMAFRecordingDelegate, SecureVideoIngestCredentials } from "../controller/SecureVideoController"; + +const debug = createDebug("HAP-NodeJS:SecureVideo:Ingest"); + +const TRACK_NAME = "video"; +const FIRST_SEGMENT_NUMBER = 1001; +const SEGMENT_DURATION_SECONDS = 2; +const PLAYLIST_CONTENT_TYPE = "application/vnd.apple.mpegurl"; + +// the HomeKit HomeHub derives the clip content key from the camera key with HKDF-SHA256, empty salt, and +// expects every segment as AES-256-GCM with a 16-byte IV in front and the tag behind +const CONTENT_KEY_INFO = "HomeKit 1.0 CMAF Content"; +const CONTENT_KEY_LENGTH = 32; +const KEY_TYPE_CMAF = 1n; +const IV_LENGTH = 16; +const TAG_LENGTH = 16; +const NTP_EPOCH_OFFSET_SECONDS = 2_208_988_800; + +/** + * Media description the controller advertises in the HLS multivariant playlist. + * + * @group Camera Secure Video + */ +export interface CMAFMediaDescription { + /** HLS codecs attribute, e.g. `hvc1.1.6.L120.B0` */ + codecs: string; + width: number; + height: number; + /** bits per second */ + bitrate: number; +} + +/** + * Everything the ingest needs from the controller: the negotiated credentials, the advertised media description and + * the event reporters. Keeps the credential and event handling internal to the controller. + * + * @group Camera Secure Video + */ +export interface CMAFIngestContext { + sensorUUID: string; + media: CMAFMediaDescription; + credentials(): SecureVideoIngestCredentials; + reportSessionStart(cmafSessionId: bigint): void; + /** `detail` summarizes the optional playlist requests, for logging only */ + reportSessionStop(cmafSessionId: bigint, detail?: string): void; + /** `detail` names the failed request or the transport error, for logging only */ + reportError(cmafSessionId: bigint, error: CMAFError, detail?: string): void; +} + +/** + * Content key of one clip, derived from the camera key the HomeKit HomeHub provisioned. + * + * @group Camera Secure Video + */ +export interface ClipKey { + /** key id as it appears in the HLS key URIs */ + keyIdString: string; + contentKey: Buffer; +} + +interface UploadSession { + clipId: bigint; + startedAt: Date; + abort: AbortController; + /** no further hub command is expected, the session is dropped once the upload ends */ + finalize: boolean; + /** the hub sent stop, the upload ends with the next fragment */ + stopRequested: boolean; + finished: boolean; +} + +interface PutResult { + status: number; + /** first bytes of the response body, the ingest edge explains rejections there */ + body: string; +} + +function put(client: http2.ClientHttp2Session, path: string, body: Buffer, contentType: string): Promise { + return new Promise((resolve, reject) => { + const request = client.request({ + ":method": "PUT", + ":path": path, + "content-type": contentType, + "content-length": body.length, + }); + + let status = 0; + const chunks: Buffer[] = []; + request.on("response", headers => { + status = Number(headers[":status"]); + }); + request.on("data", (chunk: Buffer) => { + chunks.push(chunk); + }); + request.on("end", () => { + const response = Buffer.concat(chunks).toString("utf8").slice(0, 512); + debug("PUT %s (%d bytes) -> %d %s", path.slice(path.indexOf("session_")), body.length, status, response); + resolve({ status, body: response }); + }); + request.on("error", reject); + request.end(body); + }); +} + +/** + * Derives the clip content key and key id from a provisioned camera key. + * + * @group Camera Secure Video + */ +export function deriveClipKey(keyNumber: bigint, cameraKey: Buffer): ClipKey { + const keyId = (keyNumber << 16n) | (KEY_TYPE_CMAF << 14n); + return { + keyIdString: keyId.toString(16).padStart(16, "0"), + contentKey: Buffer.from(crypto.hkdfSync("sha256", cameraKey, Buffer.alloc(0), CONTENT_KEY_INFO, CONTENT_KEY_LENGTH)), + }; +} + +function seal(key: ClipKey, plaintext: Buffer): { iv: Buffer, ciphertext: Buffer, tag: Buffer } { + const iv = crypto.randomBytes(IV_LENGTH); + const cipher = crypto.createCipheriv("aes-256-gcm", key.contentKey, iv, { authTagLength: TAG_LENGTH }); + const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]); + return { iv, ciphertext, tag: cipher.getAuthTag() }; +} + +/** + * Seals an fMP4 segment for upload: 16-byte IV, AES-256-GCM ciphertext, 16-byte tag. + * + * @group Camera Secure Video + */ +export function sealSegment(key: ClipKey, plaintext: Buffer): Buffer { + const { iv, ciphertext, tag } = seal(key, plaintext); + return Buffer.concat([iv, ciphertext, tag]); +} + +/** + * Seals a playlist session data value: JSON with base64 fields, itself base64 inside the VALUE attribute. + * + * @group Camera Secure Video + */ +export function sealSessionValue(key: ClipKey, plaintext: string): string { + const { iv, ciphertext, tag } = seal(key, Buffer.from(plaintext, "utf8")); + const value = { + method: "AES-256-GCM", + initializationVector: iv.toString("base64"), + ciphertext: ciphertext.toString("base64"), + tag: tag.toString("base64"), + keyIDString: key.keyIdString, + }; + return Buffer.from(JSON.stringify(value)).toString("base64"); +} + +/** + * Builds the HLS multivariant playlist of a clip. + * + * @group Camera Secure Video + */ +export function buildMultivariantPlaylist(key: ClipKey, startedAt: Date, sensorUUID: string, media: CMAFMediaDescription): string { + const timestamp = startedAt.toISOString().replace(/\.\d{3}Z$/, "Z"); + const { codecs, width, height, bitrate } = media; + return [ + "#EXTM3U", + "#EXT-X-VERSION:7", + "#EXT-X-INDEPENDENT-SEGMENTS", + `#EXT-X-SESSION-KEY:METHOD=AES-256-GCM,URI="${key.keyIdString}"`, + `#EXT-X-SESSION-DATA:DATA-ID="com.apple.encrypted-datetime.timestamp",VALUE="${sealSessionValue(key, timestamp)}"`, + `#EXT-X-SESSION-DATA:DATA-ID="com.apple.homekit.sensor-id",VALUE="${sensorUUID}"`, + `#EXT-X-STREAM-INF:BANDWIDTH=${bitrate},CODECS="${codecs}",RESOLUTION=${width}x${height}`, + `${TRACK_NAME}/index.m3u8`, + "", + ].join("\n"); +} + +/** + * Builds the HLS media playlist of a clip from the uploaded segment durations in seconds. + * + * @group Camera Secure Video + */ +export function buildMediaPlaylist(key: ClipKey, durations: number[], ended: boolean): string { + const targetDuration = Math.ceil(Math.max(SEGMENT_DURATION_SECONDS, ...durations)); + const lines = [ + "#EXTM3U", + "#EXT-X-VERSION:7", + `#EXT-X-TARGETDURATION:${targetDuration}`, + `#EXT-X-MEDIA-SEQUENCE:${FIRST_SEGMENT_NUMBER}`, + "#EXT-X-PLAYLIST-TYPE:EVENT", + "#EXT-X-INDEPENDENT-SEGMENTS", + `#EXT-X-KEY:METHOD=AES-256-GCM,URI="${key.keyIdString}"`, + `#EXT-X-MAP:URI="${TRACK_NAME}.init"`, + ]; + durations.forEach((duration, index) => { + lines.push(`#EXTINF:${duration.toFixed(3)},`, `segment_${FIRST_SEGMENT_NUMBER + index}.m4s`); + }); + if (ended) { + lines.push("#EXT-X-ENDLIST"); + } + lines.push(""); + return lines.join("\n"); +} + +/** + * Converts an NTP timestamp of the buffer upload command to a date, falling back to now. + * + * @group Camera Secure Video + */ +export function ntpToDate(ntp: bigint | undefined): Date { + if (ntp === undefined || ntp < 1n << 32n) { + return new Date(); + } + const seconds = Number(ntp >> 32n) - NTP_EPOCH_OFFSET_SECONDS; + const fraction = Number(ntp & 0xffffffffn) / 0x100000000; + return new Date((seconds + fraction) * 1000); +} + +function trailingSlash(pathname: string): string { + return pathname.endsWith("/") ? pathname : `${pathname}/`; +} + +function toPem(der: Buffer): string { + const lines = der.toString("base64").match(/.{1,64}/g) ?? []; + return `-----BEGIN CERTIFICATE-----\n${lines.join("\n")}\n-----END CERTIFICATE-----\n`; +} + +/** + * Maps a publishing point HTTP status to the CMAF error reported to the HomeKit HomeHub. + * + * @group Camera Secure Video + */ +export function mapStatus(status: number): CMAFError { + switch (status) { + case 400: + return CMAFError.HTTP_BAD_REQUEST; + case 401: + case 403: + return CMAFError.HTTP_INVALID_TOKEN; + case 404: + return CMAFError.HTTP_NOT_FOUND; + case 412: + return CMAFError.HTTP_INIT_MISSING; + case 415: + return CMAFError.HTTP_UNSUPPORTED_MEDIA_TYPE; + case 503: + return CMAFError.HTTP_SERVICE_UNAVAILABLE; + default: + return status >= 500 ? CMAFError.HTTP_INTERNAL_SERVER_ERROR : CMAFError.UNKNOWN; + } +} + +/** + * Uploads HomeKit Secure Video clips to the CMAF publishing point. The media is supplied by a {@link CMAFRecordingDelegate} + * as raw fMP4 segments; this seals them, builds the HLS playlists and PUTs everything over HTTP/2 with the client + * certificate the controller manages. + * + * @group Camera Secure Video + */ +export class CMAFIngest { + private readonly sessions = new Map(); + + constructor(private readonly delegate: CMAFRecordingDelegate, private readonly context: CMAFIngestContext) {} + + handleUploadCommand(request: BufferUploadCommandRequest): bigint { + const existing = this.sessions.get(request.sessionId); + + if (request.command === BufferUploadCommandType.STOP) { + if (existing) { + existing.finalize = true; + existing.stopRequested = true; + if (existing.finished) { + this.sessions.delete(request.sessionId); + } + return existing.clipId; + } + debug("stop for unknown session %s", request.sessionId); + return 0n; + } + + if (existing) { + return existing.clipId; + } + + const session: UploadSession = { + clipId: crypto.randomBytes(8).readBigUInt64LE(), + startedAt: ntpToDate(request.start), + abort: new AbortController(), + finalize: request.command === BufferUploadCommandType.START_AND_STOP, + stopRequested: false, + finished: false, + }; + this.sessions.set(request.sessionId, session); + + // the session ends with the hub's stop command, which may arrive after the upload itself ended + this.upload(request, session).finally(() => { + session.finished = true; + if (session.finalize) { + this.sessions.delete(request.sessionId); + } + }); + return session.clipId; + } + + destroy(): void { + for (const session of this.sessions.values()) { + session.abort.abort(); + } + this.sessions.clear(); + } + + private async upload(request: BufferUploadCommandRequest, session: UploadSession): Promise { + const cmafSessionId = request.sessionId; + const credentials = this.context.credentials(); + const { publishingPoint, privateKey, clientCertificate, ca } = credentials; + const cameraKey = credentials.keys.find(entry => entry.keyNumber === credentials.currentKeyNumber) ?? credentials.keys.at(-1); + if (!publishingPoint || !privateKey || !clientCertificate || !cameraKey) { + debug("upload ignored, ingest is not provisioned"); + this.context.reportError(cmafSessionId, CMAFError.INVALID_STATE); + return; + } + + const clipKey = deriveClipKey(cameraKey.keyNumber, cameraKey.key); + const url = new URL(publishingPoint.url); + const client = http2.connect(url.origin, { + key: privateKey, + cert: [toPem(clientCertificate), ...(ca ? [toPem(ca)] : [])].join(""), + ca: publishingPoint.serverCACertificates.map(toPem), + }); + client.on("error", error => debug("http2 session error: %s", error.message)); + + // the ingest edge routes exactly session_/index.m3u8, session_//index.m3u8, + // session_//.init and session_//segment_.m4s + const base = trailingSlash(url.pathname) + `session_${cmafSessionId}/`; + const multivariantPath = `${base}index.m3u8`; + const mediaPlaylistPath = `${base}${TRACK_NAME}/index.m3u8`; + const initPath = `${base}${TRACK_NAME}/${TRACK_NAME}.init`; + + this.context.reportSessionStart(cmafSessionId); + debug("session %s starting (clip %s, key %s)", cmafSessionId, session.clipId, cameraKey.keyNumber); + + const clip = this.delegate.streamClip({ cmafSessionId, command: request, signal: session.abort.signal }); + let index = 0; + try { + const first = await clip.next(); + if (first.done || first.value.type !== "init") { + throw new Error("delegate did not yield an init segment first"); + } + + const media = first.value.media ?? this.context.media; + const startedAt = first.value.startedAt ?? session.startedAt; + const durations: number[] = []; + const notes: string[] = []; + + if (!(await this.putChecked(cmafSessionId, client, initPath, sealSegment(clipKey, first.value.data), "video/mp4"))) { + return; + } + // DASH-IF ingest interface 1 takes the init and media segments only, the playlists are interface 2 extras the + // publishing point may reject, so their outcome is reported but does not end the upload + await this.putOptional(client, mediaPlaylistPath, Buffer.from(buildMediaPlaylist(clipKey, durations, false)), PLAYLIST_CONTENT_TYPE, notes); + const multivariant = Buffer.from(buildMultivariantPlaylist(clipKey, startedAt, this.context.sensorUUID, media)); + await this.putOptional(client, multivariantPath, multivariant, PLAYLIST_CONTENT_TYPE, notes); + + let finished = false; + for await (const segment of clip) { + if (segment.type !== "media") { + continue; + } + const segmentPath = `${base}${TRACK_NAME}/segment_${FIRST_SEGMENT_NUMBER + index}.m4s`; + if (!(await this.putChecked(cmafSessionId, client, segmentPath, sealSegment(clipKey, segment.data), "video/iso.segment"))) { + return; + } + index++; + durations.push(segment.duration ?? SEGMENT_DURATION_SECONDS); + finished = session.stopRequested || !!segment.last; + await this.putOptional(client, mediaPlaylistPath, Buffer.from(buildMediaPlaylist(clipKey, durations, finished)), PLAYLIST_CONTENT_TYPE, notes); + if (finished) { + break; + } + } + + // the generator ended on its own (source stopped or reached the stop timestamp) without a final fragment flag + if (!finished) { + await this.putOptional(client, mediaPlaylistPath, Buffer.from(buildMediaPlaylist(clipKey, durations, true)), PLAYLIST_CONTENT_TYPE, notes); + } + + this.context.reportSessionStop(cmafSessionId, notes.length ? notes.join(" | ") : undefined); + debug("session %s finished after %d segments", cmafSessionId, index); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + debug("session %s failed: %s", cmafSessionId, message); + this.context.reportError(cmafSessionId, CMAFError.CONNECTION_FAILED, message); + } finally { + await clip.return?.(undefined).catch(() => undefined); + client.close(); + } + } + + private async putOptional(client: http2.ClientHttp2Session, path: string, body: Buffer, contentType: string, notes: string[]): Promise { + const result = await put(client, path, body, contentType); + const note = `PUT ${path.slice(path.indexOf("session_"))} -> ${result.status}${result.body ? ` ${result.body}` : ""}`; + if (!notes.includes(note)) { + notes.push(note); + } + } + + private async putChecked(cmafSessionId: bigint, client: http2.ClientHttp2Session, path: string, body: Buffer, contentType: string): Promise { + const result = await put(client, path, body, contentType); + if (result.status >= 200 && result.status < 300) { + return true; + } + const detail = `PUT ${path.slice(path.indexOf("session_"))} (${body.length} bytes) -> ${result.status} ${result.body}`.trim(); + this.context.reportError(cmafSessionId, mapStatus(result.status), detail); + return false; + } +} diff --git a/src/lib/camera/HDSSnapshotTransport.ts b/src/lib/camera/HDSSnapshotTransport.ts new file mode 100644 index 000000000..568919cfa --- /dev/null +++ b/src/lib/camera/HDSSnapshotTransport.ts @@ -0,0 +1,209 @@ +import createDebug from "debug"; + +import { + DataStreamConnection, + DataStreamManagement, + GlobalEventHandler, + GlobalRequestHandler, + HDSProtocolSpecificErrorReason, + HDSStatus, + Protocols, + Topics, +} from "../datastream"; + +const debug = createDebug("HAP-NodeJS:SecureVideo:Snapshot"); + +const CHUNK_SIZE = 0x40000; +const TIMEOUT_MS = 25000; + +/** + * Produces a JPEG snapshot for the HDS `ipcamera.snapshot` relay. + * + * @group Camera Secure Video + */ +export type SecureVideoSnapshotHandler = () => Promise; + +interface SnapshotTransfer { + connection: DataStreamConnection; + streamId: number; + timer?: ReturnType; + onClose: () => void; + sent: boolean; +} + +/** + * Serves camera snapshots over the HDS `ipcamera.snapshot` data stream. iOS 27 fetches snapshots for the + * secure video camera services through this relay instead of the legacy image resource request, so the + * controller installs it on the recording data stream. The actual image is produced by the supplied handler. + * + * @group Camera Secure Video + */ +export class HDSSnapshotTransport { + private readonly transfers = new Set(); + private captureInFlight?: Promise; + + constructor( + private readonly dataStreamManagement: DataStreamManagement, + private readonly snapshot: SecureVideoSnapshotHandler, + private readonly isActive: () => boolean, + ) { + dataStreamManagement.onRequestMessage(Protocols.DATA_SEND, Topics.OPEN, this.onOpen); + dataStreamManagement.onEventMessage(Protocols.DATA_SEND, Topics.ACK, this.onAck); + dataStreamManagement.onEventMessage(Protocols.DATA_SEND, Topics.CLOSE, this.onCloseEvent); + } + + /** Removes the data stream handlers and cancels any in-flight transfers. Call when the controller is removed. */ + destroy(): void { + this.dataStreamManagement.removeRequestHandler(Protocols.DATA_SEND, Topics.OPEN, this.onOpen); + this.dataStreamManagement.removeEventHandler(Protocols.DATA_SEND, Topics.ACK, this.onAck); + this.dataStreamManagement.removeEventHandler(Protocols.DATA_SEND, Topics.CLOSE, this.onCloseEvent); + this.closeAll(); + } + + closeAll(): void { + for (const transfer of [...this.transfers]) { + this.finish(transfer, HDSProtocolSpecificErrorReason.CANCELLED); + } + } + + private readonly onOpen: GlobalRequestHandler = (connection, id, message) => { + if (message?.type === "ipcamera.snapshot") { + this.open(connection, id, message); + } + }; + + private readonly onAck: GlobalEventHandler = (connection, message) => { + const transfer = this.find(connection, message?.streamId); + if (transfer && transfer.sent && message?.endOfStream === true) { + this.finish(transfer); + } + }; + + private readonly onCloseEvent: GlobalEventHandler = (connection, message) => { + const transfer = this.find(connection, message?.streamId); + if (transfer) { + this.finish(transfer); + } + }; + + private find(connection: DataStreamConnection, streamId?: number): SnapshotTransfer | undefined { + return [...this.transfers].find(transfer => transfer.connection === connection && (streamId === undefined || transfer.streamId === streamId)); + } + + private reject(connection: DataStreamConnection, id: number, reason: HDSProtocolSpecificErrorReason): void { + connection.sendResponse(Protocols.DATA_SEND, Topics.OPEN, id, HDSStatus.PROTOCOL_SPECIFIC_ERROR, { status: reason }); + } + + // eslint-disable-next-line @typescript-eslint/no-explicit-any + private open(connection: DataStreamConnection, id: number, message: any): void { + if (message.target !== "controller" || !Number.isSafeInteger(message.streamId) || message.streamId < 0) { + this.reject(connection, id, HDSProtocolSpecificErrorReason.UNEXPECTED_FAILURE); + return; + } + if (!this.isActive()) { + this.reject(connection, id, HDSProtocolSpecificErrorReason.NOT_ALLOWED); + return; + } + if (this.find(connection, message.streamId)) { + this.reject(connection, id, HDSProtocolSpecificErrorReason.BUSY); + return; + } + + const transfer: SnapshotTransfer = { connection, streamId: message.streamId, sent: false, onClose: () => this.finish(transfer) }; + this.transfers.add(transfer); + connection.once("closed", transfer.onClose); + this.armTimeout(transfer); + + try { + connection.sendResponse(Protocols.DATA_SEND, Topics.OPEN, id, HDSStatus.SUCCESS, { status: 0 }); + } catch { + this.finish(transfer); + return; + } + + this.sendImage(transfer); + } + + private captureSnapshot(): Promise { + if (!this.captureInFlight) { + this.captureInFlight = this.snapshot().finally(() => { + this.captureInFlight = undefined; + }); + } + return this.captureInFlight; + } + + private async sendImage(transfer: SnapshotTransfer): Promise { + try { + const jpeg = await this.captureSnapshot(); + if (!this.transfers.has(transfer)) { + return; + } + if (!this.isActive()) { + this.finish(transfer, HDSProtocolSpecificErrorReason.NOT_ALLOWED); + return; + } + if (jpeg.length < 4 || jpeg[0] !== 0xff || jpeg[1] !== 0xd8) { + throw new Error("snapshot is empty or not JPEG"); + } + + for (let offset = 0, sequence = 1; offset < jpeg.length; offset += CHUNK_SIZE, sequence++) { + if (!this.transfers.has(transfer)) { + return; + } + const data = jpeg.subarray(offset, offset + CHUNK_SIZE); + const last = offset + data.length === jpeg.length; + transfer.sent = last; + transfer.connection.sendEvent(Protocols.DATA_SEND, Topics.DATA, { + streamId: transfer.streamId, + packets: [{ + data, + metadata: { + dataType: "image", + dataSequenceNumber: 1, + dataChunkSequenceNumber: sequence, + isLastDataChunk: last, + ...(sequence === 1 ? { dataTotalSize: jpeg.length } : {}), + }, + }], + endOfStream: last, + }); + if (!last) { + await new Promise(resolve => setImmediate(resolve)); + } + } + + debug("sent %d bytes (stream %d)", jpeg.length, transfer.streamId); + if (this.transfers.has(transfer)) { + this.armTimeout(transfer); + } + } catch (error) { + if (!this.transfers.has(transfer)) { + return; + } + debug("snapshot failed: %s", error instanceof Error ? error.message : error); + this.finish(transfer, HDSProtocolSpecificErrorReason.UNEXPECTED_FAILURE); + } + } + + private armTimeout(transfer: SnapshotTransfer): void { + clearTimeout(transfer.timer); + transfer.timer = setTimeout(() => this.finish(transfer, HDSProtocolSpecificErrorReason.TIMEOUT), TIMEOUT_MS); + transfer.timer.unref?.(); + } + + private finish(transfer: SnapshotTransfer, reason?: HDSProtocolSpecificErrorReason): void { + if (!this.transfers.delete(transfer)) { + return; + } + clearTimeout(transfer.timer); + transfer.connection.removeListener("closed", transfer.onClose); + if (reason !== undefined) { + try { + transfer.connection.sendEvent(Protocols.DATA_SEND, Topics.CLOSE, { streamId: transfer.streamId, reason }); + } catch { + // connection already gone + } + } + } +} diff --git a/src/lib/camera/RecordingManagement.ts b/src/lib/camera/RecordingManagement.ts index 10c660436..aa8c0c9ba 100644 --- a/src/lib/camera/RecordingManagement.ts +++ b/src/lib/camera/RecordingManagement.ts @@ -547,9 +547,14 @@ export class RecordingManagement { const target: string = message.target; const reason: string = message.reason; - if (target !== "controller" || type !== "ipcamera.recording") { - debug("[HDS %s] Received data send with unexpected target: %s or type: %d. Rejecting...", - connection.remoteAddress, target, type); + // only the recording data stream is ours; other types (e.g. the secure video "ipcamera.snapshot" relay) are + // owned by other handlers registered on the same data stream, so leave them alone instead of rejecting + if (type !== "ipcamera.recording") { + return; + } + + if (target !== "controller") { + debug("[HDS %s] Received data send with unexpected target: %s. Rejecting...", connection.remoteAddress, target); connection.sendResponse(Protocols.DATA_SEND, Topics.OPEN, id, HDSStatus.PROTOCOL_SPECIFIC_ERROR, { status: HDSProtocolSpecificErrorReason.UNEXPECTED_FAILURE, }); diff --git a/src/lib/camera/SecureVideoCredentials.ts b/src/lib/camera/SecureVideoCredentials.ts new file mode 100644 index 000000000..2479ddf07 --- /dev/null +++ b/src/lib/camera/SecureVideoCredentials.ts @@ -0,0 +1,58 @@ +import crypto, { KeyObject } from "crypto"; + +const OID_COMMON_NAME = Buffer.from([0x06, 0x03, 0x55, 0x04, 0x03]); +// 1.2.840.10045.4.3.2 +const OID_ECDSA_WITH_SHA256 = Buffer.from([0x06, 0x08, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x04, 0x03, 0x02]); + +/** + * @group Camera Secure Video + */ +export interface CameraClientCSRValue { + csr: Buffer; + nonceSignature: Buffer; +} + +function derLength(length: number): Buffer { + if (length < 0x80) { + return Buffer.from([length]); + } + const bytes: number[] = []; + for (let value = length; value > 0; value >>= 8) { + bytes.unshift(value & 0xff); + } + return Buffer.from([0x80 | bytes.length, ...bytes]); +} + +function der(tag: number, ...content: Buffer[]): Buffer { + const body = Buffer.concat(content); + return Buffer.concat([Buffer.from([tag]), derLength(body.length), body]); +} + +/** + * @group Camera Secure Video + */ +export function generateClientKey(): KeyObject { + return crypto.generateKeyPairSync("ec", { namedCurve: "prime256v1" }).privateKey; +} + +/** + * Builds a PKCS#10 certificate signing request for the given EC key and signs the controller nonce with the same key + * (ECDSA-SHA256, r and s concatenated). + * + * @group Camera Secure Video + */ +export function createClientCSR(privateKey: KeyObject, commonName: string, nonce: Buffer): CameraClientCSRValue { + const publicKey = crypto.createPublicKey(privateKey).export({ type: "spki", format: "der" }); + + const subject = der(0x30, der(0x31, der(0x30, OID_COMMON_NAME, der(0x0c, Buffer.from(commonName, "utf8"))))); + const info = der(0x30, der(0x02, Buffer.from([0x00])), subject, publicKey, der(0xa0)); + + const signature = crypto.sign("sha256", info, privateKey); + const csr = der(0x30, info, der(0x30, OID_ECDSA_WITH_SHA256), der(0x03, Buffer.from([0x00]), signature)); + + return { + csr, + // raw r and s, the hub rejects DER encoded signatures + nonceSignature: crypto.sign("sha256", nonce, { key: privateKey, dsaEncoding: "ieee-p1363" }), + }; +} diff --git a/src/lib/camera/SecureVideoTypes.spec.ts b/src/lib/camera/SecureVideoTypes.spec.ts new file mode 100644 index 000000000..bd430e0a3 --- /dev/null +++ b/src/lib/camera/SecureVideoTypes.spec.ts @@ -0,0 +1,199 @@ +import { execFileSync } from "child_process"; +import crypto from "crypto"; +import fs from "fs"; +import os from "os"; +import path from "path"; +import { + BufferEventCommandType, + BufferUploadCommandType, + BufferUploadStopAction, + CameraBufferEventType, + CameraSensorIntent, + CameraSensorType, + CameraVideoQuality, + CMAFError, + createClientCSR, + decodeBufferEventCommand, + decodeBufferEventCommandResponse, + decodeBufferUploadCommand, + decodeCameraCapabilities, + decodeCameraRecordingPublishingPoint, + decodeCameraZones, + decodeSupportedAudioStreamTiers, + decodeSupportedVideoStreamTiers, + decodeWebRTCProvideAnswer, + decodeWebRTCUpdateSession, + encodeBufferEventCommandResponse, + encodeCameraCapabilities, + encodeCameraRecordingPublishingPoint, + encodeCameraZones, + encodeSupportedAudioStreamTiers, + encodeSupportedVideoStreamTiers, + generateClientKey, + StreamTierAudioBitDepth, + StreamTierAudioCodec, + StreamTierAudioSampleRate, + StreamTierVideoCodec, + ZoneApplicationMethod, +} from "."; + +function tlv(type: number, value: Buffer | number[]): Buffer { + const data = Buffer.isBuffer(value) ? value : Buffer.from(value); + return Buffer.concat([Buffer.from([type, data.length]), data]); +} + +describe("SecureVideoTypes", () => { + test("video stream tiers round trip with delimited tier list", () => { + const value = { + codec: StreamTierVideoCodec.H265, + payloadType: 99, + tiers: [ + { identifier: 1, quality: CameraVideoQuality.HIGH, targetAverageBitrate: 2800, width: 2560, height: 1440, frameRate: 30 }, + { identifier: 2, quality: CameraVideoQuality.MEDIUM, targetAverageBitrate: 1700, width: 1920, height: 1080, frameRate: 30 }, + { identifier: 3, quality: CameraVideoQuality.LOW, targetAverageBitrate: 180, width: 640, height: 360, frameRate: 15 }, + ], + }; + + const encoded = encodeSupportedVideoStreamTiers(value); + expect(encoded.includes(Buffer.from([0x00, 0x00, 0x03]))).toBe(true); + expect(decodeSupportedVideoStreamTiers(encoded)).toEqual(value); + }); + + test("audio stream tiers round trip", () => { + const value = { + codec: StreamTierAudioCodec.OPUS, + payloadType: 110, + tiers: [{ + identifier: 1, + targetAverageBitrate: 24000, + sampleRate: StreamTierAudioSampleRate.KHZ_16, + bitDepth: StreamTierAudioBitDepth.BITS_16, + packetTime: 20, + channels: 1, + }], + }; + + expect(decodeSupportedAudioStreamTiers(encodeSupportedAudioStreamTiers(value))).toEqual(value); + }); + + test("camera capabilities round trip", () => { + const value = { + version: 1, + sensors: [{ + width: 2560, + height: 1440, + sensorUUID: crypto.randomUUID(), + type: CameraSensorType.PRIMARY, + intent: CameraSensorIntent.MAIN, + videoStreams: [1, 2].map(index => ({ + identifier: crypto.randomUUID(), + quality: index === 1 ? CameraVideoQuality.HIGH : CameraVideoQuality.LOW, + width: 640 * index, + height: 360 * index, + frameRate: 30, + averageBitrate: 180 * index, + peakBitrate: 190 * index, + })), + }], + }; + + expect(decodeCameraCapabilities(encodeCameraCapabilities(value))).toEqual(value); + }); + + test("uint64 fields keep precision beyond 2^53", () => { + const start = 0xE8F1_2345_6789_ABCDn; + const request = Buffer.concat([ + tlv(1, Buffer.from("0100000000000000", "hex")), + tlv(2, [BufferUploadCommandType.START_AND_STOP]), + tlv(3, Buffer.from(start.toString(16).padStart(16, "0"), "hex").reverse()), + tlv(4, Buffer.from((start + 5000n).toString(16).padStart(16, "0"), "hex").reverse()), + tlv(5, [BufferUploadStopAction.FINALIZE]), + ]); + + expect(decodeBufferUploadCommand(request)).toEqual({ + sessionId: 1n, + command: BufferUploadCommandType.START_AND_STOP, + start, + stop: start + 5000n, + stopAction: BufferUploadStopAction.FINALIZE, + }); + }); + + test("short integer encodings are accepted", () => { + expect(decodeBufferEventCommand(Buffer.concat([tlv(1, [BufferEventCommandType.QUERY]), tlv(2, [5]), tlv(3, [10])]))) + .toEqual({ command: BufferEventCommandType.QUERY, sequenceNumber: 5n, limit: 10n }); + }); + + test("buffer events round trip", () => { + const events = [ + { sequenceNumber: 1n, type: CameraBufferEventType.MOTION as const, active: true }, + { sequenceNumber: 2n, type: CameraBufferEventType.CMAF_SESSION_START as const, cmafSessionId: 7n }, + { sequenceNumber: 3n, type: CameraBufferEventType.CMAF_ERROR as const, cmafSessionId: 7n, error: CMAFError.HTTP_INIT_MISSING }, + { sequenceNumber: 4n, type: CameraBufferEventType.CMAF_SESSION_STOP as const, cmafSessionId: 7n }, + ]; + + expect(decodeBufferEventCommandResponse(encodeBufferEventCommandResponse(events))).toEqual(events); + expect(encodeBufferEventCommandResponse([]).length).toBe(0); + }); + + test("candidates are read as a list with and without delimiters", () => { + const sessionId = crypto.randomBytes(16); + const candidate = (text: string) => tlv(3, tlv(1, Buffer.from(text))); + const answer = Buffer.from("v=0\r\n".repeat(80)); + const sdp = Buffer.concat([tlv(2, answer.subarray(0, 255)), tlv(2, answer.subarray(255))]); + + const delimited = decodeWebRTCProvideAnswer(Buffer.concat([tlv(1, sessionId), sdp, candidate("a"), Buffer.from([0, 0]), candidate("b")])); + const packed = decodeWebRTCProvideAnswer(Buffer.concat([tlv(1, sessionId), sdp, candidate("a"), candidate("b")])); + + expect(delimited.sdpAnswer).toBe(answer.toString()); + expect(delimited.candidates.map(entry => entry.candidate)).toEqual(["a", "b"]); + expect(packed.candidates.map(entry => entry.candidate)).toEqual(["a", "b"]); + }); + + test("update session decodes keys and kids", () => { + const request = Buffer.concat([ + tlv(1, crypto.randomBytes(16)), + tlv(2, Buffer.concat([tlv(1, Buffer.alloc(16, 1)), tlv(2, [9])])), + tlv(3, tlv(1, [3])), + ]); + + const decoded = decodeWebRTCUpdateSession(request); + expect(decoded.receiveKeysToAdd).toEqual([{ key: Buffer.alloc(16, 1), kid: 9n }]); + expect(decoded.receiveKIDsToRemove).toEqual([3n]); + }); + + test("publishing point with large certificates round trip", () => { + const value = { url: "https://ingest.example.com/abc/", serverCACertificates: [crypto.randomBytes(900), crypto.randomBytes(300)] }; + expect(decodeCameraRecordingPublishingPoint(encodeCameraRecordingPublishingPoint(value))).toEqual(value); + }); + + test("camera zones round trip", () => { + const value = { + version: 2, + zones: [{ + method: ZoneApplicationMethod.INVERTED, + polygons: [{ identifier: crypto.randomUUID(), vertices: [{ x: 0, y: 0 }, { x: 2559, y: 0 }, { x: 1200, y: 1439 }] }], + }], + }; + expect(decodeCameraZones(encodeCameraZones(value))).toEqual(value); + }); + + test("client csr is a valid PKCS#10 request and the nonce signature verifies", () => { + const key = generateClientKey(); + const nonce = crypto.randomBytes(32); + const { csr, nonceSignature } = createClientCSR(key, "camera.ui test", nonce); + + expect(nonceSignature.length).toBe(64); + expect(crypto.verify("sha256", nonce, { key: crypto.createPublicKey(key), dsaEncoding: "ieee-p1363" }, nonceSignature)).toBe(true); + + const directory = fs.mkdtempSync(path.join(os.tmpdir(), "csr-")); + const file = path.join(directory, "request.der"); + fs.writeFileSync(file, csr); + try { + const output = execFileSync("openssl", ["req", "-inform", "DER", "-in", file, "-verify", "-noout", "-subject"], { stdio: "pipe" }).toString(); + expect(output).toContain("camera.ui test"); + } finally { + fs.rmSync(directory, { recursive: true, force: true }); + } + }); +}); diff --git a/src/lib/camera/SecureVideoTypes.ts b/src/lib/camera/SecureVideoTypes.ts new file mode 100644 index 000000000..d0997003d --- /dev/null +++ b/src/lib/camera/SecureVideoTypes.ts @@ -0,0 +1,1260 @@ +import * as uuid from "../util/uuid"; + +const DELIMITER = Buffer.from([0x00, 0x00]); + +/** + * @group Camera Secure Video + */ +export const CAMERA_CAPABILITIES_VERSION = "17.99"; + +/** + * @group Camera Secure Video + */ +export const enum StreamTierVideoCodec { + H264 = 1, + H265 = 2, +} + +/** + * @group Camera Secure Video + */ +export const enum StreamTierAudioCodec { + OPUS = 3, +} + +/** + * @group Camera Secure Video + */ +export const enum CameraVideoQuality { + HIGHEST = 1, + HIGH = 2, + MEDIUM = 3, + LOW = 4, +} + +/** + * @group Camera Secure Video + */ +export const enum StreamTierAudioSampleRate { + KHZ_16 = 1, + KHZ_24 = 2, + KHZ_32 = 3, + KHZ_48 = 4, +} + +/** + * @group Camera Secure Video + */ +export const enum StreamTierAudioBitDepth { + BITS_8 = 1, + BITS_16 = 2, + BITS_24 = 3, +} + +/** + * @group Camera Secure Video + */ +export const enum CameraSensorType { + UNKNOWN = 0, + PRIMARY = 1, + GENERIC = 255, +} + +/** + * @group Camera Secure Video + */ +export const enum CameraSensorIntent { + UNKNOWN = 0, + MAIN = 1, + PACKAGE = 2, + GENERIC = 255, +} + +/** + * @group Camera Secure Video + */ +export const enum RTPStreamingCommand { + END = 1, + START = 2, +} + +/** + * @group Camera Secure Video + */ +export const enum RTPStreamingStatus { + SUCCESS = 0, + UNKNOWN_SESSION_IDENTIFIER = 1, + NO_SUCH_STREAM = 2, + BUSY = 3, + ERROR = 4, +} + +/** + * @group Camera Secure Video + */ +export const enum WebRTCSolicitOfferStatus { + SUCCESS = 0, + PRIVACY_MODE_ACTIVE = 1, + ERROR = 2, +} + +/** + * @group Camera Secure Video + */ +export const enum WebRTCStreamingStatus { + SUCCESS = 0, + UNKNOWN_SESSION_IDENTIFIER = 1, + BUSY = 2, + ERROR = 3, +} + +/** + * @group Camera Secure Video + */ +export const enum WebRTCStreamingCommand { + END = 1, +} + +/** + * @group Camera Secure Video + */ +export const enum BufferUploadCommandType { + START = 1, + START_AND_STOP = 2, + STOP = 3, +} + +/** + * @group Camera Secure Video + */ +export const enum BufferUploadStopAction { + PAUSE = 1, + FINALIZE = 2, +} + +/** + * @group Camera Secure Video + */ +export const enum BufferActivity { + SHOULD_RECORD = 1, + SHOULD_NOT_RECORD = 2, +} + +/** + * @group Camera Secure Video + */ +export const enum BufferEventCommandType { + QUERY = 1, + ACKNOWLEDGE = 2, +} + +/** + * @group Camera Secure Video + */ +export const enum CameraBufferEventType { + CMAF_SESSION_START = 1, + CMAF_SESSION_STOP = 2, + MOTION = 3, + CMAF_ERROR = 4, +} + +/** + * @group Camera Secure Video + */ +export const enum CMAFError { + NONE = 0, + UNKNOWN = 1, + CANNOT_FIND_HOST = 2, + CERT_CONNECTION_FAILURE = 3, + CANNOT_CERTIFY = 4, + INVALID_STATE = 5, + REQUIRES_RETRY = 6, + NO_RESPONSE = 7, + MAX_SESSION_TIME_EXCEEDED = 8, + CANCELED = 9, + MP4_ERROR = 10, + CONNECTION_FAILED = 11, + TIMEOUT = 12, + OUT_OF_RESOURCES = 13, + INVALID_DATA = 14, + HTTP_BAD_REQUEST = 15, + HTTP_INVALID_TOKEN = 16, + HTTP_CAMERA_ZONE_DISABLED = 17, + HTTP_MISMATCHED_TOKEN = 18, + HTTP_NOT_FOUND = 19, + HTTP_INIT_MISSING = 20, + HTTP_UNSUPPORTED_MEDIA_TYPE = 21, + HTTP_BLOCKED = 22, + HTTP_CERTIFICATE_EXPIRED = 23, + HTTP_INTERNAL_SERVER_ERROR = 24, + HTTP_SERVICE_UNAVAILABLE = 25, + HTTP_CAMERA_ZONE_DOES_NOT_EXIST = 26, +} + +/** + * @group Camera Secure Video + */ +export const enum ZoneApplicationMethod { + NORMAL = 1, + INVERTED = 2, +} + +/** + * @group Camera Secure Video + */ +export interface VideoStreamTier { + identifier: number; + quality: CameraVideoQuality; + /** kbps */ + targetAverageBitrate: number; + width: number; + height: number; + frameRate: number; +} + +/** + * @group Camera Secure Video + */ +export interface SupportedVideoStreamTiersValue { + codec: StreamTierVideoCodec; + payloadType: number; + tiers: VideoStreamTier[]; +} + +/** + * @group Camera Secure Video + */ +export interface AudioStreamTier { + identifier: number; + /** bits per second */ + targetAverageBitrate: number; + sampleRate: StreamTierAudioSampleRate; + bitDepth: StreamTierAudioBitDepth; + packetTime: number; + channels: number; +} + +/** + * @group Camera Secure Video + */ +export interface SupportedAudioStreamTiersValue { + codec: StreamTierAudioCodec; + payloadType: number; + tiers: AudioStreamTier[]; +} + +/** + * @group Camera Secure Video + */ +export interface CameraVideoStreamCapability { + /** uuid string */ + identifier: string; + quality: CameraVideoQuality; + width: number; + height: number; + frameRate: number; + /** kbps */ + averageBitrate: number; + /** kbps */ + peakBitrate: number; +} + +/** + * @group Camera Secure Video + */ +export interface CameraSensorConfiguration { + width: number; + height: number; + /** uuid string */ + sensorUUID: string; + type: CameraSensorType; + intent: CameraSensorIntent; + videoStreams: CameraVideoStreamCapability[]; +} + +/** + * @group Camera Secure Video + */ +export interface CameraCapabilitiesValue { + version: number; + sensors: CameraSensorConfiguration[]; +} + +/** + * @group Camera Secure Video + */ +export interface RTPStreamingControlRequest { + sessionIdentifier: string; + command: RTPStreamingCommand; + videoTier?: number; + videoSSRC?: number; + audioTier?: number; + audioSSRC?: number; +} + +/** + * @group Camera Secure Video + */ +export interface RTPStreamAddress { + version: "ipv4" | "ipv6"; + address: string; + videoRTPPort: number; + audioRTPPort: number; +} + +/** + * @group Camera Secure Video + */ +export interface RTPSRTPParameters { + /** SRTP crypto suite, 0 = AES_CM_128_HMAC_SHA1_80 */ + cryptoSuite: number; + masterKey: Buffer; + masterSalt: Buffer; +} + +/** + * @group Camera Secure Video + */ +export interface RTPSetupEndpointsRequest { + sessionIdentifier: string; + controllerAddress: RTPStreamAddress; + video: RTPSRTPParameters; + audio: RTPSRTPParameters; +} + +/** + * @group Camera Secure Video + */ +export interface RTPSetupEndpointsResponse { + sessionIdentifier: string; + /** 0 = success, 1 = busy, 2 = error */ + status?: number; + accessoryAddress: RTPStreamAddress; + video: RTPSRTPParameters; + audio: RTPSRTPParameters; + videoSSRC: number; + audioSSRC: number; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCOfferOptions { + sframeEnabled: boolean; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCICECandidate { + candidate: string; + sdpMid?: string; + sdpMLineIndex?: number; +} + +/** + * @group Camera Secure Video + */ +export interface SFrameKeyData { + key: Buffer; + kid: bigint; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCSolicitOfferResponse { + sessionIdentifier?: string; + sdpOffer?: string; + candidates?: WebRTCICECandidate[]; + status: WebRTCSolicitOfferStatus; + sframe?: SFrameKeyData; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCProvideAnswerRequest { + sessionIdentifier: string; + sdpAnswer: string; + candidates: WebRTCICECandidate[]; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCStreamingControlRequest { + sessionIdentifier: string; + command: WebRTCStreamingCommand; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCReofferRequest { + sessionIdentifier: string; + sdpOffer: string; + options?: WebRTCOfferOptions; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCReofferResponse { + sessionIdentifier: string; + sdpAnswer?: string; + status: WebRTCStreamingStatus; + sframe?: SFrameKeyData; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCUpdateSessionRequest { + sessionIdentifier: string; + receiveKeysToAdd: SFrameKeyData[]; + receiveKIDsToRemove: bigint[]; +} + +/** + * @group Camera Secure Video + */ +export interface BufferUploadCommandRequest { + sessionId: bigint; + command: BufferUploadCommandType; + start?: bigint; + stop?: bigint; + stopAction?: BufferUploadStopAction; +} + +/** + * @group Camera Secure Video + */ +export interface BufferActivityCommandRequest { + /** NTP timestamp */ + start: bigint; + /** milliseconds */ + duration: bigint; + activity: BufferActivity; +} + +/** + * @group Camera Secure Video + */ +export interface BufferEventCommandRequest { + command: BufferEventCommandType; + sequenceNumber?: bigint; + limit?: bigint; +} + +/** + * @group Camera Secure Video + */ +export type CameraBufferEvent = + | { sequenceNumber: bigint, type: CameraBufferEventType.CMAF_SESSION_START, cmafSessionId: bigint } + | { sequenceNumber: bigint, type: CameraBufferEventType.CMAF_SESSION_STOP, cmafSessionId: bigint } + | { sequenceNumber: bigint, type: CameraBufferEventType.MOTION, active: boolean } + | { sequenceNumber: bigint, type: CameraBufferEventType.CMAF_ERROR, cmafSessionId: bigint, error: CMAFError }; + +/** + * @group Camera Secure Video + */ +export interface CameraRecordingPublishingPointValue { + url: string; + /** DER encoded */ + serverCACertificates: Buffer[]; +} + +/** + * @group Camera Secure Video + */ +export interface CameraKeyValue { + key: Buffer; + keyNumber: bigint; +} + +/** + * @group Camera Secure Video + */ +export interface CameraClientCertificateValue { + /** DER encoded */ + clientCertificate: Buffer; + /** DER encoded */ + ca?: Buffer; +} + +/** + * @group Camera Secure Video + */ +export interface CameraZonePolygon { + /** uuid string */ + identifier: string; + vertices: { x: number, y: number }[]; +} + +/** + * @group Camera Secure Video + */ +export interface CameraZoneData { + method: ZoneApplicationMethod; + polygons: CameraZonePolygon[]; +} + +/** + * @group Camera Secure Video + */ +export interface CameraZonesValue { + version: number; + zones: CameraZoneData[]; +} + +function readUIntLE(buffer: Buffer): bigint { + let result = 0n; + for (let i = buffer.length - 1; i >= 0; i--) { + result = (result << 8n) | BigInt(buffer[i]); + } + return result; +} + +interface TLVEntry { + type: number; + value: Buffer; + afterDelimiter: boolean; +} + +class TLVReader { + private readonly entries: TLVEntry[] = []; + + constructor(buffer: Buffer) { + let index = 0; + let afterDelimiter = false; + let last: (TLVEntry & { lastLength: number }) | undefined; + + while (index < buffer.length) { + if (index + 2 > buffer.length) { + throw new Error("TLV decode failure: incomplete type/length header"); + } + const type = buffer[index]; + const length = buffer[index + 1]; + if (index + 2 + length > buffer.length) { + throw new Error(`TLV decode failure: declared length ${length} exceeds remaining buffer`); + } + const value = buffer.subarray(index + 2, index + 2 + length); + index += 2 + length; + + if (type === 0 && length === 0) { + afterDelimiter = true; + continue; + } + + // a full 255 byte fragment continues into the next entry of the same type + if (last && !afterDelimiter && last.type === type && last.lastLength === 255) { + last.value = Buffer.concat([last.value, value]); + last.lastLength = length; + continue; + } + + last = { type, value, afterDelimiter, lastLength: length }; + this.entries.push(last); + afterDelimiter = false; + } + } + + public has(type: number): boolean { + return this.entries.some(entry => entry.type === type); + } + + public buffer(type: number): Buffer | undefined { + return this.entries.find(entry => entry.type === type)?.value; + } + + public buffers(type: number): Buffer[] { + return this.entries.filter(entry => entry.type === type).map(entry => entry.value); + } + + public string(type: number): string | undefined { + return this.buffer(type)?.toString("utf8"); + } + + public number(type: number): number | undefined { + const value = this.buffer(type); + return value && value.length ? Number(readUIntLE(value)) : undefined; + } + + public bigint(type: number): bigint | undefined { + const value = this.buffer(type); + return value && value.length ? readUIntLE(value) : undefined; + } + + public boolean(type: number): boolean | undefined { + const value = this.buffer(type); + return value && value.length ? value[0] !== 0 : undefined; + } + + public uuid(type: number): string | undefined { + const value = this.buffer(type); + return value && value.length === 16 ? uuid.unparse(value) : undefined; + } + + public required(value: T | undefined, name: string): T { + if (value === undefined) { + throw new Error(`TLV decode failure: missing ${name}`); + } + return value; + } +} + +function item(type: number, value: Buffer | undefined): Buffer { + if (value === undefined) { + return Buffer.alloc(0); + } + + const parts: Buffer[] = []; + let offset = 0; + do { + const chunk = value.subarray(offset, offset + 255); + parts.push(Buffer.from([type, chunk.length]), chunk); + offset += 255; + } while (offset < value.length); + return Buffer.concat(parts); +} + +function list(type: number, values: Buffer[]): Buffer { + const parts: Buffer[] = []; + values.forEach((value, index) => { + if (index > 0) { + parts.push(DELIMITER); + } + parts.push(item(type, value)); + }); + return Buffer.concat(parts); +} + +function u8(value: number): Buffer { + return Buffer.from([value & 0xff]); +} + +function u16(value: number): Buffer { + const buffer = Buffer.alloc(2); + buffer.writeUInt16LE(value); + return buffer; +} + +function u32(value: number): Buffer { + const buffer = Buffer.alloc(4); + buffer.writeUInt32LE(value >>> 0); + return buffer; +} + +function u64(value: bigint): Buffer { + const buffer = Buffer.alloc(8); + buffer.writeBigUInt64LE(BigInt.asUintN(64, value)); + return buffer; +} + +function bool(value: boolean): Buffer { + return Buffer.from([value ? 1 : 0]); +} + +function str(value: string | undefined): Buffer | undefined { + return value === undefined ? undefined : Buffer.from(value, "utf8"); +} + +function uuidBuffer(value: string): Buffer { + return uuid.write(value); +} + +/** + * @group Camera Secure Video + */ +export function encodeSupportedVideoStreamTiers(value: SupportedVideoStreamTiersValue): Buffer { + return Buffer.concat([ + item(1, u8(value.codec)), + item(2, u8(value.payloadType)), + list(3, value.tiers.map(tier => Buffer.concat([ + item(1, u32(tier.identifier)), + item(2, u8(tier.quality)), + item(3, u32(tier.targetAverageBitrate)), + item(4, u16(tier.width)), + item(5, u16(tier.height)), + item(6, u8(tier.frameRate)), + ]))), + ]); +} + +/** + * @group Camera Secure Video + */ +export function decodeSupportedVideoStreamTiers(buffer: Buffer): SupportedVideoStreamTiersValue { + const reader = new TLVReader(buffer); + return { + codec: reader.required(reader.number(1), "codec"), + payloadType: reader.required(reader.number(2), "payload type"), + tiers: reader.buffers(3).map(entry => { + const tier = new TLVReader(entry); + return { + identifier: tier.required(tier.number(1), "tier identifier"), + quality: tier.required(tier.number(2), "tier quality"), + targetAverageBitrate: tier.required(tier.number(3), "tier bitrate"), + width: tier.required(tier.number(4), "tier width"), + height: tier.required(tier.number(5), "tier height"), + frameRate: tier.required(tier.number(6), "tier frame rate"), + }; + }), + }; +} + +/** + * @group Camera Secure Video + */ +export function encodeSupportedAudioStreamTiers(value: SupportedAudioStreamTiersValue): Buffer { + return Buffer.concat([ + item(1, u8(value.codec)), + item(2, u8(value.payloadType)), + list(3, value.tiers.map(tier => Buffer.concat([ + item(1, u32(tier.identifier)), + item(2, u32(tier.targetAverageBitrate)), + item(3, u8(tier.sampleRate)), + item(4, u8(tier.bitDepth)), + item(5, u8(tier.packetTime)), + item(6, u8(tier.channels)), + ]))), + ]); +} + +/** + * @group Camera Secure Video + */ +export function decodeSupportedAudioStreamTiers(buffer: Buffer): SupportedAudioStreamTiersValue { + const reader = new TLVReader(buffer); + return { + codec: reader.required(reader.number(1), "codec"), + payloadType: reader.required(reader.number(2), "payload type"), + tiers: reader.buffers(3).map(entry => { + const tier = new TLVReader(entry); + return { + identifier: tier.required(tier.number(1), "tier identifier"), + targetAverageBitrate: tier.required(tier.number(2), "tier bitrate"), + sampleRate: tier.required(tier.number(3), "tier sample rate"), + bitDepth: tier.required(tier.number(4), "tier bit depth"), + packetTime: tier.required(tier.number(5), "tier packet time"), + channels: tier.required(tier.number(6), "tier channels"), + }; + }), + }; +} + +/** + * @group Camera Secure Video + */ +export function encodeCameraCapabilities(value: CameraCapabilitiesValue): Buffer { + const sensors = value.sensors.map(sensor => Buffer.concat([ + item(1, Buffer.concat([item(1, u16(sensor.width)), item(2, u16(sensor.height))])), + item(2, uuidBuffer(sensor.sensorUUID)), + item(3, u8(sensor.type)), + item(4, u8(sensor.intent)), + list(5, sensor.videoStreams.map(stream => Buffer.concat([ + item(1, uuidBuffer(stream.identifier)), + item(2, u8(stream.quality)), + item(3, u16(stream.width)), + item(4, u16(stream.height)), + item(5, u8(stream.frameRate)), + item(6, u32(stream.averageBitrate)), + item(7, u32(stream.peakBitrate)), + ]))), + ])); + + return Buffer.concat([ + item(1, u8(value.version)), + item(2, list(1, sensors)), + ]); +} + +/** + * @group Camera Secure Video + */ +export function decodeCameraCapabilities(buffer: Buffer): CameraCapabilitiesValue { + const reader = new TLVReader(buffer); + const sensors = new TLVReader(reader.buffer(2) ?? Buffer.alloc(0)); + return { + version: reader.required(reader.number(1), "version"), + sensors: sensors.buffers(1).map(entry => { + const sensor = new TLVReader(entry); + const dimensions = new TLVReader(sensor.required(sensor.buffer(1), "sensor dimensions")); + return { + width: dimensions.required(dimensions.number(1), "sensor width"), + height: dimensions.required(dimensions.number(2), "sensor height"), + sensorUUID: sensor.required(sensor.uuid(2), "sensor uuid"), + type: sensor.number(3) ?? CameraSensorType.UNKNOWN, + intent: sensor.number(4) ?? CameraSensorIntent.UNKNOWN, + videoStreams: sensor.buffers(5).map(streamEntry => { + const stream = new TLVReader(streamEntry); + return { + identifier: stream.required(stream.uuid(1), "stream identifier"), + quality: stream.required(stream.number(2), "stream quality"), + width: stream.required(stream.number(3), "stream width"), + height: stream.required(stream.number(4), "stream height"), + frameRate: stream.required(stream.number(5), "stream frame rate"), + averageBitrate: stream.required(stream.number(6), "stream average bitrate"), + peakBitrate: stream.required(stream.number(7), "stream peak bitrate"), + }; + }), + }; + }), + }; +} + +/** + * @group Camera Secure Video + */ +export function encodeContributingSensors(sensorUUIDs: string[]): Buffer { + return list(1, sensorUUIDs.map(sensorUUID => item(1, uuidBuffer(sensorUUID)))); +} + +/** + * @group Camera Secure Video + */ +export function encodeSensorUUID(sensorUUID: string): Buffer { + return uuidBuffer(sensorUUID); +} + +/** + * @group Camera Secure Video + */ +export function decodeRTPStreamingControl(buffer: Buffer): RTPStreamingControlRequest { + const reader = new TLVReader(buffer); + return { + sessionIdentifier: reader.required(reader.uuid(1), "session identifier"), + command: reader.required(reader.number(2), "command"), + videoTier: reader.number(3), + videoSSRC: reader.number(4), + audioTier: reader.number(5), + audioSSRC: reader.number(6), + }; +} + +/** + * @group Camera Secure Video + */ +export function encodeSessionStatus(sessionIdentifier: string | undefined, status: number): Buffer { + return Buffer.concat([ + sessionIdentifier ? item(1, uuidBuffer(sessionIdentifier)) : Buffer.alloc(0), + item(2, u8(status)), + ]); +} + +function decodeRTPAddress(buffer: Buffer): RTPStreamAddress { + const reader = new TLVReader(buffer); + return { + version: reader.number(1) === 1 ? "ipv6" : "ipv4", + address: reader.required(reader.string(2), "address"), + videoRTPPort: reader.required(reader.number(3), "video rtp port"), + audioRTPPort: reader.required(reader.number(4), "audio rtp port"), + }; +} + +function encodeRTPAddress(address: RTPStreamAddress): Buffer { + return Buffer.concat([ + item(1, u8(address.version === "ipv6" ? 1 : 0)), + item(2, str(address.address)), + item(3, u16(address.videoRTPPort)), + item(4, u16(address.audioRTPPort)), + ]); +} + +function decodeSRTPParameters(buffer: Buffer): RTPSRTPParameters { + const reader = new TLVReader(buffer); + return { + cryptoSuite: reader.number(1) ?? 0, + masterKey: reader.buffer(2) ?? Buffer.alloc(0), + masterSalt: reader.buffer(3) ?? Buffer.alloc(0), + }; +} + +function encodeSRTPParameters(parameters: RTPSRTPParameters): Buffer { + return Buffer.concat([ + item(1, u8(parameters.cryptoSuite)), + item(2, parameters.masterKey), + item(3, parameters.masterSalt), + ]); +} + +/** + * The multi-tier RTP Setup Endpoints characteristic reuses the same TLV as the legacy HAP Setup Endpoints. + * + * @group Camera Secure Video + */ +export function decodeRTPSetupEndpoints(buffer: Buffer): RTPSetupEndpointsRequest { + const reader = new TLVReader(buffer); + return { + sessionIdentifier: reader.required(reader.uuid(1), "session identifier"), + controllerAddress: decodeRTPAddress(reader.required(reader.buffer(3), "controller address")), + video: decodeSRTPParameters(reader.required(reader.buffer(4), "video srtp parameters")), + audio: decodeSRTPParameters(reader.required(reader.buffer(5), "audio srtp parameters")), + }; +} + +/** + * @group Camera Secure Video + */ +export function encodeRTPSetupEndpointsResponse(response: RTPSetupEndpointsResponse): Buffer { + return Buffer.concat([ + item(1, uuidBuffer(response.sessionIdentifier)), + item(2, u8(response.status ?? 0)), + item(3, encodeRTPAddress(response.accessoryAddress)), + item(4, encodeSRTPParameters(response.video)), + item(5, encodeSRTPParameters(response.audio)), + item(6, u32(response.videoSSRC)), + item(7, u32(response.audioSSRC)), + ]); +} + +function decodeOfferOptions(buffer: Buffer | undefined): WebRTCOfferOptions | undefined { + if (!buffer) { + return undefined; + } + return { sframeEnabled: new TLVReader(buffer).boolean(1) ?? false }; +} + +function encodeCandidate(candidate: WebRTCICECandidate): Buffer { + return Buffer.concat([ + item(1, str(candidate.candidate)), + item(2, str(candidate.sdpMid)), + candidate.sdpMLineIndex !== undefined ? item(3, u16(candidate.sdpMLineIndex)) : Buffer.alloc(0), + ]); +} + +function decodeCandidate(buffer: Buffer): WebRTCICECandidate { + const reader = new TLVReader(buffer); + return { + candidate: reader.required(reader.string(1), "candidate"), + sdpMid: reader.string(2), + sdpMLineIndex: reader.number(3), + }; +} + +function encodeSFrameKey(key: SFrameKeyData): Buffer { + return Buffer.concat([item(1, key.key), item(2, u64(key.kid))]); +} + +function decodeSFrameKey(buffer: Buffer): SFrameKeyData { + const reader = new TLVReader(buffer); + return { + key: reader.required(reader.buffer(1), "sframe key"), + kid: reader.required(reader.bigint(2), "sframe kid"), + }; +} + +/** + * @group Camera Secure Video + */ +export function decodeWebRTCSolicitOffer(buffer: Buffer): WebRTCOfferOptions { + const reader = new TLVReader(buffer); + return decodeOfferOptions(reader.buffer(1)) ?? { sframeEnabled: false }; +} + +/** + * @group Camera Secure Video + */ +export function encodeWebRTCSolicitOfferResponse(value: WebRTCSolicitOfferResponse): Buffer { + return Buffer.concat([ + value.sessionIdentifier ? item(1, uuidBuffer(value.sessionIdentifier)) : Buffer.alloc(0), + item(2, str(value.sdpOffer)), + list(3, (value.candidates ?? []).map(encodeCandidate)), + item(4, u8(value.status)), + value.sframe ? item(5, encodeSFrameKey(value.sframe)) : Buffer.alloc(0), + ]); +} + +/** + * @group Camera Secure Video + */ +export function decodeWebRTCProvideAnswer(buffer: Buffer): WebRTCProvideAnswerRequest { + const reader = new TLVReader(buffer); + return { + sessionIdentifier: reader.required(reader.uuid(1), "session identifier"), + sdpAnswer: reader.required(reader.string(2), "sdp answer"), + candidates: reader.buffers(3).map(decodeCandidate), + }; +} + +/** + * @group Camera Secure Video + */ +export function decodeWebRTCStreamingControl(buffer: Buffer): WebRTCStreamingControlRequest { + const reader = new TLVReader(buffer); + return { + sessionIdentifier: reader.required(reader.uuid(1), "session identifier"), + command: reader.required(reader.number(2), "command"), + }; +} + +/** + * @group Camera Secure Video + */ +export function decodeWebRTCReoffer(buffer: Buffer): WebRTCReofferRequest { + const reader = new TLVReader(buffer); + return { + sessionIdentifier: reader.required(reader.uuid(1), "session identifier"), + sdpOffer: reader.required(reader.string(2), "sdp offer"), + options: decodeOfferOptions(reader.buffer(3)), + }; +} + +/** + * @group Camera Secure Video + */ +export function encodeWebRTCReofferResponse(value: WebRTCReofferResponse): Buffer { + return Buffer.concat([ + item(1, uuidBuffer(value.sessionIdentifier)), + item(2, str(value.sdpAnswer)), + item(3, u8(value.status)), + value.sframe ? item(4, encodeSFrameKey(value.sframe)) : Buffer.alloc(0), + ]); +} + +/** + * @group Camera Secure Video + */ +export function decodeWebRTCUpdateSession(buffer: Buffer): WebRTCUpdateSessionRequest { + const reader = new TLVReader(buffer); + return { + sessionIdentifier: reader.required(reader.uuid(1), "session identifier"), + receiveKeysToAdd: reader.buffers(2).map(decodeSFrameKey), + receiveKIDsToRemove: reader.buffers(3).map(entry => { + const kid = new TLVReader(entry); + return kid.required(kid.bigint(1), "sframe kid"); + }), + }; +} + +/** + * @group Camera Secure Video + */ +export function decodeBufferUploadCommand(buffer: Buffer): BufferUploadCommandRequest { + const reader = new TLVReader(buffer); + return { + sessionId: reader.required(reader.bigint(1), "session id"), + command: reader.required(reader.number(2), "command"), + start: reader.bigint(3), + stop: reader.bigint(4), + stopAction: reader.number(5), + }; +} + +/** + * @group Camera Secure Video + */ +export function encodeBufferUploadCommandResponse(clipId: bigint): Buffer { + return item(1, u64(clipId)); +} + +/** + * @group Camera Secure Video + */ +export function decodeBufferActivityCommand(buffer: Buffer): BufferActivityCommandRequest { + const reader = new TLVReader(buffer); + return { + start: reader.required(reader.bigint(1), "start"), + duration: reader.required(reader.bigint(2), "duration"), + activity: reader.required(reader.number(3), "activity"), + }; +} + +/** + * @group Camera Secure Video + */ +export function decodeBufferEventCommand(buffer: Buffer): BufferEventCommandRequest { + const reader = new TLVReader(buffer); + return { + command: reader.required(reader.number(1), "command"), + sequenceNumber: reader.bigint(2), + limit: reader.bigint(3), + }; +} + +/** + * @group Camera Secure Video + */ +export function encodeBufferEventCommandResponse(events: CameraBufferEvent[]): Buffer { + return list(1, events.map(event => { + let payload: Buffer; + switch (event.type) { + case CameraBufferEventType.CMAF_SESSION_START: + payload = item(3, item(1, u64(event.cmafSessionId))); + break; + case CameraBufferEventType.CMAF_SESSION_STOP: + payload = item(4, item(1, u64(event.cmafSessionId))); + break; + case CameraBufferEventType.MOTION: + payload = item(5, item(1, bool(event.active))); + break; + case CameraBufferEventType.CMAF_ERROR: + payload = item(6, Buffer.concat([item(1, u64(event.cmafSessionId)), item(2, u8(event.error))])); + break; + } + return Buffer.concat([item(1, u64(event.sequenceNumber)), item(2, u8(event.type)), payload]); + })); +} + +/** + * @group Camera Secure Video + */ +export function decodeBufferEventCommandResponse(buffer: Buffer): CameraBufferEvent[] { + const reader = new TLVReader(buffer); + return reader.buffers(1).map(entry => { + const event = new TLVReader(entry); + const sequenceNumber = event.required(event.bigint(1), "sequence number"); + const type: CameraBufferEventType = event.required(event.number(2), "event type"); + switch (type) { + case CameraBufferEventType.CMAF_SESSION_START: + case CameraBufferEventType.CMAF_SESSION_STOP: { + const session = new TLVReader(event.required(event.buffer(type === CameraBufferEventType.CMAF_SESSION_START ? 3 : 4), "cmaf session")); + return { sequenceNumber, type, cmafSessionId: session.required(session.bigint(1), "cmaf session id") }; + } + case CameraBufferEventType.MOTION: { + const motion = new TLVReader(event.required(event.buffer(5), "motion")); + return { sequenceNumber, type, active: motion.boolean(1) ?? false }; + } + case CameraBufferEventType.CMAF_ERROR: { + const error = new TLVReader(event.required(event.buffer(6), "cmaf error")); + return { + sequenceNumber, + type, + cmafSessionId: error.required(error.bigint(1), "cmaf session id"), + error: error.number(2) ?? CMAFError.UNKNOWN, + }; + } + default: + throw new Error(`TLV decode failure: unknown buffer event type ${type}`); + } + }); +} + +/** + * @group Camera Secure Video + */ +export function encodeCameraRecordingPublishingPoint(value: CameraRecordingPublishingPointValue): Buffer { + return Buffer.concat([ + item(1, str(value.url)), + list(2, value.serverCACertificates.map(certificate => item(1, certificate))), + ]); +} + +/** + * @group Camera Secure Video + */ +export function decodeCameraRecordingPublishingPoint(buffer: Buffer): CameraRecordingPublishingPointValue { + const reader = new TLVReader(buffer); + return { + url: reader.required(reader.string(1), "url"), + serverCACertificates: reader.buffers(2) + .map(entry => new TLVReader(entry).buffer(1)) + .filter((certificate): certificate is Buffer => !!certificate), + }; +} + +/** + * @group Camera Secure Video + */ +export function decodeCameraKey(buffer: Buffer): CameraKeyValue { + const reader = new TLVReader(buffer); + return { + key: reader.required(reader.buffer(1), "key"), + keyNumber: reader.required(reader.bigint(2), "key number"), + }; +} + +/** + * @group Camera Secure Video + */ +export function encodeCameraKeyID(keyId: bigint): Buffer { + return item(1, u64(keyId)); +} + +/** + * @group Camera Secure Video + */ +export function decodeCameraClientCSRRequest(buffer: Buffer): Buffer { + const reader = new TLVReader(buffer); + return reader.required(reader.buffer(1), "nonce"); +} + +/** + * @group Camera Secure Video + */ +export function encodeCameraClientCSRResponse(csr: Buffer, nonceSignature: Buffer): Buffer { + return Buffer.concat([item(1, csr), item(2, nonceSignature)]); +} + +/** + * @group Camera Secure Video + */ +export function encodeCameraClientCertificate(value: CameraClientCertificateValue): Buffer { + return Buffer.concat([item(1, value.clientCertificate), item(2, value.ca)]); +} + +/** + * @group Camera Secure Video + */ +export function decodeCameraClientCertificate(buffer: Buffer): CameraClientCertificateValue { + const reader = new TLVReader(buffer); + return { + clientCertificate: reader.required(reader.buffer(1), "client certificate"), + ca: reader.buffer(2), + }; +} + +/** + * @group Camera Secure Video + */ +export function encodeCameraClientCertificateStatus(needsUpdate: boolean): Buffer { + return item(1, bool(needsUpdate)); +} + +/** + * @group Camera Secure Video + */ +export function encodeCameraZones(value: CameraZonesValue): Buffer { + const zones = value.zones.map(zone => Buffer.concat([ + item(1, u8(zone.method)), + list(3, zone.polygons.map(polygon => { + const vertices = Buffer.alloc(polygon.vertices.length * 4); + polygon.vertices.forEach((vertex, index) => { + vertices.writeUInt16LE(vertex.x, index * 4); + vertices.writeUInt16LE(vertex.y, index * 4 + 2); + }); + return Buffer.concat([item(1, uuidBuffer(polygon.identifier)), item(3, vertices)]); + })), + ])); + + return Buffer.concat([ + item(1, u8(value.version)), + list(2, zones), + ]); +} + +/** + * @group Camera Secure Video + */ +export function decodeCameraZones(buffer: Buffer): CameraZonesValue { + const reader = new TLVReader(buffer); + return { + version: reader.required(reader.number(1), "zone data version"), + zones: reader.buffers(2).map(entry => { + const zone = new TLVReader(entry); + return { + method: zone.number(1) ?? ZoneApplicationMethod.NORMAL, + polygons: zone.buffers(3).map(polygonEntry => { + const polygon = new TLVReader(polygonEntry); + const vertexData = polygon.buffer(3) ?? Buffer.alloc(0); + const vertices: { x: number, y: number }[] = []; + for (let offset = 0; offset + 4 <= vertexData.length; offset += 4) { + vertices.push({ x: vertexData.readUInt16LE(offset), y: vertexData.readUInt16LE(offset + 2) }); + } + return { identifier: polygon.uuid(1) ?? "", vertices }; + }), + }; + }), + }; +} diff --git a/src/lib/camera/index.ts b/src/lib/camera/index.ts index 341a0ce87..8af7d1b12 100644 --- a/src/lib/camera/index.ts +++ b/src/lib/camera/index.ts @@ -1,3 +1,7 @@ +export * from "./CMAFIngest"; +export * from "./HDSSnapshotTransport"; export * from "./RTPProxy"; export * from "./RTPStreamManagement"; export * from "./RecordingManagement"; +export * from "./SecureVideoCredentials"; +export * from "./SecureVideoTypes"; diff --git a/src/lib/controller/SecureVideoController.spec.ts b/src/lib/controller/SecureVideoController.spec.ts new file mode 100644 index 000000000..241990669 --- /dev/null +++ b/src/lib/controller/SecureVideoController.spec.ts @@ -0,0 +1,257 @@ +import crypto from "crypto"; +import { + AudioRecordingCodecType, + AudioRecordingSamplerate, + BufferEventCommandType, + CameraBufferEventType, + CameraRecordingOptions, + CameraVideoQuality, + decodeBufferEventCommandResponse, + H264Level, + H264Profile, + MediaContainerType, + StreamTierVideoCodec, + VideoCodecType, + WebRTCSolicitOfferStatus, + WebRTCStreamingStatus, +} from "../camera"; +import { Accessory } from "../Accessory"; +import { Characteristic } from "../Characteristic"; +import "../definitions"; +import { Service } from "../Service"; +import * as uuid from "../util/uuid"; +import { CameraRecordingDelegate } from "./CameraController"; +import { MultiTierRTPStreamingDelegate, SecureVideoController, SecureVideoControllerOptions, WebRTCStreamingDelegate } from "./SecureVideoController"; + +const recordingOptions: CameraRecordingOptions = { + prebufferLength: 4000, + mediaContainerConfiguration: { type: MediaContainerType.FRAGMENTED_MP4, fragmentLength: 4000 }, + video: { + type: VideoCodecType.H264, + parameters: { profiles: [H264Profile.MAIN], levels: [H264Level.LEVEL4_0] }, + resolutions: [[1920, 1080, 30]], + }, + audio: { codecs: [{ type: AudioRecordingCodecType.AAC_LC, samplerate: AudioRecordingSamplerate.KHZ_32 }] }, +}; + +const recordingDelegate: CameraRecordingDelegate = { + updateRecordingActive: () => undefined, + updateRecordingConfiguration: () => undefined, + // eslint-disable-next-line require-yield + handleRecordingStreamRequest: async function* () { + return; + }, + closeRecordingStream: () => undefined, +}; + +function tlv(type: number, value: Buffer | number[]): Buffer { + const data = Buffer.isBuffer(value) ? value : Buffer.from(value); + return Buffer.concat([Buffer.from([type, data.length]), data]); +} + +function parse(value: unknown): Record { + const buffer = Buffer.from(String(value), "base64"); + const result: Record = {}; + for (let index = 0; index < buffer.length; index += 2 + buffer[index + 1]) { + result[buffer[index]] = buffer.subarray(index + 2, index + 2 + buffer[index + 1]); + } + return result; +} + +describe("SecureVideoController", () => { + let accessory: Accessory; + let controller: SecureVideoController; + let webrtc: jest.Mocked; + let rtp: jest.Mocked; + + beforeEach(() => { + webrtc = { + handleSolicitOffer: jest.fn().mockResolvedValue({ sdpOffer: "v=0", candidates: [{ candidate: "candidate:1 1 udp 1 10.0.0.2 5000 typ host" }] }), + handleProvideAnswer: jest.fn().mockResolvedValue(undefined), + handleReoffer: jest.fn().mockResolvedValue({ sdpAnswer: "v=0" }), + handleUpdateSession: jest.fn().mockResolvedValue(undefined), + handleEndSession: jest.fn().mockResolvedValue(undefined), + }; + rtp = { + prepareStream: jest.fn().mockResolvedValue({ videoSSRC: 1, audioSSRC: 2 }), + startStream: jest.fn().mockResolvedValue(undefined), + stopStream: jest.fn().mockResolvedValue(undefined), + }; + + const options: SecureVideoControllerOptions = { + sensor: { uuid: uuid.generate("sensor"), width: 1920, height: 1080 }, + video: { + codec: StreamTierVideoCodec.H265, + tiers: [ + { identifier: 1, quality: CameraVideoQuality.HIGH, targetAverageBitrate: 1700, peakBitrate: 1800, width: 1920, height: 1080, frameRate: 30 }, + { identifier: 2, quality: CameraVideoQuality.MEDIUM, targetAverageBitrate: 768, peakBitrate: 800, width: 1280, height: 720, frameRate: 30 }, + { identifier: 3, quality: CameraVideoQuality.LOW, targetAverageBitrate: 180, peakBitrate: 190, width: 640, height: 360, frameRate: 15 }, + ], + }, + webrtc: { delegate: webrtc, maxSessions: 1 }, + rtp: { delegate: rtp }, + recording: { options: recordingOptions, delegate: recordingDelegate }, + ingest: { + delegate: { + // eslint-disable-next-line require-yield + streamClip: async function* () { + return; + }, + }, + }, + }; + + accessory = new Accessory("Camera", uuid.generate("camera")); + controller = new SecureVideoController(options); + accessory.configureController(controller); + }); + + test("adds all services from the guide", () => { + for (const service of [ + Service.CameraCapabilities, Service.CameraGlobalOperatingMode, Service.CameraMotionZones, Service.CameraBufferManagement, + Service.CameraMultiTierRTPStreamManagement, Service.CameraWebRTCStreamManagement, Service.CameraRecordingManagement, + Service.CameraOperatingMode, Service.DataStreamTransportManagement, Service.CameraKeyManagement, + Service.CameraClientCertificateManagement, Service.MotionSensor, + ]) { + expect(accessory.getService(service)).toBeDefined(); + } + expect(controller.capabilitiesService!.getCharacteristic(Characteristic.Version).value).toBe("17.99"); + }); + + test("webrtc session lifecycle", async () => { + const service = controller.webrtcStreamManagementService!; + + const offer = parse(await service.getCharacteristic(Characteristic.WebRTCSolicitOffer).handleSetRequest( + tlv(1, tlv(1, [0])).toString("base64"))); + expect(offer[4][0]).toBe(WebRTCSolicitOfferStatus.SUCCESS); + expect(offer[2].toString()).toBe("v=0"); + expect(service.getCharacteristic(Characteristic.WebRTCNumberOfActiveSessions).value).toBe(1); + + const sessionId = offer[1]; + const busy = parse(await service.getCharacteristic(Characteristic.WebRTCSolicitOffer).handleSetRequest(tlv(1, tlv(1, [0])).toString("base64"))); + expect(busy[4][0]).toBe(WebRTCSolicitOfferStatus.ERROR); + + const answer = parse(await service.getCharacteristic(Characteristic.WebRTCProvideAnswer).handleSetRequest( + Buffer.concat([tlv(1, sessionId), tlv(2, Buffer.from("v=0 answer"))]).toString("base64"))); + expect(answer[2][0]).toBe(WebRTCStreamingStatus.SUCCESS); + expect(webrtc.handleProvideAnswer).toHaveBeenCalledWith(expect.objectContaining({ sdpAnswer: "v=0 answer" })); + + const unknown = parse(await service.getCharacteristic(Characteristic.WebRTCStreamingControl).handleSetRequest( + Buffer.concat([tlv(1, crypto.randomBytes(16)), tlv(2, [1])]).toString("base64"))); + expect(unknown[2][0]).toBe(WebRTCStreamingStatus.UNKNOWN_SESSION_IDENTIFIER); + + const end = parse(await service.getCharacteristic(Characteristic.WebRTCStreamingControl).handleSetRequest( + Buffer.concat([tlv(1, sessionId), tlv(2, [1])]).toString("base64"))); + expect(end[2][0]).toBe(WebRTCStreamingStatus.SUCCESS); + expect(webrtc.handleEndSession).toHaveBeenCalledWith(uuid.unparse(sessionId)); + expect(service.getCharacteristic(Characteristic.WebRTCNumberOfActiveSessions).value).toBe(0); + }); + + test("solicit offer reports privacy mode when the camera is off", async () => { + controller.globalOperatingModeService!.setCharacteristic(Characteristic.HomeKitCameraActive, 0); + + const offer = parse(await controller.webrtcStreamManagementService!.getCharacteristic(Characteristic.WebRTCSolicitOffer) + .handleSetRequest(tlv(1, tlv(1, [0])).toString("base64"))); + expect(offer[4][0]).toBe(WebRTCSolicitOfferStatus.PRIVACY_MODE_ACTIVE); + expect(webrtc.handleSolicitOffer).not.toHaveBeenCalled(); + }); + + test("event queue notifies, queries and acknowledges", async () => { + const buffer = controller.bufferManagementService!; + controller.setMotionDetected(true); + controller.setMotionDetected(false); + expect(buffer.getCharacteristic(Characteristic.BufferEventSequenceNumber).value).toBe(2); + + const command = buffer.getCharacteristic(Characteristic.BufferEventCommand); + const query = await command.handleSetRequest(Buffer.concat([tlv(1, [BufferEventCommandType.QUERY]), tlv(2, [1])]).toString("base64")); + expect(decodeBufferEventCommandResponse(Buffer.from(String(query), "base64")).map(event => event.type)) + .toEqual([CameraBufferEventType.MOTION, CameraBufferEventType.MOTION]); + + await command.handleSetRequest(Buffer.concat([tlv(1, [BufferEventCommandType.ACKNOWLEDGE]), tlv(2, [1])]).toString("base64")); + const remaining = await command.handleSetRequest(Buffer.concat([tlv(1, [BufferEventCommandType.QUERY]), tlv(2, [0])]).toString("base64")); + expect(decodeBufferEventCommandResponse(Buffer.from(String(remaining), "base64")).map(event => event.sequenceNumber)).toEqual([2n]); + }); + + test("csr, certificate, key and publishing point survive serialization", async () => { + const certificates = controller.clientCertificateManagementService!; + const csr = parse(await certificates.getCharacteristic(Characteristic.CameraClientCSR).handleSetRequest( + tlv(1, crypto.randomBytes(32)).toString("base64"))); + expect(csr[1][0]).toBe(0x30); + + await certificates.getCharacteristic(Characteristic.CameraClientCertificate).handleSetRequest( + Buffer.concat([tlv(1, Buffer.from([1, 2, 3])), tlv(2, Buffer.from([4, 5]))]).toString("base64")); + await controller.keyManagementService!.getCharacteristic(Characteristic.CameraKey).handleSetRequest( + Buffer.concat([tlv(1, Buffer.alloc(16, 7)), tlv(2, [3])]).toString("base64")); + await controller.bufferManagementService!.getCharacteristic(Characteristic.CameraRecordingPublishingPoint).handleSetRequest( + Buffer.concat([tlv(1, Buffer.from("https://ingest.example.com/x/")), tlv(2, tlv(1, Buffer.from([9])))]).toString("base64")); + + const state = JSON.parse(JSON.stringify(controller.serialize())); + controller.handleFactoryReset(); + expect(controller.serialize()!.privateKey).toBeUndefined(); + + controller.deserialize(state); + const restored = controller.serialize()!; + expect(restored.privateKey).toContain("PRIVATE KEY"); + expect(restored.clientCertificate).toBe(Buffer.from([1, 2, 3]).toString("base64")); + expect(restored.ca).toBe(Buffer.from([4, 5]).toString("base64")); + expect(restored.keys).toEqual([{ keyNumber: "3", key: Buffer.alloc(16, 7).toString("base64") }]); + expect(restored.publishingPoint).toBe(state.publishingPoint); + }); + + test("empty writes clear certificate, publishing point and keys", async () => { + const certificate = controller.clientCertificateManagementService!.getCharacteristic(Characteristic.CameraClientCertificate); + const publishingPoint = controller.bufferManagementService!.getCharacteristic(Characteristic.CameraRecordingPublishingPoint); + + await certificate.handleSetRequest(Buffer.concat([tlv(1, Buffer.from([1, 2, 3]))]).toString("base64")); + await publishingPoint.handleSetRequest(tlv(1, Buffer.from("https://ingest.example.com/x/")).toString("base64")); + await controller.keyManagementService!.getCharacteristic(Characteristic.CameraKey).handleSetRequest( + Buffer.concat([tlv(1, Buffer.alloc(16, 7)), tlv(2, [3])]).toString("base64")); + + await expect(certificate.handleSetRequest("")).resolves.toBeUndefined(); + await expect(publishingPoint.handleSetRequest("")).resolves.toBeUndefined(); + await expect(controller.keyManagementService!.getCharacteristic(Characteristic.CameraKey).handleSetRequest("")).resolves.toBeUndefined(); + + const cleared = controller.serialize()!; + expect(cleared.clientCertificate).toBeUndefined(); + expect(cleared.publishingPoint).toBeUndefined(); + expect(cleared.keys).toEqual([]); + expect(controller.clientCertificateManagementService!.getCharacteristic(Characteristic.CameraClientCertificateStatus).value).toBe("AQEB"); + }); + + test("owns the recording management and links it to the stream services", () => { + const recording = controller.recordingManagementService!; + const dataStream = controller.recordingManagement!.dataStreamManagement.getService(); + expect(accessory.getService(Service.CameraRecordingManagement)).toBe(recording); + expect(recording.testCharacteristic(Characteristic.RecordingAudioActive)).toBe(true); + expect(recording.linkedServices).toContain(controller.motionService); + expect(controller.multiTierStreamManagementService!.linkedServices).toContain(dataStream); + expect(controller.webrtcStreamManagementService!.linkedServices).toContain(dataStream); + expect(recording.getCharacteristic(Characteristic.SupportedCameraRecordingConfiguration).value).toBeDefined(); + }); + + test("hds only without an ingest delegate", () => { + const hds = new Accessory("HDS", uuid.generate("hds")); + const secureVideo = new SecureVideoController({ + sensor: { uuid: uuid.generate("hds-sensor"), width: 1920, height: 1080 }, + video: { codec: StreamTierVideoCodec.H265, tiers: [] }, + webrtc: { delegate: webrtc }, + rtp: { delegate: rtp }, + recording: { options: recordingOptions, delegate: recordingDelegate }, + }); + hds.configureController(secureVideo); + + expect(hds.getService(Service.CameraRecordingManagement)).toBeDefined(); + expect(hds.getService(Service.CameraBufferManagement)).toBeUndefined(); + expect(hds.getService(Service.CameraKeyManagement)).toBeUndefined(); + expect(hds.getService(Service.CameraClientCertificateManagement)).toBeUndefined(); + }); + + test("buffer upload returns a generated clip id", async () => { + const response = await controller.bufferManagementService!.getCharacteristic(Characteristic.BufferUploadCommand).handleSetRequest( + Buffer.concat([tlv(1, [1]), tlv(2, [1])]).toString("base64")); + const decoded = Buffer.from(String(response), "base64"); + expect(decoded[0]).toBe(1); // TLV type: clip id + expect(decoded[1]).toBe(8); // encoded as a uint64 + expect(decoded.subarray(2, 10)).not.toEqual(Buffer.alloc(8)); + }); +}); diff --git a/src/lib/controller/SecureVideoController.ts b/src/lib/controller/SecureVideoController.ts new file mode 100644 index 000000000..048e8cd0d --- /dev/null +++ b/src/lib/controller/SecureVideoController.ts @@ -0,0 +1,1212 @@ +import crypto from "crypto"; +import createDebug from "debug"; +import { EventEmitter } from "events"; +import { + BufferActivityCommandRequest, + BufferEventCommandType, + BufferUploadCommandRequest, + CAMERA_CAPABILITIES_VERSION, + CameraBufferEvent, + CameraBufferEventType, + CameraRecordingPublishingPointValue, + CameraSensorIntent, + CameraSensorType, + CameraZonesValue, + CMAFError, + decodeBufferActivityCommand, + decodeBufferEventCommand, + decodeBufferUploadCommand, + decodeCameraClientCertificate, + decodeCameraClientCSRRequest, + decodeCameraKey, + decodeCameraRecordingPublishingPoint, + decodeCameraZones, + decodeRTPSetupEndpoints, + decodeRTPStreamingControl, + decodeWebRTCProvideAnswer, + decodeWebRTCReoffer, + decodeWebRTCSolicitOffer, + decodeWebRTCStreamingControl, + decodeWebRTCUpdateSession, + encodeBufferEventCommandResponse, + encodeBufferUploadCommandResponse, + encodeCameraCapabilities, + encodeCameraClientCertificate, + encodeCameraClientCertificateStatus, + encodeCameraClientCSRResponse, + encodeCameraKeyID, + encodeCameraRecordingPublishingPoint, + encodeCameraZones, + encodeContributingSensors, + encodeRTPSetupEndpointsResponse, + encodeSensorUUID, + encodeSessionStatus, + encodeSupportedAudioStreamTiers, + encodeSupportedVideoStreamTiers, + encodeWebRTCReofferResponse, + encodeWebRTCSolicitOfferResponse, + RTPSetupEndpointsResponse, + RTPSRTPParameters, + RTPStreamingCommand, + RTPStreamingStatus, + SFrameKeyData, + StreamTierAudioCodec, + StreamTierVideoCodec, + AudioStreamTier, + VideoStreamTier, + WebRTCICECandidate, + WebRTCOfferOptions, + WebRTCProvideAnswerRequest, + WebRTCReofferRequest, + WebRTCSolicitOfferStatus, + WebRTCStreamingStatus, + WebRTCUpdateSessionRequest, +} from "../camera/SecureVideoTypes"; +import { CMAFIngest } from "../camera/CMAFIngest"; +import { createClientCSR, generateClientKey } from "../camera/SecureVideoCredentials"; +import { HDSSnapshotTransport } from "../camera/HDSSnapshotTransport"; +import { EventTriggerOption, RecordingManagement } from "../camera/RecordingManagement"; +import { Characteristic, CharacteristicEventTypes, Perms } from "../Characteristic"; +import { DataStreamManagement } from "../datastream"; +import { + CameraBufferManagement, + CameraCapabilities, + CameraClientCertificateManagement, + CameraGlobalOperatingMode, + CameraKeyManagement, + CameraMotionZones, + CameraMultiTierRTPStreamManagement, + CameraOperatingMode, + CameraRecordingManagement, + CameraWebRTCStreamManagement, + DataStreamTransportManagement, + MotionSensor, +} from "../definitions"; +import { HAPStatus } from "../HAPServer"; +import { Service } from "../Service"; +import { HapStatusError } from "../util/hapStatusError"; +import * as uuid from "../util/uuid"; +import { ControllerIdentifier, ControllerServiceMap, SerializableController, StateChangeDelegate } from "./Controller"; + +import type { CharacteristicValue } from "../../types"; +import type { CharacteristicChange } from "../Characteristic"; +import type { CMAFMediaDescription } from "../camera/CMAFIngest"; +import type { SecureVideoSnapshotHandler } from "../camera/HDSSnapshotTransport"; +import type { CameraRecordingOptions, RecordingManagementState } from "../camera/RecordingManagement"; +import type { HAPConnection } from "../util/eventedhttp"; +import type { CameraRecordingDelegate } from "./CameraController"; + +const debug = createDebug("HAP-NodeJS:SecureVideo:Controller"); + +const MAX_QUEUED_EVENTS = 256; +const DEFAULT_MAX_WEBRTC_SESSIONS = 6; + +function setupEndpointsError(sessionIdentifier: string): RTPSetupEndpointsResponse { + const emptySRTP: RTPSRTPParameters = { cryptoSuite: 0, masterKey: Buffer.alloc(0), masterSalt: Buffer.alloc(0) }; + return { + sessionIdentifier, + status: 2, + accessoryAddress: { version: "ipv4", address: "0.0.0.0", videoRTPPort: 0, audioRTPPort: 0 }, + video: emptySRTP, + audio: emptySRTP, + videoSSRC: 0, + audioSSRC: 0, + }; +} + +/** + * @group Camera Secure Video + */ +export interface SecureVideoVideoTier extends VideoStreamTier { + /** kbps */ + peakBitrate: number; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCSolicitOfferRequest { + sessionIdentifier: string; + options: WebRTCOfferOptions; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCOffer { + sdpOffer: string; + candidates?: WebRTCICECandidate[]; + sframe?: SFrameKeyData; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCReofferAnswer { + sdpAnswer: string; + sframe?: SFrameKeyData; +} + +/** + * @group Camera Secure Video + */ +export interface WebRTCStreamingDelegate { + handleSolicitOffer(request: WebRTCSolicitOfferRequest): Promise; + handleProvideAnswer(request: WebRTCProvideAnswerRequest): Promise; + handleReoffer(request: WebRTCReofferRequest): Promise; + handleUpdateSession(request: WebRTCUpdateSessionRequest): Promise; + handleEndSession(sessionIdentifier: string): Promise; +} + +/** + * @group Camera Secure Video + */ +export interface MultiTierPrepareStreamRequest { + sessionIdentifier: string; + addressVersion: "ipv4" | "ipv6"; + /** the controller address media is sent to */ + targetAddress: string; + /** the accessory address on this connection */ + sourceAddress: string; + controllerVideoPort: number; + controllerAudioPort: number; + video: RTPSRTPParameters; + audio: RTPSRTPParameters; +} + +/** + * @group Camera Secure Video + */ +export interface MultiTierPrepareStreamResponse { + /** overrides the accessory address in the response, defaults to the connection source address */ + addressOverride?: string; + videoPort: number; + audioPort: number; + videoSSRC: number; + audioSSRC: number; + video: RTPSRTPParameters; + audio: RTPSRTPParameters; +} + +/** + * @group Camera Secure Video + */ +export interface MultiTierStreamStartRequest { + sessionIdentifier: string; + /** identifier of the selected video tier from the advertised supported video stream tiers */ + videoTier: number; + /** ssrc the accessory must use for the outgoing video stream */ + videoSSRC: number; + audioTier?: number; + audioSSRC?: number; +} + +/** + * @group Camera Secure Video + */ +export interface MultiTierRTPStreamingDelegate { + prepareStream(request: MultiTierPrepareStreamRequest): Promise; + startStream(request: MultiTierStreamStartRequest): Promise; + stopStream(sessionIdentifier: string): Promise; +} + +/** + * @group Camera Secure Video + */ +export interface CMAFRecordingDelegate { + /** + * Streams the clip as fMP4: the init segment first, then media fragments, until `request.signal` aborts or the + * source ends. The controller seals every segment, builds the HLS playlists and uploads them to the publishing point. + */ + streamClip(request: CMAFClipRequest): AsyncGenerator; + /** the HomeKit HomeHub signals recording activity windows */ + handleBufferActivity?(request: BufferActivityCommandRequest): void; + updateRecordingActive?(active: boolean, audioActive: boolean): void; + /** called with undefined when the controller clears the publishing point */ + updatePublishingPoint?(publishingPoint: CameraRecordingPublishingPointValue | undefined): void; + updateClientCertificate?(installed: boolean): void; + /** + * the upload session ended, `error` is set when it failed (the HomeKit HomeHub gets the same as a CMAF error event); + * `detail` names the failed request or transport error, or summarizes the playlist requests of a finished upload + */ + handleUploadResult?(cmafSessionId: bigint, error?: CMAFError, detail?: string): void; +} + +/** + * @group Camera Secure Video + */ +export interface CMAFClipRequest { + cmafSessionId: bigint; + command: BufferUploadCommandRequest; + /** aborted when the HomeKit HomeHub stops the upload */ + signal: AbortSignal; +} + +/** + * @group Camera Secure Video + */ +export interface CMAFSegment { + type: "init" | "media"; + /** raw fMP4; the controller seals it before upload */ + data: Buffer; + /** on the init segment: the actual media description for the HLS playlists, overriding the controller default */ + media?: CMAFMediaDescription; + /** on the init segment: wall clock of the first media fragment, defaults to the start of the upload command */ + startedAt?: Date; + /** media fragment duration in seconds, defaults to 2 */ + duration?: number; + /** set on the last media fragment */ + last?: boolean; +} + +/** + * @group Camera Secure Video + */ +export interface SecureVideoControllerOptions { + sensor: { + /** stable uuid string, must not change across restarts */ + uuid: string; + width: number; + height: number; + type?: CameraSensorType; + intent?: CameraSensorIntent; + }; + video: { + codec: StreamTierVideoCodec; + payloadType?: number; + tiers: SecureVideoVideoTier[]; + }; + audio?: { + payloadType?: number; + tier: AudioStreamTier; + }; + webrtc: { + delegate: WebRTCStreamingDelegate; + maxSessions?: number; + }; + rtp: { + delegate: MultiTierRTPStreamingDelegate; + }; + /** + * Event recording over HDS, owned by the controller like a {@link CameraController} owns its {@link RecordingManagement}. + * A HomeKit HomeHub analyses and records the HDS stream and locates the stream management services through its + * data stream, so it is part of every secure video accessory. {@link EventTriggerOption.MOTION} is always advertised, + * {@link CameraRecordingOptions.overrideEventTriggerOptions} adds further triggers. + */ + recording: { + options: CameraRecordingOptions; + delegate: CameraRecordingDelegate; + }; + /** + * Accessory direct upload of clips to the CMAF publishing point. Adds the buffer, key and client certificate + * management services; without it the HomeKit HomeHub records over HDS bulk send only. + */ + ingest?: { + delegate: CMAFRecordingDelegate; + /** common name placed into the client certificate signing request */ + certificateCommonName?: string; + }; + /** reuse an existing motion sensor instead of creating one */ + motionService?: Service; + /** + * produces a JPEG snapshot for the HDS `ipcamera.snapshot` relay iOS 27 uses for the secure video services. Without + * it no snapshot responder is installed; the legacy image resource request of a {@link CameraController} is not used. + */ + snapshot?: SecureVideoSnapshotHandler; +} + +/** + * @group Camera Secure Video + */ +export interface SecureVideoIngestCredentials { + publishingPoint?: CameraRecordingPublishingPointValue; + /** PKCS#8 PEM */ + privateKey?: string; + /** DER */ + clientCertificate?: Buffer; + /** DER */ + ca?: Buffer; + keys: { keyNumber: bigint, key: Buffer }[]; + currentKeyNumber?: bigint; +} + +/** + * @group Camera Secure Video + */ +export interface SecureVideoControllerServiceMap extends ControllerServiceMap { + capabilities?: CameraCapabilities; + globalOperatingMode?: CameraGlobalOperatingMode; + motionZones?: CameraMotionZones; + multiTierStreamManagement?: CameraMultiTierRTPStreamManagement; + webrtcStreamManagement?: CameraWebRTCStreamManagement; + recordingManagement?: CameraRecordingManagement; + cameraOperatingMode?: CameraOperatingMode; + dataStreamTransportManagement?: DataStreamTransportManagement; + bufferManagement?: CameraBufferManagement; + keyManagement?: CameraKeyManagement; + clientCertificateManagement?: CameraClientCertificateManagement; + motionSensor?: MotionSensor; +} + +/** + * @group Camera Secure Video + */ +export interface SecureVideoControllerState { + homeKitCameraActive: number; + operatingModeIndicator: number; + globalStreamingEnabled: boolean; + webrtcStreamingEnabled: boolean; + rtpStreamingEnabled: boolean; + motionEnabled: boolean; + motionZonesActive: number; + zones?: string; + recordingManagement?: RecordingManagementState; + publishingPoint?: string; + privateKey?: string; + clientCertificate?: string; + ca?: string; + keys: { keyNumber: string, key: string }[]; + currentKeyNumber?: string; + eventSequenceNumber: string; +} + +/** + * @group Camera Secure Video + */ +export const enum SecureVideoControllerEvents { + ZONES_CHANGED = "zones-changed", + OPERATING_MODE_CHANGED = "operating-mode-changed", +} + +/** + * @group Camera Secure Video + */ +// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging +export declare interface SecureVideoController { + on(event: "zones-changed", listener: (zones: CameraZonesValue | undefined, active: boolean) => void): this; + on(event: "operating-mode-changed", listener: () => void): this; + + emit(event: "zones-changed", zones: CameraZonesValue | undefined, active: boolean): boolean; + emit(event: "operating-mode-changed"): boolean; +} + +interface WebRTCSession { + sessionIdentifier: string; + answered: boolean; +} + +type DistributiveOmit = T extends unknown ? Omit : never; +type CameraBufferEventInput = DistributiveOmit; + +type TLVWriteHandler = (value: Buffer, connection?: HAPConnection) => Promise | Buffer | undefined; + +/** + * Implements the camera services of the HomeKit Secure Video Open Source Compatibility Guide (WebRTC streaming, + * multi-tier RTP streaming and CMAF ingest recording). Media handling is left to the supplied delegates. + * + * @group Camera Secure Video + */ +// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging +export class SecureVideoController extends EventEmitter implements SerializableController { + public static readonly CONTROLLER_ID = "secure-video"; + + public capabilitiesService?: CameraCapabilities; + public globalOperatingModeService?: CameraGlobalOperatingMode; + public motionZonesService?: CameraMotionZones; + public multiTierStreamManagementService?: CameraMultiTierRTPStreamManagement; + public webrtcStreamManagementService?: CameraWebRTCStreamManagement; + public recordingManagement?: RecordingManagement; + public bufferManagementService?: CameraBufferManagement; + public keyManagementService?: CameraKeyManagement; + public clientCertificateManagementService?: CameraClientCertificateManagement; + public motionService?: Service; + + private readonly options: SecureVideoControllerOptions; + private stateChangeDelegate?: StateChangeDelegate; + private motionServiceExternallySupplied = false; + private dataStreamManagement?: DataStreamManagement; + private snapshotTransport?: HDSSnapshotTransport; + private cmafIngest?: CMAFIngest; + private readonly externalCleanups: (() => void)[] = []; + + private readonly webrtcSessions = new Map(); + private readonly lastResponses = new Map(); + private readonly readHandlers = new Set(); + + private events: CameraBufferEvent[] = []; + private eventSequenceNumber = 0n; + + private zones?: CameraZonesValue; + private publishingPoint?: CameraRecordingPublishingPointValue; + private privateKey?: crypto.KeyObject; + private clientCertificate?: Buffer; + private ca?: Buffer; + private readonly keys = new Map(); + private currentKeyNumber?: bigint; + + constructor(options: SecureVideoControllerOptions) { + super(); + this.options = options; + } + + public controllerId(): ControllerIdentifier { + return SecureVideoController.CONTROLLER_ID; + } + + /** Whether the camera is enabled in HomeKit, mirrored from the {@link Characteristic.HomeKitCameraActive} of the global operating mode. */ + public get homeKitCameraActive(): boolean { + return !!this.globalOperatingModeService?.getCharacteristic(Characteristic.HomeKitCameraActive).value; + } + + /** The recording management service, see {@link recordingManagement}. */ + public get recordingManagementService(): Service | undefined { + return this.recordingManagement?.recordingManagementService; + } + + /** Whether recording is enabled by the user, mirrored from the {@link Characteristic.Active} of the recording management. */ + public get recordingActive(): boolean { + return !!this.recordingManagementService?.getCharacteristic(Characteristic.Active).value; + } + + /** Whether audio recording is enabled by the user. */ + public get recordingAudioActive(): boolean { + return !!this.recordingManagementService?.getCharacteristic(Characteristic.RecordingAudioActive).value; + } + + /** The configured motion zones and whether zone based motion detection is active. */ + public get motionZones(): { active: boolean, zones?: CameraZonesValue } { + return { + active: !!this.motionZonesService?.getCharacteristic(Characteristic.Active).value, + zones: this.zones, + }; + } + + /** Identifiers of the currently active WebRTC streaming sessions. */ + public get activeWebRTCSessions(): string[] { + return [...this.webrtcSessions.keys()]; + } + + /** + * Whether streaming is currently allowed, honoring the global operating mode (camera active, streaming enabled and + * not manually disabled). Pass a stream management service to additionally require its own streaming to be enabled. + */ + public streamingAllowed(service?: Service): boolean { + if (!this.homeKitCameraActive) { + return false; + } + if (!this.globalOperatingModeService?.getCharacteristic(Characteristic.StreamingEnabled).value) { + return false; + } + if (this.globalOperatingModeService.testCharacteristic(Characteristic.ManuallyDisabled) + && this.globalOperatingModeService.getCharacteristic(Characteristic.ManuallyDisabled).value) { + return false; + } + return !service || !!service.getCharacteristic(Characteristic.StreamingEnabled).value; + } + + /** Reports a motion state change by updating the motion sensor's {@link Characteristic.MotionDetected}. */ + public setMotionDetected(active: boolean): void { + this.motionService?.updateCharacteristic(Characteristic.MotionDetected, active); + } + + private ingestCredentials(): SecureVideoIngestCredentials { + return { + publishingPoint: this.publishingPoint, + privateKey: this.privateKey?.export({ type: "pkcs8", format: "pem" }).toString(), + clientCertificate: this.clientCertificate, + ca: this.ca, + keys: [...this.keys.entries()].map(([keyNumber, key]) => ({ keyNumber, key })), + currentKeyNumber: this.currentKeyNumber, + }; + } + + private ingestMediaDescription(): CMAFMediaDescription { + const tiers = this.options.video.tiers; + const top = tiers.reduce((best, tier) => (tier.width * tier.height > best.width * best.height ? tier : best), tiers[0]); + const codecs = this.options.video.codec === StreamTierVideoCodec.H265 ? "hvc1.1.6.L120.B0" : "avc1.640028"; + return { + codecs, + width: top?.width ?? 1920, + height: top?.height ?? 1080, + bitrate: (top?.targetAverageBitrate ?? 1700) * 1000, + }; + } + + /** Signals whether the CMAF ingest client certificate needs to be (re)issued by the HomeKit HomeHub. */ + public setClientCertificateNeedsUpdate(needsUpdate: boolean): void { + this.clientCertificateManagementService?.updateCharacteristic(Characteristic.CameraClientCertificateStatus, + encodeCameraClientCertificateStatus(needsUpdate).toString("base64")); + } + + /** Ends the WebRTC streaming session with the given identifier and notifies the delegate. */ + public async endWebRTCSession(sessionIdentifier: string): Promise { + if (!this.webrtcSessions.delete(sessionIdentifier)) { + return; + } + this.updateWebRTCSessionCount(); + await this.options.webrtc.delegate.handleEndSession(sessionIdentifier); + } + + public constructServices(): SecureVideoControllerServiceMap { + return this.buildServiceMap({}).serviceMap; + } + + public initWithServices(serviceMap: SecureVideoControllerServiceMap): SecureVideoControllerServiceMap | void { + const result = this.buildServiceMap(serviceMap); + if (result.updated) { + return result.serviceMap; + } + } + + public configureServices(): void { + const { sensor, video, audio } = this.options; + const sensorUUID = encodeSensorUUID(sensor.uuid).toString("base64"); + + const videoTiers = encodeSupportedVideoStreamTiers({ + codec: video.codec, + payloadType: video.payloadType ?? 99, + tiers: video.tiers, + }).toString("base64"); + const audioTiers = audio + ? encodeSupportedAudioStreamTiers({ codec: StreamTierAudioCodec.OPUS, payloadType: audio.payloadType ?? 110, tiers: [audio.tier] }).toString("base64") + : ""; + + const capabilities = this.capabilitiesService!; + capabilities.setCharacteristic(Characteristic.Version, CAMERA_CAPABILITIES_VERSION); + this.registerRead(capabilities.getCharacteristic(Characteristic.CameraCapabilitiesConfiguration), () => encodeCameraCapabilities({ + version: 1, + sensors: [{ + width: sensor.width, + height: sensor.height, + sensorUUID: sensor.uuid, + type: sensor.type ?? CameraSensorType.PRIMARY, + intent: sensor.intent ?? CameraSensorIntent.MAIN, + videoStreams: video.tiers.map(tier => ({ + identifier: uuid.generate(`${sensor.uuid}:tier:${tier.identifier}`), + quality: tier.quality, + width: tier.width, + height: tier.height, + frameRate: tier.frameRate, + averageBitrate: tier.targetAverageBitrate, + peakBitrate: tier.peakBitrate, + })), + }], + }).toString("base64")); + + const operatingMode = this.globalOperatingModeService!; + for (const characteristic of [Characteristic.HomeKitCameraActive, Characteristic.StreamingEnabled, Characteristic.CameraOperatingModeIndicator]) { + operatingMode.getCharacteristic(characteristic).on(CharacteristicEventTypes.CHANGE, () => { + this.updateStatusActive(); + this.emit(SecureVideoControllerEvents.OPERATING_MODE_CHANGED); + this.stateChangeDelegate?.(); + }); + } + if (operatingMode.testCharacteristic(Characteristic.ManuallyDisabled)) { + operatingMode.getCharacteristic(Characteristic.ManuallyDisabled).on(CharacteristicEventTypes.CHANGE, () => this.updateStatusActive()); + } + + const zones = this.motionZonesService!; + zones.setCharacteristic(Characteristic.Version, CAMERA_CAPABILITIES_VERSION); + zones.getCharacteristic(Characteristic.Active).on(CharacteristicEventTypes.CHANGE, () => { + this.emit(SecureVideoControllerEvents.ZONES_CHANGED, this.zones, this.motionZones.active); + this.stateChangeDelegate?.(); + }); + this.registerRead(zones.getCharacteristic(Characteristic.CameraZones), () => this.zones ? encodeCameraZones(this.zones).toString("base64") : ""); + this.handleTLVWrite(zones.getCharacteristic(Characteristic.CameraZones), value => { + this.zones = value.length ? decodeCameraZones(value) : undefined; + this.emit(SecureVideoControllerEvents.ZONES_CHANGED, this.zones, this.motionZones.active); + this.stateChangeDelegate?.(); + return undefined; + }); + + const rtp = this.multiTierStreamManagementService!; + rtp.setCharacteristic(Characteristic.SensorUUID, sensorUUID); + rtp.setCharacteristic(Characteristic.SupportedVideoStreamTiers, videoTiers); + rtp.setCharacteristic(Characteristic.SupportedAudioStreamTiers, audioTiers); + // SRTP_CRYPTO_SUITE: AES_CM_128_HMAC_SHA1_80 + rtp.setCharacteristic(Characteristic.SupportedRTPConfiguration, Buffer.from([0x02, 0x01, 0x00]).toString("base64")); + rtp.getCharacteristic(Characteristic.StreamingEnabled).on(CharacteristicEventTypes.CHANGE, () => this.updateStatusActive()); + this.handleTLVWrite(rtp.getCharacteristic(Characteristic.SetupEndpoints), (value, connection) => this.handleSetupEndpoints(value, connection)); + this.handleTLVWrite(rtp.getCharacteristic(Characteristic.RTPStreamingControl), value => this.handleRTPStreamingControl(value)); + + const webrtc = this.webrtcStreamManagementService!; + // A HomeKit HomeHub finds one stream management service through the other's linked services when + // setting up a remote stream; a shared sensor uuid alone does not establish the association. + webrtc.addLinkedService(rtp); + rtp.addLinkedService(webrtc); + webrtc.setCharacteristic(Characteristic.SensorUUID, sensorUUID); + webrtc.setCharacteristic(Characteristic.WebRTCSupportedVideoStreamTiers, videoTiers); + webrtc.setCharacteristic(Characteristic.WebRTCSupportedAudioStreamTiers, audioTiers); + webrtc.setCharacteristic(Characteristic.WebRTCNumberOfActiveSessions, 0); + this.handleTLVWrite(webrtc.getCharacteristic(Characteristic.WebRTCSolicitOffer), value => this.handleSolicitOffer(value)); + this.handleTLVWrite(webrtc.getCharacteristic(Characteristic.WebRTCProvideAnswer), value => this.handleProvideAnswer(value)); + this.handleTLVWrite(webrtc.getCharacteristic(Characteristic.WebRTCReoffer), value => this.handleReoffer(value)); + this.handleTLVWrite(webrtc.getCharacteristic(Characteristic.WebRTCUpdateSession), value => this.handleUpdateSession(value)); + this.handleTLVWrite(webrtc.getCharacteristic(Characteristic.WebRTCStreamingControl), value => this.handleWebRTCStreamingControl(value)); + + const recordingManagement = this.recordingManagement!; + this.dataStreamManagement = recordingManagement.dataStreamManagement; + const dataStreamService = this.dataStreamManagement.getService(); + // A HomeKit HomeHub locates the stream management services through the recording data stream they link to. + rtp.addLinkedService(dataStreamService); + webrtc.addLinkedService(dataStreamService); + if (this.options.snapshot) { + // iOS 27 fetches snapshots for the secure video services over HDS instead of the legacy image resource + this.snapshotTransport = new HDSSnapshotTransport(this.dataStreamManagement, this.options.snapshot, () => this.homeKitCameraActive); + } + + const recording = recordingManagement.recordingManagementService; + for (const characteristic of [Characteristic.Active, Characteristic.RecordingAudioActive]) { + this.onExternalChange(recording.getCharacteristic(characteristic), () => { + this.options.ingest?.delegate.updateRecordingActive?.(this.recordingActive, this.recordingAudioActive); + this.stateChangeDelegate?.(); + }); + } + + if (this.options.ingest) { + this.configureCMAFIngestServices(); + } + + if (!this.motionServiceExternallySupplied && this.motionService) { + this.motionService.setCharacteristic(Characteristic.StatusActive, true); + } + if (this.motionService) { + recording.addLinkedService(this.motionService); + recordingManagement.sensorServices.push(this.motionService); + this.onExternalChange(this.motionService.getCharacteristic(Characteristic.MotionEnabled), () => this.stateChangeDelegate?.()); + this.onExternalChange(this.motionService.getCharacteristic(Characteristic.MotionDetected), change => { + if (change.oldValue === change.newValue) { + return; + } + const active = !!change.newValue; + this.motionService!.updateCharacteristic(Characteristic.ContributingSensors, + encodeContributingSensors(active ? [this.options.sensor.uuid] : []).toString("base64")); + this.pushEvent({ type: CameraBufferEventType.MOTION, active }); + }); + } + + this.updateStatusActive(); + } + + private onExternalChange(characteristic: Characteristic, listener: (change: CharacteristicChange) => void): void { + characteristic.on(CharacteristicEventTypes.CHANGE, listener); + this.externalCleanups.push(() => characteristic.removeListener(CharacteristicEventTypes.CHANGE, listener)); + } + + private configureCMAFIngestServices(): void { + this.cmafIngest = new CMAFIngest(this.options.ingest!.delegate, { + sensorUUID: this.options.sensor.uuid, + media: this.ingestMediaDescription(), + credentials: () => this.ingestCredentials(), + reportSessionStart: cmafSessionId => this.pushEvent({ type: CameraBufferEventType.CMAF_SESSION_START, cmafSessionId }), + reportSessionStop: (cmafSessionId, detail) => { + this.pushEvent({ type: CameraBufferEventType.CMAF_SESSION_STOP, cmafSessionId }); + this.options.ingest?.delegate.handleUploadResult?.(cmafSessionId, undefined, detail); + }, + reportError: (cmafSessionId, error, detail) => { + this.pushEvent({ type: CameraBufferEventType.CMAF_ERROR, cmafSessionId, error }); + this.options.ingest?.delegate.handleUploadResult?.(cmafSessionId, error, detail); + }, + }); + + const buffer = this.bufferManagementService!; + buffer.setCharacteristic(Characteristic.BufferEventSequenceNumber, Number(this.eventSequenceNumber & 0xffffffffn)); + this.handleTLVWrite(buffer.getCharacteristic(Characteristic.BufferUploadCommand), value => this.handleBufferUpload(value)); + this.handleTLVWrite(buffer.getCharacteristic(Characteristic.BufferActivityCommand), value => { + const request = decodeBufferActivityCommand(value); + debug("buffer activity %o", request); + this.options.ingest?.delegate.handleBufferActivity?.(request); + return undefined; + }); + this.handleTLVWrite(buffer.getCharacteristic(Characteristic.BufferEventCommand), value => this.handleBufferEventCommand(value)); + this.registerRead(buffer.getCharacteristic(Characteristic.CameraRecordingPublishingPoint), + () => this.publishingPoint ? encodeCameraRecordingPublishingPoint(this.publishingPoint).toString("base64") : ""); + this.handleTLVWrite(buffer.getCharacteristic(Characteristic.CameraRecordingPublishingPoint), value => { + this.publishingPoint = value.length ? decodeCameraRecordingPublishingPoint(value) : undefined; + this.options.ingest?.delegate.updatePublishingPoint?.(this.publishingPoint); + this.stateChangeDelegate?.(); + return undefined; + }); + + const keys = this.keyManagementService!; + this.registerRead(keys.getCharacteristic(Characteristic.CameraKeyID), + () => this.currentKeyNumber !== undefined ? encodeCameraKeyID(this.currentKeyNumber).toString("base64") : ""); + this.handleTLVWrite(keys.getCharacteristic(Characteristic.CameraKey), value => { + if (!value.length) { + this.keys.clear(); + this.currentKeyNumber = undefined; + this.stateChangeDelegate?.(); + return undefined; + } + const { key, keyNumber } = decodeCameraKey(value); + this.keys.set(keyNumber, key); + this.currentKeyNumber = keyNumber; + keys.getCharacteristic(Characteristic.CameraKeyID).sendEventNotification(encodeCameraKeyID(keyNumber).toString("base64")); + this.stateChangeDelegate?.(); + return undefined; + }); + + const certificates = this.clientCertificateManagementService!; + certificates.setCharacteristic(Characteristic.CameraClientCertificateStatus, + encodeCameraClientCertificateStatus(!this.clientCertificate).toString("base64")); + this.handleTLVWrite(certificates.getCharacteristic(Characteristic.CameraClientCSR), value => { + const nonce = decodeCameraClientCSRRequest(value); + this.privateKey ??= generateClientKey(); + const commonName = this.options.ingest?.certificateCommonName ?? this.options.sensor.uuid; + const { csr, nonceSignature } = createClientCSR(this.privateKey, commonName, nonce); + this.stateChangeDelegate?.(); + return encodeCameraClientCSRResponse(csr, nonceSignature); + }); + this.registerRead(certificates.getCharacteristic(Characteristic.CameraClientCertificate), () => this.clientCertificate + ? encodeCameraClientCertificate({ clientCertificate: this.clientCertificate, ca: this.ca }).toString("base64") + : ""); + this.handleTLVWrite(certificates.getCharacteristic(Characteristic.CameraClientCertificate), value => { + const { clientCertificate, ca } = value.length ? decodeCameraClientCertificate(value) : { clientCertificate: undefined, ca: undefined }; + this.clientCertificate = clientCertificate; + this.ca = ca; + this.setClientCertificateNeedsUpdate(!clientCertificate); + this.options.ingest?.delegate.updateClientCertificate?.(!!clientCertificate); + this.stateChangeDelegate?.(); + return undefined; + }); + } + + public handleControllerRemoved(): void { + this.handleFactoryReset(); + this.snapshotTransport?.destroy(); + this.snapshotTransport = undefined; + this.cmafIngest?.destroy(); + this.cmafIngest = undefined; + this.recordingManagement?.destroy(); + this.recordingManagement = undefined; + for (const cleanup of this.externalCleanups) { + cleanup(); + } + this.externalCleanups.length = 0; + this.removeAllListeners(); + } + + public handleFactoryReset(): void { + for (const sessionIdentifier of [...this.webrtcSessions.keys()]) { + this.endWebRTCSession(sessionIdentifier).catch(error => debug("failed to end session %s: %s", sessionIdentifier, error)); + } + this.recordingManagement?.handleFactoryReset(); + this.events = []; + this.eventSequenceNumber = 0n; + this.zones = undefined; + this.publishingPoint = undefined; + this.privateKey = undefined; + this.clientCertificate = undefined; + this.ca = undefined; + this.keys.clear(); + this.currentKeyNumber = undefined; + this.lastResponses.clear(); + } + + public serialize(): SecureVideoControllerState | undefined { + const operatingMode = this.globalOperatingModeService; + return { + homeKitCameraActive: Number(operatingMode?.getCharacteristic(Characteristic.HomeKitCameraActive).value ?? 1), + operatingModeIndicator: Number(operatingMode?.getCharacteristic(Characteristic.CameraOperatingModeIndicator).value ?? 1), + globalStreamingEnabled: !!operatingMode?.getCharacteristic(Characteristic.StreamingEnabled).value, + webrtcStreamingEnabled: !!this.webrtcStreamManagementService?.getCharacteristic(Characteristic.StreamingEnabled).value, + rtpStreamingEnabled: !!this.multiTierStreamManagementService?.getCharacteristic(Characteristic.StreamingEnabled).value, + motionEnabled: !!this.motionService?.getCharacteristic(Characteristic.MotionEnabled).value, + motionZonesActive: Number(this.motionZonesService?.getCharacteristic(Characteristic.Active).value ?? 0), + zones: this.zones ? encodeCameraZones(this.zones).toString("base64") : undefined, + recordingManagement: this.recordingManagement?.serialize(), + publishingPoint: this.publishingPoint ? encodeCameraRecordingPublishingPoint(this.publishingPoint).toString("base64") : undefined, + privateKey: this.privateKey?.export({ type: "pkcs8", format: "pem" }).toString(), + clientCertificate: this.clientCertificate?.toString("base64"), + ca: this.ca?.toString("base64"), + keys: [...this.keys.entries()].map(([keyNumber, key]) => ({ keyNumber: keyNumber.toString(), key: key.toString("base64") })), + currentKeyNumber: this.currentKeyNumber?.toString(), + eventSequenceNumber: this.eventSequenceNumber.toString(), + }; + } + + public deserialize(serialized: SecureVideoControllerState): void { + const operatingMode = this.globalOperatingModeService; + operatingMode?.updateCharacteristic(Characteristic.HomeKitCameraActive, serialized.homeKitCameraActive); + operatingMode?.updateCharacteristic(Characteristic.CameraOperatingModeIndicator, serialized.operatingModeIndicator); + operatingMode?.updateCharacteristic(Characteristic.StreamingEnabled, serialized.globalStreamingEnabled); + this.webrtcStreamManagementService?.updateCharacteristic(Characteristic.StreamingEnabled, serialized.webrtcStreamingEnabled); + this.multiTierStreamManagementService?.updateCharacteristic(Characteristic.StreamingEnabled, serialized.rtpStreamingEnabled); + this.motionService?.updateCharacteristic(Characteristic.MotionEnabled, serialized.motionEnabled); + this.motionZonesService?.updateCharacteristic(Characteristic.Active, serialized.motionZonesActive); + if (serialized.recordingManagement) { + this.recordingManagement?.deserialize(serialized.recordingManagement); + } + + this.zones = serialized.zones ? decodeCameraZones(Buffer.from(serialized.zones, "base64")) : undefined; + this.publishingPoint = serialized.publishingPoint + ? decodeCameraRecordingPublishingPoint(Buffer.from(serialized.publishingPoint, "base64")) + : undefined; + this.privateKey = serialized.privateKey ? crypto.createPrivateKey(serialized.privateKey) : undefined; + this.clientCertificate = serialized.clientCertificate ? Buffer.from(serialized.clientCertificate, "base64") : undefined; + this.ca = serialized.ca ? Buffer.from(serialized.ca, "base64") : undefined; + this.keys.clear(); + for (const { keyNumber, key } of serialized.keys ?? []) { + this.keys.set(BigInt(keyNumber), Buffer.from(key, "base64")); + } + this.currentKeyNumber = serialized.currentKeyNumber !== undefined ? BigInt(serialized.currentKeyNumber) : undefined; + this.eventSequenceNumber = BigInt(serialized.eventSequenceNumber ?? "0"); + + this.bufferManagementService?.updateCharacteristic(Characteristic.BufferEventSequenceNumber, Number(this.eventSequenceNumber & 0xffffffffn)); + this.setClientCertificateNeedsUpdate(!this.clientCertificate); + this.updateStatusActive(); + } + + public setupStateChangeDelegate(delegate?: StateChangeDelegate): void { + this.stateChangeDelegate = delegate; + this.recordingManagement?.setupStateChangeDelegate(delegate); + } + + private buildServiceMap(existing: SecureVideoControllerServiceMap): { serviceMap: SecureVideoControllerServiceMap, updated: boolean } { + const serviceMap: SecureVideoControllerServiceMap = { ...existing }; + let updated = false; + + function ensure(key: K, create: () => NonNullable) { + if (!serviceMap[key]) { + serviceMap[key] = create(); + updated = true; + } + return serviceMap[key]!; + } + + this.capabilitiesService = ensure("capabilities", () => new Service.CameraCapabilities("", "")); + this.globalOperatingModeService = ensure("globalOperatingMode", () => { + const service = new Service.CameraGlobalOperatingMode("", ""); + service.setCharacteristic(Characteristic.HomeKitCameraActive, Characteristic.HomeKitCameraActive.ON); + service.setCharacteristic(Characteristic.StreamingEnabled, true); + service.setCharacteristic(Characteristic.CameraOperatingModeIndicator, Characteristic.CameraOperatingModeIndicator.ENABLE); + service.setCharacteristic(Characteristic.ThirdPartyCameraActive, Characteristic.ThirdPartyCameraActive.ON); + return service; + }); + this.motionZonesService = ensure("motionZones", () => new Service.CameraMotionZones("", "")); + this.multiTierStreamManagementService = ensure("multiTierStreamManagement", () => { + const service = new Service.CameraMultiTierRTPStreamManagement("", ""); + service.setCharacteristic(Characteristic.StreamingEnabled, true); + return service; + }); + this.webrtcStreamManagementService = ensure("webrtcStreamManagement", () => { + const service = new Service.CameraWebRTCStreamManagement("", ""); + service.setCharacteristic(Characteristic.StreamingEnabled, true); + return service; + }); + const { recording } = this.options; + const eventTriggers = new Set([EventTriggerOption.MOTION, ...(recording.options.overrideEventTriggerOptions ?? [])]); + if (serviceMap.recordingManagement && serviceMap.cameraOperatingMode && serviceMap.dataStreamTransportManagement) { + this.recordingManagement = new RecordingManagement(recording.options, recording.delegate, eventTriggers, { + recordingManagement: serviceMap.recordingManagement, + operatingMode: serviceMap.cameraOperatingMode, + dataStreamManagement: new DataStreamManagement(serviceMap.dataStreamTransportManagement), + }); + } else { + this.recordingManagement = new RecordingManagement(recording.options, recording.delegate, eventTriggers); + serviceMap.recordingManagement = this.recordingManagement.recordingManagementService; + serviceMap.cameraOperatingMode = this.recordingManagement.operatingModeService; + serviceMap.dataStreamTransportManagement = this.recordingManagement.dataStreamManagement.getService(); + updated = true; + } + const recordingService = this.recordingManagement.recordingManagementService; + if (!recordingService.testCharacteristic(Characteristic.RecordingAudioActive)) { + recordingService.addCharacteristic(Characteristic.RecordingAudioActive); + } + // the buffer, key and certificate management services signal a CMAF accessory-direct-upload camera to the + // HomeKit HomeHub. They are only added when an ingest delegate is supplied; without them the hub records + // over the classic HDS bulk-send path. + if (this.options.ingest) { + this.bufferManagementService = ensure("bufferManagement", () => new Service.CameraBufferManagement("", "")); + this.keyManagementService = ensure("keyManagement", () => new Service.CameraKeyManagement("", "")); + this.clientCertificateManagementService = ensure("clientCertificateManagement", () => new Service.CameraClientCertificateManagement("", "")); + } else { + for (const key of ["bufferManagement", "keyManagement", "clientCertificateManagement"] as const) { + if (serviceMap[key]) { + delete serviceMap[key]; + updated = true; + } + } + } + + if (this.options.motionService) { + this.motionService = this.options.motionService; + this.motionServiceExternallySupplied = true; + if (serviceMap.motionSensor) { + delete serviceMap.motionSensor; + updated = true; + } + } else { + this.motionService = ensure("motionSensor", () => new Service.MotionSensor("", "")); + } + for (const characteristic of [Characteristic.ContributingSensors, Characteristic.MotionEnabled]) { + if (!this.motionService.testCharacteristic(characteristic)) { + this.motionService.addCharacteristic(characteristic); + } + } + if (!serviceMap.motionSensor || this.motionServiceExternallySupplied) { + this.motionService.setCharacteristic(Characteristic.MotionEnabled, true); + } + + return { serviceMap, updated }; + } + + private updateStatusActive(): void { + const rtp = this.multiTierStreamManagementService; + rtp?.updateCharacteristic(Characteristic.StatusActive, this.streamingAllowed(rtp)); + } + + private updateWebRTCSessionCount(): void { + this.webrtcStreamManagementService?.updateCharacteristic(Characteristic.WebRTCNumberOfActiveSessions, Math.min(255, this.webrtcSessions.size)); + } + + private pushEvent(event: CameraBufferEventInput): void { + this.eventSequenceNumber += 1n; + const queued = { ...event, sequenceNumber: this.eventSequenceNumber } as CameraBufferEvent; + this.events.push(queued); + if (this.events.length > MAX_QUEUED_EVENTS) { + this.events.splice(0, this.events.length - MAX_QUEUED_EVENTS); + } + + debug("queued buffer event %o", queued); + this.bufferManagementService?.updateCharacteristic(Characteristic.BufferEventSequenceNumber, Number(this.eventSequenceNumber & 0xffffffffn)); + this.stateChangeDelegate?.(); + } + + private handleBufferEventCommand(value: Buffer): Buffer { + const request = decodeBufferEventCommand(value); + debug("buffer event command %o", request); + + if (request.command === BufferEventCommandType.ACKNOWLEDGE) { + const acknowledged = request.sequenceNumber ?? this.eventSequenceNumber; + this.events = this.events.filter(event => event.sequenceNumber > acknowledged); + return encodeBufferEventCommandResponse([]); + } + + const from = request.sequenceNumber ?? 0n; + const limit = request.limit && request.limit > 0n ? Number(request.limit) : this.events.length; + return encodeBufferEventCommandResponse(this.events.filter(event => event.sequenceNumber >= from).slice(0, limit)); + } + + private handleBufferUpload(value: Buffer): Buffer { + const request = decodeBufferUploadCommand(value); + debug("buffer upload command %o", request); + + if (!this.cmafIngest) { + throw new HapStatusError(HAPStatus.RESOURCE_DOES_NOT_EXIST); + } + return encodeBufferUploadCommandResponse(this.cmafIngest.handleUploadCommand(request)); + } + + private async handleSetupEndpoints(value: Buffer, connection?: HAPConnection): Promise { + const request = decodeRTPSetupEndpoints(value); + debug("setup endpoints %o", request); + + const delegate = this.options.rtp.delegate; + if (!connection) { + return encodeRTPSetupEndpointsResponse(setupEndpointsError(request.sessionIdentifier)); + } + + const version = request.controllerAddress.version; + const sourceAddress = connection.getLocalAddress(version); + + try { + const response = await delegate.prepareStream({ + sessionIdentifier: request.sessionIdentifier, + addressVersion: version, + targetAddress: request.controllerAddress.address, + sourceAddress, + controllerVideoPort: request.controllerAddress.videoRTPPort, + controllerAudioPort: request.controllerAddress.audioRTPPort, + video: request.video, + audio: request.audio, + }); + return encodeRTPSetupEndpointsResponse({ + sessionIdentifier: request.sessionIdentifier, + status: 0, + accessoryAddress: { + version, + address: response.addressOverride ?? sourceAddress, + videoRTPPort: response.videoPort, + audioRTPPort: response.audioPort, + }, + video: response.video, + audio: response.audio, + videoSSRC: response.videoSSRC, + audioSSRC: response.audioSSRC, + }); + } catch (error) { + debug("setup endpoints failed: %s", error); + return encodeRTPSetupEndpointsResponse(setupEndpointsError(request.sessionIdentifier)); + } + } + + private async handleRTPStreamingControl(value: Buffer): Promise { + const request = decodeRTPStreamingControl(value); + debug("rtp streaming control %o", request); + + const delegate = this.options.rtp.delegate; + + try { + if (request.command === RTPStreamingCommand.START) { + if (!this.streamingAllowed(this.multiTierStreamManagementService)) { + return encodeSessionStatus(request.sessionIdentifier, RTPStreamingStatus.ERROR); + } + await delegate.startStream({ + sessionIdentifier: request.sessionIdentifier, + videoTier: request.videoTier ?? 0, + videoSSRC: request.videoSSRC ?? 0, + audioTier: request.audioTier, + audioSSRC: request.audioSSRC, + }); + } else { + await delegate.stopStream(request.sessionIdentifier); + } + return encodeSessionStatus(request.sessionIdentifier, RTPStreamingStatus.SUCCESS); + } catch (error) { + debug("rtp streaming control failed: %s", error); + return encodeSessionStatus(request.sessionIdentifier, RTPStreamingStatus.ERROR); + } + } + + private async handleSolicitOffer(value: Buffer): Promise { + const options = decodeWebRTCSolicitOffer(value); + const delegate = this.options.webrtc.delegate; + + if (!this.streamingAllowed(this.webrtcStreamManagementService)) { + const status = !this.homeKitCameraActive ? WebRTCSolicitOfferStatus.PRIVACY_MODE_ACTIVE : WebRTCSolicitOfferStatus.ERROR; + return encodeWebRTCSolicitOfferResponse({ status }); + } + + if (this.webrtcSessions.size >= (this.options.webrtc.maxSessions ?? DEFAULT_MAX_WEBRTC_SESSIONS)) { + return encodeWebRTCSolicitOfferResponse({ status: WebRTCSolicitOfferStatus.ERROR }); + } + + const sessionIdentifier = uuid.unparse(crypto.randomBytes(16)); + this.webrtcSessions.set(sessionIdentifier, { sessionIdentifier, answered: false }); + this.updateWebRTCSessionCount(); + + try { + const offer = await delegate.handleSolicitOffer({ sessionIdentifier, options }); + return encodeWebRTCSolicitOfferResponse({ + sessionIdentifier, + sdpOffer: offer.sdpOffer, + candidates: offer.candidates, + status: WebRTCSolicitOfferStatus.SUCCESS, + sframe: offer.sframe, + }); + } catch (error) { + debug("solicit offer failed: %s", error); + this.webrtcSessions.delete(sessionIdentifier); + this.updateWebRTCSessionCount(); + return encodeWebRTCSolicitOfferResponse({ status: WebRTCSolicitOfferStatus.ERROR }); + } + } + + private async handleProvideAnswer(value: Buffer): Promise { + const request = decodeWebRTCProvideAnswer(value); + const session = this.webrtcSessions.get(request.sessionIdentifier); + if (!session) { + return encodeSessionStatus(request.sessionIdentifier, WebRTCStreamingStatus.UNKNOWN_SESSION_IDENTIFIER); + } + + try { + await this.options.webrtc.delegate.handleProvideAnswer(request); + session.answered = true; + return encodeSessionStatus(request.sessionIdentifier, WebRTCStreamingStatus.SUCCESS); + } catch (error) { + debug("provide answer failed: %s", error); + await this.endWebRTCSession(request.sessionIdentifier).catch(() => undefined); + return encodeSessionStatus(request.sessionIdentifier, WebRTCStreamingStatus.ERROR); + } + } + + private async handleReoffer(value: Buffer): Promise { + const request = decodeWebRTCReoffer(value); + if (!this.webrtcSessions.has(request.sessionIdentifier)) { + return encodeWebRTCReofferResponse({ sessionIdentifier: request.sessionIdentifier, status: WebRTCStreamingStatus.UNKNOWN_SESSION_IDENTIFIER }); + } + + try { + const answer = await this.options.webrtc.delegate.handleReoffer(request); + return encodeWebRTCReofferResponse({ + sessionIdentifier: request.sessionIdentifier, + sdpAnswer: answer.sdpAnswer, + status: WebRTCStreamingStatus.SUCCESS, + sframe: answer.sframe, + }); + } catch (error) { + debug("reoffer failed: %s", error); + return encodeWebRTCReofferResponse({ sessionIdentifier: request.sessionIdentifier, status: WebRTCStreamingStatus.ERROR }); + } + } + + private async handleUpdateSession(value: Buffer): Promise { + const request = decodeWebRTCUpdateSession(value); + if (!this.webrtcSessions.has(request.sessionIdentifier)) { + return encodeSessionStatus(request.sessionIdentifier, WebRTCStreamingStatus.UNKNOWN_SESSION_IDENTIFIER); + } + + try { + await this.options.webrtc.delegate.handleUpdateSession(request); + return encodeSessionStatus(request.sessionIdentifier, WebRTCStreamingStatus.SUCCESS); + } catch (error) { + debug("update session failed: %s", error); + return encodeSessionStatus(request.sessionIdentifier, WebRTCStreamingStatus.ERROR); + } + } + + private async handleWebRTCStreamingControl(value: Buffer): Promise { + const request = decodeWebRTCStreamingControl(value); + if (!this.webrtcSessions.has(request.sessionIdentifier)) { + return encodeSessionStatus(request.sessionIdentifier, WebRTCStreamingStatus.UNKNOWN_SESSION_IDENTIFIER); + } + + try { + await this.endWebRTCSession(request.sessionIdentifier); + return encodeSessionStatus(request.sessionIdentifier, WebRTCStreamingStatus.SUCCESS); + } catch (error) { + debug("end session failed: %s", error); + return encodeSessionStatus(request.sessionIdentifier, WebRTCStreamingStatus.ERROR); + } + } + + private registerRead(characteristic: Characteristic, read: () => CharacteristicValue): void { + this.readHandlers.add(characteristic.UUID); + characteristic.onGet(() => this.lastResponses.get(characteristic.UUID) ?? read()); + } + + private handleTLVWrite(characteristic: Characteristic, handler: TLVWriteHandler): void { + const name = characteristic.displayName; + + if (!this.readHandlers.has(characteristic.UUID)) { + characteristic.onGet(() => this.lastResponses.get(characteristic.UUID) ?? ""); + } + + characteristic.onSet(async (value, _context, connection) => { + let response: Buffer | undefined; + try { + response = await handler(Buffer.from(String(value), "base64"), connection); + } catch (error) { + if (error instanceof HapStatusError) { + throw error; + } + debug("%s write failed: %s", name, error); + throw new HapStatusError(HAPStatus.INVALID_VALUE_IN_REQUEST); + } + + if (response === undefined) { + return; + } + + const encoded = response.toString("base64"); + this.lastResponses.set(characteristic.UUID, encoded); + + // Setup Endpoints has no write-response permission, the controller reads the result back instead + if (!characteristic.props.perms.includes(Perms.WRITE_RESPONSE)) { + return; + } + return encoded; + }); + } +} diff --git a/src/lib/controller/index.ts b/src/lib/controller/index.ts index 0926de155..76ea8284a 100644 --- a/src/lib/controller/index.ts +++ b/src/lib/controller/index.ts @@ -4,3 +4,4 @@ export * from "./AdaptiveLightingController"; export * from "./RemoteController"; export * from "./CameraController"; export * from "./DoorbellController"; +export * from "./SecureVideoController"; diff --git a/src/lib/definitions/CharacteristicDefinitions.spec.ts b/src/lib/definitions/CharacteristicDefinitions.spec.ts index 9e91dc7ca..89b47e0bc 100644 --- a/src/lib/definitions/CharacteristicDefinitions.spec.ts +++ b/src/lib/definitions/CharacteristicDefinitions.spec.ts @@ -112,18 +112,90 @@ describe("CharacteristicDefinitions", () => { }); }); + describe("BufferActivityCommand", () => { + it("should be able to construct", () => { + new Characteristic.BufferActivityCommand(); + }); + }); + + describe("BufferEventCommand", () => { + it("should be able to construct", () => { + new Characteristic.BufferEventCommand(); + }); + }); + + describe("BufferEventSequenceNumber", () => { + it("should be able to construct", () => { + new Characteristic.BufferEventSequenceNumber(); + }); + }); + + describe("BufferUploadCommand", () => { + it("should be able to construct", () => { + new Characteristic.BufferUploadCommand(); + }); + }); + describe("ButtonEvent", () => { it("should be able to construct", () => { new Characteristic.ButtonEvent(); }); }); + describe("CameraCapabilitiesConfiguration", () => { + it("should be able to construct", () => { + new Characteristic.CameraCapabilitiesConfiguration(); + }); + }); + + describe("CameraClientCertificate", () => { + it("should be able to construct", () => { + new Characteristic.CameraClientCertificate(); + }); + }); + + describe("CameraClientCertificateStatus", () => { + it("should be able to construct", () => { + new Characteristic.CameraClientCertificateStatus(); + }); + }); + + describe("CameraClientCSR", () => { + it("should be able to construct", () => { + new Characteristic.CameraClientCSR(); + }); + }); + + describe("CameraKey", () => { + it("should be able to construct", () => { + new Characteristic.CameraKey(); + }); + }); + + describe("CameraKeyID", () => { + it("should be able to construct", () => { + new Characteristic.CameraKeyID(); + }); + }); + describe("CameraOperatingModeIndicator", () => { it("should be able to construct", () => { new Characteristic.CameraOperatingModeIndicator(); }); }); + describe("CameraRecordingPublishingPoint", () => { + it("should be able to construct", () => { + new Characteristic.CameraRecordingPublishingPoint(); + }); + }); + + describe("CameraZones", () => { + it("should be able to construct", () => { + new Characteristic.CameraZones(); + }); + }); + describe("CarbonDioxideDetected", () => { it("should be able to construct", () => { new Characteristic.CarbonDioxideDetected(); @@ -226,6 +298,12 @@ describe("CharacteristicDefinitions", () => { }); }); + describe("ContributingSensors", () => { + it("should be able to construct", () => { + new Characteristic.ContributingSensors(); + }); + }); + describe("CoolingThresholdTemperature", () => { it("should be able to construct", () => { new Characteristic.CoolingThresholdTemperature(); @@ -640,6 +718,12 @@ describe("CharacteristicDefinitions", () => { }); }); + describe("MotionEnabled", () => { + it("should be able to construct", () => { + new Characteristic.MotionEnabled(); + }); + }); + describe("MultifunctionButton", () => { it("should be able to construct", () => { new Characteristic.MultifunctionButton(); @@ -922,6 +1006,12 @@ describe("CharacteristicDefinitions", () => { }); }); + describe("RTPStreamingControl", () => { + it("should be able to construct", () => { + new Characteristic.RTPStreamingControl(); + }); + }); + describe("Saturation", () => { it("should be able to construct", () => { new Characteristic.Saturation(); @@ -982,6 +1072,12 @@ describe("CharacteristicDefinitions", () => { }); }); + describe("SensorUUID", () => { + it("should be able to construct", () => { + new Characteristic.SensorUUID(); + }); + }); + describe("SerialNumber", () => { it("should be able to construct", () => { new Characteristic.SerialNumber(); @@ -1138,6 +1234,12 @@ describe("CharacteristicDefinitions", () => { }); }); + describe("StreamingEnabled", () => { + it("should be able to construct", () => { + new Characteristic.StreamingEnabled(); + }); + }); + describe("StreamingStatus", () => { it("should be able to construct", () => { new Characteristic.StreamingStatus(); @@ -1168,6 +1270,12 @@ describe("CharacteristicDefinitions", () => { }); }); + describe("SupportedAudioStreamTiers", () => { + it("should be able to construct", () => { + new Characteristic.SupportedAudioStreamTiers(); + }); + }); + describe("SupportedCameraRecordingConfiguration", () => { it("should be able to construct", () => { new Characteristic.SupportedCameraRecordingConfiguration(); @@ -1252,6 +1360,12 @@ describe("CharacteristicDefinitions", () => { }); }); + describe("SupportedVideoStreamTiers", () => { + it("should be able to construct", () => { + new Characteristic.SupportedVideoStreamTiers(); + }); + }); + describe("SwingMode", () => { it("should be able to construct", () => { new Characteristic.SwingMode(); @@ -1498,6 +1612,54 @@ describe("CharacteristicDefinitions", () => { }); }); + describe("WebRTCNumberOfActiveSessions", () => { + it("should be able to construct", () => { + new Characteristic.WebRTCNumberOfActiveSessions(); + }); + }); + + describe("WebRTCProvideAnswer", () => { + it("should be able to construct", () => { + new Characteristic.WebRTCProvideAnswer(); + }); + }); + + describe("WebRTCReoffer", () => { + it("should be able to construct", () => { + new Characteristic.WebRTCReoffer(); + }); + }); + + describe("WebRTCSolicitOffer", () => { + it("should be able to construct", () => { + new Characteristic.WebRTCSolicitOffer(); + }); + }); + + describe("WebRTCStreamingControl", () => { + it("should be able to construct", () => { + new Characteristic.WebRTCStreamingControl(); + }); + }); + + describe("WebRTCSupportedAudioStreamTiers", () => { + it("should be able to construct", () => { + new Characteristic.WebRTCSupportedAudioStreamTiers(); + }); + }); + + describe("WebRTCSupportedVideoStreamTiers", () => { + it("should be able to construct", () => { + new Characteristic.WebRTCSupportedVideoStreamTiers(); + }); + }); + + describe("WebRTCUpdateSession", () => { + it("should be able to construct", () => { + new Characteristic.WebRTCUpdateSession(); + }); + }); + describe("WiFiCapabilities", () => { it("should be able to construct", () => { new Characteristic.WiFiCapabilities(); diff --git a/src/lib/definitions/CharacteristicDefinitions.ts b/src/lib/definitions/CharacteristicDefinitions.ts index 0db9256ca..8b1c617a7 100644 --- a/src/lib/definitions/CharacteristicDefinitions.ts +++ b/src/lib/definitions/CharacteristicDefinitions.ts @@ -356,6 +356,78 @@ export class Brightness extends Characteristic { } Characteristic.Brightness = Brightness; +/** + * Characteristic "Buffer Activity Command" + * @since iOS 27 + */ +export class BufferActivityCommand extends Characteristic { + + public static readonly UUID: string = "00008017-0000-1000-8000-0026BB765291"; + + constructor() { + super("Buffer Activity Command", BufferActivityCommand.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_WRITE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.BufferActivityCommand = BufferActivityCommand; + +/** + * Characteristic "Buffer Event Command" + * @since iOS 27 + */ +export class BufferEventCommand extends Characteristic { + + public static readonly UUID: string = "00008014-0000-1000-8000-0026BB765291"; + + constructor() { + super("Buffer Event Command", BufferEventCommand.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.WRITE_RESPONSE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.BufferEventCommand = BufferEventCommand; + +/** + * Characteristic "Buffer Event Sequence Number" + * @since iOS 27 + */ +export class BufferEventSequenceNumber extends Characteristic { + + public static readonly UUID: string = "00008015-0000-1000-8000-0026BB765291"; + + constructor() { + super("Buffer Event Sequence Number", BufferEventSequenceNumber.UUID, { + format: Formats.UINT32, + perms: [Perms.NOTIFY, Perms.PAIRED_READ], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.BufferEventSequenceNumber = BufferEventSequenceNumber; + +/** + * Characteristic "Buffer Upload Command" + * @since iOS 27 + */ +export class BufferUploadCommand extends Characteristic { + + public static readonly UUID: string = "00008013-0000-1000-8000-0026BB765291"; + + constructor() { + super("Buffer Upload Command", BufferUploadCommand.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.WRITE_RESPONSE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.BufferUploadCommand = BufferUploadCommand; + /** * Characteristic "Button Event" */ @@ -374,6 +446,114 @@ export class ButtonEvent extends Characteristic { } Characteristic.ButtonEvent = ButtonEvent; +/** + * Characteristic "Camera Capabilities" + * @since iOS 27 + */ +export class CameraCapabilitiesConfiguration extends Characteristic { + + public static readonly UUID: string = "00008011-0000-1000-8000-0026BB765291"; + + constructor() { + super("Camera Capabilities", CameraCapabilitiesConfiguration.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.CameraCapabilitiesConfiguration = CameraCapabilitiesConfiguration; + +/** + * Characteristic "Camera Client Certificate" + * @since iOS 27 + */ +export class CameraClientCertificate extends Characteristic { + + public static readonly UUID: string = "00008082-0000-1000-8000-0026BB765291"; + + constructor() { + super("Camera Client Certificate", CameraClientCertificate.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.TIMED_WRITE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.CameraClientCertificate = CameraClientCertificate; + +/** + * Characteristic "Camera Client Certificate Status" + * @since iOS 27 + */ +export class CameraClientCertificateStatus extends Characteristic { + + public static readonly UUID: string = "00008083-0000-1000-8000-0026BB765291"; + + constructor() { + super("Camera Client Certificate Status", CameraClientCertificateStatus.UUID, { + format: Formats.TLV8, + perms: [Perms.NOTIFY, Perms.PAIRED_READ], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.CameraClientCertificateStatus = CameraClientCertificateStatus; + +/** + * Characteristic "Camera Client CSR" + * @since iOS 27 + */ +export class CameraClientCSR extends Characteristic { + + public static readonly UUID: string = "00008081-0000-1000-8000-0026BB765291"; + + constructor() { + super("Camera Client CSR", CameraClientCSR.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.WRITE_RESPONSE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.CameraClientCSR = CameraClientCSR; + +/** + * Characteristic "Camera Key" + * @since iOS 27 + */ +export class CameraKey extends Characteristic { + + public static readonly UUID: string = "00008051-0000-1000-8000-0026BB765291"; + + constructor() { + super("Camera Key", CameraKey.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_WRITE, Perms.TIMED_WRITE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.CameraKey = CameraKey; + +/** + * Characteristic "Camera Key ID" + * @since iOS 27 + */ +export class CameraKeyID extends Characteristic { + + public static readonly UUID: string = "00008052-0000-1000-8000-0026BB765291"; + + constructor() { + super("Camera Key ID", CameraKeyID.UUID, { + format: Formats.TLV8, + perms: [Perms.NOTIFY, Perms.PAIRED_READ], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.CameraKeyID = CameraKeyID; + /** * Characteristic "Camera Operating Mode Indicator" */ @@ -395,6 +575,42 @@ export class CameraOperatingModeIndicator extends Characteristic { } Characteristic.CameraOperatingModeIndicator = CameraOperatingModeIndicator; +/** + * Characteristic "Camera Recording Publishing Point" + * @since iOS 27 + */ +export class CameraRecordingPublishingPoint extends Characteristic { + + public static readonly UUID: string = "00008016-0000-1000-8000-0026BB765291"; + + constructor() { + super("Camera Recording Publishing Point", CameraRecordingPublishingPoint.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.CameraRecordingPublishingPoint = CameraRecordingPublishingPoint; + +/** + * Characteristic "Camera Zones" + * @since iOS 27 + */ +export class CameraZones extends Characteristic { + + public static readonly UUID: string = "00008022-0000-1000-8000-0026BB765291"; + + constructor() { + super("Camera Zones", CameraZones.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.CameraZones = CameraZones; + /** * Characteristic "Carbon Dioxide Detected" */ @@ -740,6 +956,24 @@ export class ContactSensorState extends Characteristic { } Characteristic.ContactSensorState = ContactSensorState; +/** + * Characteristic "Contributing Sensors" + * @since iOS 27 + */ +export class ContributingSensors extends Characteristic { + + public static readonly UUID: string = "00008086-0000-1000-8000-0026BB765291"; + + constructor() { + super("Contributing Sensors", ContributingSensors.UUID, { + format: Formats.TLV8, + perms: [Perms.NOTIFY, Perms.PAIRED_READ], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.ContributingSensors = ContributingSensors; + /** * Characteristic "Cooling Threshold Temperature" */ @@ -2173,6 +2407,25 @@ export class MotionDetected extends Characteristic { } Characteristic.MotionDetected = MotionDetected; +/** + * Characteristic "Motion Enabled" + * @since iOS 27 + */ +export class MotionEnabled extends Characteristic { + + public static readonly UUID: string = "00008087-0000-1000-8000-0026BB765291"; + + constructor() { + super("Motion Enabled", MotionEnabled.UUID, { + format: Formats.BOOL, + perms: [Perms.NOTIFY, Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.TIMED_WRITE], + adminOnlyAccess: [Access.WRITE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.MotionEnabled = MotionEnabled; + /** * Characteristic "Multifunction Button" */ @@ -3115,6 +3368,24 @@ export class RouterStatus extends Characteristic { } Characteristic.RouterStatus = RouterStatus; +/** + * Characteristic "RTP Streaming Control" + * @since iOS 27 + */ +export class RTPStreamingControl extends Characteristic { + + public static readonly UUID: string = "00008045-0000-1000-8000-0026BB765291"; + + constructor() { + super("RTP Streaming Control", RTPStreamingControl.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.WRITE_RESPONSE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.RTPStreamingControl = RTPStreamingControl; + /** * Characteristic "Saturation" */ @@ -3315,6 +3586,24 @@ export class SelectedSleepConfiguration extends Characteristic { } Characteristic.SelectedSleepConfiguration = SelectedSleepConfiguration; +/** + * Characteristic "Sensor UUID" + * @since iOS 27 + */ +export class SensorUUID extends Characteristic { + + public static readonly UUID: string = "0000805B-0000-1000-8000-0026BB765291"; + + constructor() { + super("Sensor UUID", SensorUUID.UUID, { + format: Formats.DATA, + perms: [Perms.PAIRED_READ], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.SensorUUID = SensorUUID; + /** * Characteristic "Serial Number" */ @@ -3839,6 +4128,25 @@ export class StatusTampered extends Characteristic { } Characteristic.StatusTampered = StatusTampered; +/** + * Characteristic "Streaming Enabled" + * @since iOS 27 + */ +export class StreamingEnabled extends Characteristic { + + public static readonly UUID: string = "00008041-0000-1000-8000-0026BB765291"; + + constructor() { + super("Streaming Enabled", StreamingEnabled.UUID, { + format: Formats.BOOL, + perms: [Perms.NOTIFY, Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.TIMED_WRITE], + adminOnlyAccess: [Access.WRITE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.StreamingEnabled = StreamingEnabled; + /** * Characteristic "Streaming Status" */ @@ -3927,6 +4235,24 @@ export class SupportedAudioStreamConfiguration extends Characteristic { } Characteristic.SupportedAudioStreamConfiguration = SupportedAudioStreamConfiguration; +/** + * Characteristic "Supported Audio Stream Tiers" + * @since iOS 27 + */ +export class SupportedAudioStreamTiers extends Characteristic { + + public static readonly UUID: string = "00008044-0000-1000-8000-0026BB765291"; + + constructor() { + super("Supported Audio Stream Tiers", SupportedAudioStreamTiers.UUID, { + format: Formats.TLV8, + perms: [Perms.NOTIFY, Perms.PAIRED_READ], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.SupportedAudioStreamTiers = SupportedAudioStreamTiers; + /** * Characteristic "Supported Camera Recording Configuration" */ @@ -4168,6 +4494,24 @@ export class SupportedVideoStreamConfiguration extends Characteristic { } Characteristic.SupportedVideoStreamConfiguration = SupportedVideoStreamConfiguration; +/** + * Characteristic "Supported Video Stream Tiers" + * @since iOS 27 + */ +export class SupportedVideoStreamTiers extends Characteristic { + + public static readonly UUID: string = "00008043-0000-1000-8000-0026BB765291"; + + constructor() { + super("Supported Video Stream Tiers", SupportedVideoStreamTiers.UUID, { + format: Formats.TLV8, + perms: [Perms.NOTIFY, Perms.PAIRED_READ], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.SupportedVideoStreamTiers = SupportedVideoStreamTiers; + /** * Characteristic "Swing Mode" */ @@ -5027,6 +5371,152 @@ export class WaterLevel extends Characteristic { } Characteristic.WaterLevel = WaterLevel; +/** + * Characteristic "WebRTC Number Of Active Sessions" + * @since iOS 27 + */ +export class WebRTCNumberOfActiveSessions extends Characteristic { + + public static readonly UUID: string = "00008057-0000-1000-8000-0026BB765291"; + + constructor() { + super("WebRTC Number Of Active Sessions", WebRTCNumberOfActiveSessions.UUID, { + format: Formats.UINT8, + perms: [Perms.NOTIFY, Perms.PAIRED_READ], + minValue: 0, + maxValue: 255, + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.WebRTCNumberOfActiveSessions = WebRTCNumberOfActiveSessions; + +/** + * Characteristic "WebRTC Provide Answer" + * @since iOS 27 + */ +export class WebRTCProvideAnswer extends Characteristic { + + public static readonly UUID: string = "00008054-0000-1000-8000-0026BB765291"; + + constructor() { + super("WebRTC Provide Answer", WebRTCProvideAnswer.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.WRITE_RESPONSE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.WebRTCProvideAnswer = WebRTCProvideAnswer; + +/** + * Characteristic "WebRTC Reoffer" + * @since iOS 27 + */ +export class WebRTCReoffer extends Characteristic { + + public static readonly UUID: string = "00008058-0000-1000-8000-0026BB765291"; + + constructor() { + super("WebRTC Reoffer", WebRTCReoffer.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.WRITE_RESPONSE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.WebRTCReoffer = WebRTCReoffer; + +/** + * Characteristic "WebRTC Solicit Offer" + * @since iOS 27 + */ +export class WebRTCSolicitOffer extends Characteristic { + + public static readonly UUID: string = "00008053-0000-1000-8000-0026BB765291"; + + constructor() { + super("WebRTC Solicit Offer", WebRTCSolicitOffer.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.WRITE_RESPONSE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.WebRTCSolicitOffer = WebRTCSolicitOffer; + +/** + * Characteristic "WebRTC Streaming Control" + * @since iOS 27 + */ +export class WebRTCStreamingControl extends Characteristic { + + public static readonly UUID: string = "00008056-0000-1000-8000-0026BB765291"; + + constructor() { + super("WebRTC Streaming Control", WebRTCStreamingControl.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.WRITE_RESPONSE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.WebRTCStreamingControl = WebRTCStreamingControl; + +/** + * Characteristic "WebRTC Supported Audio Stream Tiers" + * @since iOS 27 + */ +export class WebRTCSupportedAudioStreamTiers extends Characteristic { + + public static readonly UUID: string = "0000805A-0000-1000-8000-0026BB765291"; + + constructor() { + super("WebRTC Supported Audio Stream Tiers", WebRTCSupportedAudioStreamTiers.UUID, { + format: Formats.TLV8, + perms: [Perms.NOTIFY, Perms.PAIRED_READ], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.WebRTCSupportedAudioStreamTiers = WebRTCSupportedAudioStreamTiers; + +/** + * Characteristic "WebRTC Supported Video Stream Tiers" + * @since iOS 27 + */ +export class WebRTCSupportedVideoStreamTiers extends Characteristic { + + public static readonly UUID: string = "00008059-0000-1000-8000-0026BB765291"; + + constructor() { + super("WebRTC Supported Video Stream Tiers", WebRTCSupportedVideoStreamTiers.UUID, { + format: Formats.TLV8, + perms: [Perms.NOTIFY, Perms.PAIRED_READ], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.WebRTCSupportedVideoStreamTiers = WebRTCSupportedVideoStreamTiers; + +/** + * Characteristic "WebRTC Update Session" + * @since iOS 27 + */ +export class WebRTCUpdateSession extends Characteristic { + + public static readonly UUID: string = "0000805C-0000-1000-8000-0026BB765291"; + + constructor() { + super("WebRTC Update Session", WebRTCUpdateSession.UUID, { + format: Formats.TLV8, + perms: [Perms.PAIRED_READ, Perms.PAIRED_WRITE, Perms.WRITE_RESPONSE], + }); + this.value = this.getDefaultValue(); + } +} +Characteristic.WebRTCUpdateSession = WebRTCUpdateSession; + /** * Characteristic "Wi-Fi Capabilities" * @since iOS 14 diff --git a/src/lib/definitions/ServiceDefinitions.spec.ts b/src/lib/definitions/ServiceDefinitions.spec.ts index 2a17fe5d3..c41f62a2f 100644 --- a/src/lib/definitions/ServiceDefinitions.spec.ts +++ b/src/lib/definitions/ServiceDefinitions.spec.ts @@ -247,6 +247,160 @@ describe("ServiceDefinitions", () => { }); }); + describe("CameraBufferManagement", () => { + it("should be able to construct", () => { + const service0 = new Service.CameraBufferManagement(); + const service1 = new Service.CameraBufferManagement("test name"); + const service2 = new Service.CameraBufferManagement("test name", "test sub type"); + + expect(service0.displayName).toBe(""); + expect(service0.testCharacteristic(Characteristic.Name)).toBe(false); + expect(service0.subtype).toBeUndefined(); + + expect(service1.displayName).toBe("test name"); + expect(service1.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service1.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service1.subtype).toBeUndefined(); + + expect(service2.displayName).toBe("test name"); + expect(service2.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service2.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service2.subtype).toBe("test sub type"); + }); + }); + + describe("CameraCapabilities", () => { + it("should be able to construct", () => { + const service0 = new Service.CameraCapabilities(); + const service1 = new Service.CameraCapabilities("test name"); + const service2 = new Service.CameraCapabilities("test name", "test sub type"); + + expect(service0.displayName).toBe(""); + expect(service0.testCharacteristic(Characteristic.Name)).toBe(false); + expect(service0.subtype).toBeUndefined(); + + expect(service1.displayName).toBe("test name"); + expect(service1.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service1.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service1.subtype).toBeUndefined(); + + expect(service2.displayName).toBe("test name"); + expect(service2.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service2.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service2.subtype).toBe("test sub type"); + }); + }); + + describe("CameraClientCertificateManagement", () => { + it("should be able to construct", () => { + const service0 = new Service.CameraClientCertificateManagement(); + const service1 = new Service.CameraClientCertificateManagement("test name"); + const service2 = new Service.CameraClientCertificateManagement("test name", "test sub type"); + + expect(service0.displayName).toBe(""); + expect(service0.testCharacteristic(Characteristic.Name)).toBe(false); + expect(service0.subtype).toBeUndefined(); + + expect(service1.displayName).toBe("test name"); + expect(service1.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service1.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service1.subtype).toBeUndefined(); + + expect(service2.displayName).toBe("test name"); + expect(service2.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service2.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service2.subtype).toBe("test sub type"); + }); + }); + + describe("CameraGlobalOperatingMode", () => { + it("should be able to construct", () => { + const service0 = new Service.CameraGlobalOperatingMode(); + const service1 = new Service.CameraGlobalOperatingMode("test name"); + const service2 = new Service.CameraGlobalOperatingMode("test name", "test sub type"); + + expect(service0.displayName).toBe(""); + expect(service0.testCharacteristic(Characteristic.Name)).toBe(false); + expect(service0.subtype).toBeUndefined(); + + expect(service1.displayName).toBe("test name"); + expect(service1.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service1.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service1.subtype).toBeUndefined(); + + expect(service2.displayName).toBe("test name"); + expect(service2.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service2.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service2.subtype).toBe("test sub type"); + }); + }); + + describe("CameraKeyManagement", () => { + it("should be able to construct", () => { + const service0 = new Service.CameraKeyManagement(); + const service1 = new Service.CameraKeyManagement("test name"); + const service2 = new Service.CameraKeyManagement("test name", "test sub type"); + + expect(service0.displayName).toBe(""); + expect(service0.testCharacteristic(Characteristic.Name)).toBe(false); + expect(service0.subtype).toBeUndefined(); + + expect(service1.displayName).toBe("test name"); + expect(service1.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service1.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service1.subtype).toBeUndefined(); + + expect(service2.displayName).toBe("test name"); + expect(service2.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service2.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service2.subtype).toBe("test sub type"); + }); + }); + + describe("CameraMotionZones", () => { + it("should be able to construct", () => { + const service0 = new Service.CameraMotionZones(); + const service1 = new Service.CameraMotionZones("test name"); + const service2 = new Service.CameraMotionZones("test name", "test sub type"); + + expect(service0.displayName).toBe(""); + expect(service0.testCharacteristic(Characteristic.Name)).toBe(false); + expect(service0.subtype).toBeUndefined(); + + expect(service1.displayName).toBe("test name"); + expect(service1.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service1.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service1.subtype).toBeUndefined(); + + expect(service2.displayName).toBe("test name"); + expect(service2.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service2.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service2.subtype).toBe("test sub type"); + }); + }); + + describe("CameraMultiTierRTPStreamManagement", () => { + it("should be able to construct", () => { + const service0 = new Service.CameraMultiTierRTPStreamManagement(); + const service1 = new Service.CameraMultiTierRTPStreamManagement("test name"); + const service2 = new Service.CameraMultiTierRTPStreamManagement("test name", "test sub type"); + + expect(service0.displayName).toBe(""); + expect(service0.testCharacteristic(Characteristic.Name)).toBe(false); + expect(service0.subtype).toBeUndefined(); + + expect(service1.displayName).toBe("test name"); + expect(service1.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service1.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service1.subtype).toBeUndefined(); + + expect(service2.displayName).toBe("test name"); + expect(service2.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service2.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service2.subtype).toBe("test sub type"); + }); + }); + describe("CameraOperatingMode", () => { it("should be able to construct", () => { const service0 = new Service.CameraOperatingMode(); @@ -313,6 +467,28 @@ describe("ServiceDefinitions", () => { }); }); + describe("CameraWebRTCStreamManagement", () => { + it("should be able to construct", () => { + const service0 = new Service.CameraWebRTCStreamManagement(); + const service1 = new Service.CameraWebRTCStreamManagement("test name"); + const service2 = new Service.CameraWebRTCStreamManagement("test name", "test sub type"); + + expect(service0.displayName).toBe(""); + expect(service0.testCharacteristic(Characteristic.Name)).toBe(false); + expect(service0.subtype).toBeUndefined(); + + expect(service1.displayName).toBe("test name"); + expect(service1.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service1.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service1.subtype).toBeUndefined(); + + expect(service2.displayName).toBe("test name"); + expect(service2.testCharacteristic(Characteristic.Name)).toBe(true); + expect(service2.getCharacteristic(Characteristic.Name).value).toBe("test name"); + expect(service2.subtype).toBe("test sub type"); + }); + }); + describe("CarbonDioxideSensor", () => { it("should be able to construct", () => { const service0 = new Service.CarbonDioxideSensor(); diff --git a/src/lib/definitions/ServiceDefinitions.ts b/src/lib/definitions/ServiceDefinitions.ts index b503e3303..93b0cdd5d 100644 --- a/src/lib/definitions/ServiceDefinitions.ts +++ b/src/lib/definitions/ServiceDefinitions.ts @@ -246,6 +246,152 @@ export class Battery extends Service { } Service.Battery = Battery; +/** + * Service "Camera Buffer Management" + * @since iOS 27 + */ +export class CameraBufferManagement extends Service { + + public static readonly UUID: string = "00008000-0000-1000-8000-0026BB765291"; + + constructor(displayName?: string, subtype?: string) { + super(displayName, CameraBufferManagement.UUID, subtype); + + // Required Characteristics + this.addCharacteristic(Characteristic.BufferActivityCommand); + this.addCharacteristic(Characteristic.BufferEventCommand); + this.addCharacteristic(Characteristic.BufferEventSequenceNumber); + this.addCharacteristic(Characteristic.BufferUploadCommand); + this.addCharacteristic(Characteristic.CameraRecordingPublishingPoint); + } +} +Service.CameraBufferManagement = CameraBufferManagement; + +/** + * Service "Camera Capabilities" + * @since iOS 27 + */ +export class CameraCapabilities extends Service { + + public static readonly UUID: string = "00008010-0000-1000-8000-0026BB765291"; + + constructor(displayName?: string, subtype?: string) { + super(displayName, CameraCapabilities.UUID, subtype); + + // Required Characteristics + this.addCharacteristic(Characteristic.CameraCapabilitiesConfiguration); + this.addCharacteristic(Characteristic.Version); + + // Optional Characteristics + this.addOptionalCharacteristic(Characteristic.ManuallyDisabled); + } +} +Service.CameraCapabilities = CameraCapabilities; + +/** + * Service "Camera Client Certificate Management" + * @since iOS 27 + */ +export class CameraClientCertificateManagement extends Service { + + public static readonly UUID: string = "00008080-0000-1000-8000-0026BB765291"; + + constructor(displayName?: string, subtype?: string) { + super(displayName, CameraClientCertificateManagement.UUID, subtype); + + // Required Characteristics + this.addCharacteristic(Characteristic.CameraClientCertificate); + this.addCharacteristic(Characteristic.CameraClientCertificateStatus); + this.addCharacteristic(Characteristic.CameraClientCSR); + } +} +Service.CameraClientCertificateManagement = CameraClientCertificateManagement; + +/** + * Service "Camera Global Operating Mode" + * @since iOS 27 + */ +export class CameraGlobalOperatingMode extends Service { + + public static readonly UUID: string = "00008032-0000-1000-8000-0026BB765291"; + + constructor(displayName?: string, subtype?: string) { + super(displayName, CameraGlobalOperatingMode.UUID, subtype); + + // Required Characteristics + this.addCharacteristic(Characteristic.CameraOperatingModeIndicator); + this.addCharacteristic(Characteristic.HomeKitCameraActive); + this.addCharacteristic(Characteristic.StreamingEnabled); + + // Optional Characteristics + this.addOptionalCharacteristic(Characteristic.ManuallyDisabled); + this.addOptionalCharacteristic(Characteristic.NightVision); + this.addOptionalCharacteristic(Characteristic.ThirdPartyCameraActive); + } +} +Service.CameraGlobalOperatingMode = CameraGlobalOperatingMode; + +/** + * Service "Camera Key Management" + * @since iOS 27 + */ +export class CameraKeyManagement extends Service { + + public static readonly UUID: string = "00008050-0000-1000-8000-0026BB765291"; + + constructor(displayName?: string, subtype?: string) { + super(displayName, CameraKeyManagement.UUID, subtype); + + // Required Characteristics + this.addCharacteristic(Characteristic.CameraKey); + this.addCharacteristic(Characteristic.CameraKeyID); + } +} +Service.CameraKeyManagement = CameraKeyManagement; + +/** + * Service "Camera Motion Zones" + * @since iOS 27 + */ +export class CameraMotionZones extends Service { + + public static readonly UUID: string = "00008021-0000-1000-8000-0026BB765291"; + + constructor(displayName?: string, subtype?: string) { + super(displayName, CameraMotionZones.UUID, subtype); + + // Required Characteristics + this.addCharacteristic(Characteristic.Active); + this.addCharacteristic(Characteristic.CameraZones); + this.addCharacteristic(Characteristic.Version); + } +} +Service.CameraMotionZones = CameraMotionZones; + +/** + * Service "Camera Multi-Tier RTP Stream Management" + * @since iOS 27 + */ +export class CameraMultiTierRTPStreamManagement extends Service { + + public static readonly UUID: string = "00008031-0000-1000-8000-0026BB765291"; + + constructor(displayName?: string, subtype?: string) { + super(displayName, CameraMultiTierRTPStreamManagement.UUID, subtype); + + // Required Characteristics + this.addCharacteristic(Characteristic.RTPStreamingControl); + this.addCharacteristic(Characteristic.SensorUUID); + this.addCharacteristic(Characteristic.SetupEndpoints); + this.addCharacteristic(Characteristic.StatusActive); + this.addCharacteristic(Characteristic.StreamingEnabled); + this.addCharacteristic(Characteristic.SupportedAudioStreamTiers); + this.addCharacteristic(Characteristic.SupportedRTPConfiguration); + this.addCharacteristic(Characteristic.SupportedVideoStreamTiers); + } +} +Service.CameraMultiTierRTPStreamManagement = CameraMultiTierRTPStreamManagement; + /** * Service "Camera Operating Mode" */ @@ -318,6 +464,32 @@ export class CameraRTPStreamManagement extends Service { } Service.CameraRTPStreamManagement = CameraRTPStreamManagement; +/** + * Service "Camera WebRTC Stream Management" + * @since iOS 27 + */ +export class CameraWebRTCStreamManagement extends Service { + + public static readonly UUID: string = "00008033-0000-1000-8000-0026BB765291"; + + constructor(displayName?: string, subtype?: string) { + super(displayName, CameraWebRTCStreamManagement.UUID, subtype); + + // Required Characteristics + this.addCharacteristic(Characteristic.SensorUUID); + this.addCharacteristic(Characteristic.StreamingEnabled); + this.addCharacteristic(Characteristic.WebRTCNumberOfActiveSessions); + this.addCharacteristic(Characteristic.WebRTCProvideAnswer); + this.addCharacteristic(Characteristic.WebRTCReoffer); + this.addCharacteristic(Characteristic.WebRTCSolicitOffer); + this.addCharacteristic(Characteristic.WebRTCStreamingControl); + this.addCharacteristic(Characteristic.WebRTCSupportedAudioStreamTiers); + this.addCharacteristic(Characteristic.WebRTCSupportedVideoStreamTiers); + this.addCharacteristic(Characteristic.WebRTCUpdateSession); + } +} +Service.CameraWebRTCStreamManagement = CameraWebRTCStreamManagement; + /** * Service "Carbon Dioxide Sensor" */ @@ -908,6 +1080,8 @@ export class MotionSensor extends Service { this.addCharacteristic(Characteristic.MotionDetected); // Optional Characteristics + this.addOptionalCharacteristic(Characteristic.ContributingSensors); + this.addOptionalCharacteristic(Characteristic.MotionEnabled); this.addOptionalCharacteristic(Characteristic.Name); this.addOptionalCharacteristic(Characteristic.StatusActive); this.addOptionalCharacteristic(Characteristic.StatusFault); diff --git a/src/lib/definitions/generator-configuration.ts b/src/lib/definitions/generator-configuration.ts index e4b6991d3..c507d29b1 100644 --- a/src/lib/definitions/generator-configuration.ts +++ b/src/lib/definitions/generator-configuration.ts @@ -305,6 +305,253 @@ export const CharacteristicManualAdditions: Map format: "int", properties: 3, // read, notify }], + ["sensor-uuid", { + id: "sensor-uuid", + UUID: "0000805B-0000-1000-8000-0026BB765291", + name: "Sensor UUID", + className: "SensorUUID", + since: "27", + format: "data", + properties: 2, // read + }], + ["motion-enabled", { + id: "motion-enabled", + UUID: "00008087-0000-1000-8000-0026BB765291", + name: "Motion Enabled", + className: "MotionEnabled", + since: "27", + format: "bool", + properties: 39, // notify, read, write, timed write + adminOnlyAccess: [Access.WRITE], + }], + ["supported-video-stream-tiers", { + id: "supported-video-stream-tiers", + UUID: "00008043-0000-1000-8000-0026BB765291", + name: "Supported Video Stream Tiers", + className: "SupportedVideoStreamTiers", + since: "27", + format: "tlv8", + properties: 3, // notify, read + }], + ["supported-audio-stream-tiers", { + id: "supported-audio-stream-tiers", + UUID: "00008044-0000-1000-8000-0026BB765291", + name: "Supported Audio Stream Tiers", + className: "SupportedAudioStreamTiers", + since: "27", + format: "tlv8", + properties: 3, // notify, read + }], + ["camera-capabilities", { + id: "camera-capabilities", + UUID: "00008011-0000-1000-8000-0026BB765291", + name: "Camera Capabilities", + className: "CameraCapabilitiesConfiguration", + since: "27", + format: "tlv8", + properties: 2, // read + }], + ["contributing-sensors", { + id: "contributing-sensors", + UUID: "00008086-0000-1000-8000-0026BB765291", + name: "Contributing Sensors", + className: "ContributingSensors", + since: "27", + format: "tlv8", + properties: 3, // notify, read + }], + ["camera-key", { + id: "camera-key", + UUID: "00008051-0000-1000-8000-0026BB765291", + name: "Camera Key", + className: "CameraKey", + since: "27", + format: "tlv8", + properties: 36, // write, timed write + }], + ["camera-key-id", { + id: "camera-key-id", + UUID: "00008052-0000-1000-8000-0026BB765291", + name: "Camera Key ID", + className: "CameraKeyID", + since: "27", + format: "tlv8", + properties: 3, // notify, read + }], + ["camera-buffer-command", { + id: "camera-buffer-command", + UUID: "00008013-0000-1000-8000-0026BB765291", + name: "Buffer Upload Command", + className: "BufferUploadCommand", + since: "27", + format: "tlv8", + properties: 134, // read, write, write response + }], + ["camera-activity-command", { + id: "camera-activity-command", + UUID: "00008017-0000-1000-8000-0026BB765291", + name: "Buffer Activity Command", + className: "BufferActivityCommand", + since: "27", + format: "tlv8", + properties: 4, // write + }], + ["camera-buffer-event-command", { + id: "camera-buffer-event-command", + UUID: "00008014-0000-1000-8000-0026BB765291", + name: "Buffer Event Command", + className: "BufferEventCommand", + since: "27", + format: "tlv8", + properties: 134, // read, write, write response + }], + ["camera-buffer-event-sequence-number", { + id: "camera-buffer-event-sequence-number", + UUID: "00008015-0000-1000-8000-0026BB765291", + name: "Buffer Event Sequence Number", + className: "BufferEventSequenceNumber", + since: "27", + format: "uint32", + properties: 3, // notify, read + }], + ["camera-recording-publishing-point", { + id: "camera-recording-publishing-point", + UUID: "00008016-0000-1000-8000-0026BB765291", + name: "Camera Recording Publishing Point", + className: "CameraRecordingPublishingPoint", + since: "27", + format: "tlv8", + properties: 6, // read, write + }], + ["camera-zones", { + id: "camera-zones", + UUID: "00008022-0000-1000-8000-0026BB765291", + name: "Camera Zones", + className: "CameraZones", + since: "27", + format: "tlv8", + properties: 6, // read, write + }], + ["streaming-enabled", { + id: "streaming-enabled", + UUID: "00008041-0000-1000-8000-0026BB765291", + name: "Streaming Enabled", + className: "StreamingEnabled", + since: "27", + format: "bool", + properties: 39, // notify, read, write, timed write + adminOnlyAccess: [Access.WRITE], + }], + ["rtp-streaming-control", { + id: "rtp-streaming-control", + UUID: "00008045-0000-1000-8000-0026BB765291", + name: "RTP Streaming Control", + className: "RTPStreamingControl", + since: "27", + format: "tlv8", + properties: 134, // read, write, write response + }], + ["webrtc-solicit-offer", { + id: "webrtc-solicit-offer", + UUID: "00008053-0000-1000-8000-0026BB765291", + name: "WebRTC Solicit Offer", + className: "WebRTCSolicitOffer", + since: "27", + format: "tlv8", + properties: 134, // read, write, write response + }], + ["webrtc-provide-answer", { + id: "webrtc-provide-answer", + UUID: "00008054-0000-1000-8000-0026BB765291", + name: "WebRTC Provide Answer", + className: "WebRTCProvideAnswer", + since: "27", + format: "tlv8", + properties: 134, // read, write, write response + }], + ["webrtc-streaming-control", { + id: "webrtc-streaming-control", + UUID: "00008056-0000-1000-8000-0026BB765291", + name: "WebRTC Streaming Control", + className: "WebRTCStreamingControl", + since: "27", + format: "tlv8", + properties: 134, // read, write, write response + }], + ["webrtc-number-of-active-sessions", { + id: "webrtc-number-of-active-sessions", + UUID: "00008057-0000-1000-8000-0026BB765291", + name: "WebRTC Number Of Active Sessions", + className: "WebRTCNumberOfActiveSessions", + since: "27", + format: "uint8", + properties: 3, // notify, read + minValue: 0, + maxValue: 255, + }], + ["webrtc-reoffer", { + id: "webrtc-reoffer", + UUID: "00008058-0000-1000-8000-0026BB765291", + name: "WebRTC Reoffer", + className: "WebRTCReoffer", + since: "27", + format: "tlv8", + properties: 134, // read, write, write response + }], + ["webrtc-update-session", { + id: "webrtc-update-session", + UUID: "0000805C-0000-1000-8000-0026BB765291", + name: "WebRTC Update Session", + className: "WebRTCUpdateSession", + since: "27", + format: "tlv8", + properties: 134, // read, write, write response + }], + ["webrtc-supported-video-stream-tiers", { + id: "webrtc-supported-video-stream-tiers", + UUID: "00008059-0000-1000-8000-0026BB765291", + name: "WebRTC Supported Video Stream Tiers", + className: "WebRTCSupportedVideoStreamTiers", + since: "27", + format: "tlv8", + properties: 3, // notify, read + }], + ["webrtc-supported-audio-stream-tiers", { + id: "webrtc-supported-audio-stream-tiers", + UUID: "0000805A-0000-1000-8000-0026BB765291", + name: "WebRTC Supported Audio Stream Tiers", + className: "WebRTCSupportedAudioStreamTiers", + since: "27", + format: "tlv8", + properties: 3, // notify, read + }], + ["camera-client-csr", { + id: "camera-client-csr", + UUID: "00008081-0000-1000-8000-0026BB765291", + name: "Camera Client CSR", + className: "CameraClientCSR", + since: "27", + format: "tlv8", + properties: 134, // read, write, write response + }], + ["camera-client-certificate", { + id: "camera-client-certificate", + UUID: "00008082-0000-1000-8000-0026BB765291", + name: "Camera Client Certificate", + className: "CameraClientCertificate", + since: "27", + format: "tlv8", + properties: 38, // read, write, timed write + }], + ["camera-client-certificate-status", { + id: "camera-client-certificate-status", + UUID: "00008083-0000-1000-8000-0026BB765291", + name: "Camera Client Certificate Status", + className: "CameraClientCertificateStatus", + since: "27", + format: "tlv8", + properties: 3, // notify, read + }], ]); export const ServiceNameOverrides: Map = new Map([ @@ -329,6 +576,7 @@ interface CharacteristicConfigurationOverride { export const ServiceCharacteristicConfigurationOverrides: Map = new Map([ ["accessory-information", { addedRequired: ["firmware.revision"], removedOptional: ["firmware.revision"] }], ["camera-operating-mode", { addedOptional: ["diagonal-field-of-view"] }], + ["sensor.motion", { addedOptional: ["contributing-sensors", "motion-enabled"] }], ]); export const ServiceManualAdditions: Map = new Map([ @@ -380,6 +628,81 @@ export const ServiceManualAdditions: Map = new Map([ "tunneled-accessory-state-number", ], }], + ["camera-capabilities", { + id: "camera-capabilities", + UUID: "00008010-0000-1000-8000-0026BB765291", + name: "Camera Capabilities", + className: "CameraCapabilities", + since: "27", + requiredCharacteristics: ["version", "camera-capabilities"], + optionalCharacteristics: ["manually-disabled"], + }], + ["camera-global-operating-mode", { + id: "camera-global-operating-mode", + UUID: "00008032-0000-1000-8000-0026BB765291", + name: "Camera Global Operating Mode", + className: "CameraGlobalOperatingMode", + since: "27", + requiredCharacteristics: ["homekit-camera-active", "streaming-enabled", "camera-operating-mode-indicator"], + optionalCharacteristics: ["manually-disabled", "night-vision", "third-party-camera-active"], + }], + ["camera-motion-zones", { + id: "camera-motion-zones", + UUID: "00008021-0000-1000-8000-0026BB765291", + name: "Camera Motion Zones", + className: "CameraMotionZones", + since: "27", + requiredCharacteristics: ["version", "active", "camera-zones"], + }], + ["camera-buffer-management", { + id: "camera-buffer-management", + UUID: "00008000-0000-1000-8000-0026BB765291", + name: "Camera Buffer Management", + className: "CameraBufferManagement", + since: "27", + requiredCharacteristics: [ + "camera-buffer-command", "camera-activity-command", "camera-buffer-event-command", "camera-buffer-event-sequence-number", + "camera-recording-publishing-point", + ], + }], + ["camera-multi-tier-rtp-stream-management", { + id: "camera-multi-tier-rtp-stream-management", + UUID: "00008031-0000-1000-8000-0026BB765291", + name: "Camera Multi-Tier RTP Stream Management", + className: "CameraMultiTierRTPStreamManagement", + since: "27", + requiredCharacteristics: [ + "streaming-enabled", "status-active", "supported-video-stream-tiers", "supported-audio-stream-tiers", "supported-rtp-configuration", + "setup-stream-endpoint", "rtp-streaming-control", "sensor-uuid", + ], + }], + ["camera-webrtc-stream-management", { + id: "camera-webrtc-stream-management", + UUID: "00008033-0000-1000-8000-0026BB765291", + name: "Camera WebRTC Stream Management", + className: "CameraWebRTCStreamManagement", + since: "27", + requiredCharacteristics: [ + "webrtc-solicit-offer", "webrtc-provide-answer", "webrtc-streaming-control", "webrtc-number-of-active-sessions", "webrtc-reoffer", + "webrtc-update-session", "webrtc-supported-video-stream-tiers", "webrtc-supported-audio-stream-tiers", "streaming-enabled", "sensor-uuid", + ], + }], + ["camera-key-management", { + id: "camera-key-management", + UUID: "00008050-0000-1000-8000-0026BB765291", + name: "Camera Key Management", + className: "CameraKeyManagement", + since: "27", + requiredCharacteristics: ["camera-key", "camera-key-id"], + }], + ["camera-client-certificate-management", { + id: "camera-client-certificate-management", + UUID: "00008080-0000-1000-8000-0026BB765291", + name: "Camera Client Certificate Management", + className: "CameraClientCertificateManagement", + since: "27", + requiredCharacteristics: ["camera-client-csr", "camera-client-certificate", "camera-client-certificate-status"], + }], ]); export const CharacteristicSinceInformation: Map = new Map([ From 1c15e2dcf77917086e3b402de7bd94e264891448 Mon Sep 17 00:00:00 2001 From: seydx Date: Tue, 15 Sep 2026 02:17:05 +0200 Subject: [PATCH 2/4] serve the image resource request from the secure video controller --- src/lib/Accessory.spec.ts | 19 +++++- src/lib/Accessory.ts | 9 +-- src/lib/camera/HDSSnapshotTransport.ts | 7 ++- src/lib/controller/Controller.ts | 27 ++++++++ .../controller/SecureVideoController.spec.ts | 26 +++++++- src/lib/controller/SecureVideoController.ts | 61 +++++++++++++++++-- 6 files changed, 137 insertions(+), 12 deletions(-) diff --git a/src/lib/Accessory.spec.ts b/src/lib/Accessory.spec.ts index 1aa9c1c7c..a8abb7c66 100644 --- a/src/lib/Accessory.spec.ts +++ b/src/lib/Accessory.spec.ts @@ -27,7 +27,7 @@ import { Perms, Units, } from "./Characteristic"; -import { CameraController, Controller, ControllerIdentifier, ControllerServiceMap } from "./controller"; +import { CameraController, Controller, ControllerIdentifier, ControllerServiceMap, ResourceRequestReason, SnapshotController } from "./controller"; import { createCameraControllerOptions, MOCK_IMAGE } from "./controller/CameraController.spec"; import { HAPHTTPCode, HAPStatus, IdentifyCallback, TLVErrorCode } from "./HAPServer"; import { AccessoryInfo, PairingInformation, PermissionTypes } from "./model/AccessoryInfo"; @@ -1998,6 +1998,23 @@ describe("Accessory", () => { expect(callback).toHaveBeenCalledWith(undefined, MOCK_IMAGE); }); + test("retrieve image resource from any snapshot controller", async () => { + accessory.removeController(cameraController); + const snapshotController: SnapshotController = { + controllerId: () => "snapshot", + constructServices: () => ({}), + initWithServices: () => undefined, + configureServices: () => undefined, + handleControllerRemoved: () => undefined, + handleSnapshotRequest: jest.fn().mockResolvedValue(MOCK_IMAGE), + }; + accessory.configureController(snapshotController); + + await testRequestResponse({ reason: ResourceRequestReason.PERIODIC }); + expect(callback).toHaveBeenCalledWith(undefined, MOCK_IMAGE); + expect(snapshotController.handleSnapshotRequest).toHaveBeenCalledWith(200, 200, accessory.displayName, ResourceRequestReason.PERIODIC); + }); + test("retrieve image resource on bridge", async () => { accessory.addBridgedAccessory(new Accessory("Bridged accessory", uuid.generate("bridged"))); accessory._assignIDs(accessory._identifierCache!); diff --git a/src/lib/Accessory.ts b/src/lib/Accessory.ts index daf350071..072f3d65b 100644 --- a/src/lib/Accessory.ts +++ b/src/lib/Accessory.ts @@ -41,12 +41,13 @@ import { isValidPerms, } from "./Characteristic"; import { - CameraController, Controller, ControllerConstructor, ControllerIdentifier, ControllerServiceMap, isSerializableController, + isSnapshotController, + SnapshotController, } from "./controller"; import { AccessoriesCallback, @@ -429,7 +430,7 @@ export class Accessory extends EventEmitter { private controllers: Record = {}; private serializedControllers?: Record; // store uninitialized controller data after a Accessory.deserialize call - private activeCameraController?: CameraController; + private activeCameraController?: SnapshotController; /** * @private Private API. @@ -812,7 +813,7 @@ export class Accessory extends EventEmitter { this.controllers[id] = context; - if (controller instanceof CameraController) { // save CameraController for Snapshot handling + if (isSnapshotController(controller)) { // save the controller for snapshot handling this.activeCameraController = controller; } } @@ -1928,7 +1929,7 @@ export class Accessory extends EventEmitter { const aid = data.aid; // aid is optionally supplied by HomeKit (for example when camera is bridged, multiple cams, etc) let accessory: Accessory | undefined = undefined; - let controller: CameraController | undefined = undefined; + let controller: SnapshotController | undefined = undefined; if (aid) { accessory = this.getAccessoryByAID(aid); if (accessory && accessory.activeCameraController) { diff --git a/src/lib/camera/HDSSnapshotTransport.ts b/src/lib/camera/HDSSnapshotTransport.ts index 568919cfa..b6aa5114c 100644 --- a/src/lib/camera/HDSSnapshotTransport.ts +++ b/src/lib/camera/HDSSnapshotTransport.ts @@ -11,17 +11,20 @@ import { Topics, } from "../datastream"; +import type { SnapshotRequest } from "./RTPStreamManagement"; + const debug = createDebug("HAP-NodeJS:SecureVideo:Snapshot"); const CHUNK_SIZE = 0x40000; const TIMEOUT_MS = 25000; /** - * Produces a JPEG snapshot for the HDS `ipcamera.snapshot` relay. + * Produces a JPEG snapshot for the secure video camera. The HAP image resource request passes the requested + * size and reason, the HDS `ipcamera.snapshot` relay carries no such information and calls without a request. * * @group Camera Secure Video */ -export type SecureVideoSnapshotHandler = () => Promise; +export type SecureVideoSnapshotHandler = (request?: SnapshotRequest) => Promise; interface SnapshotTransfer { connection: DataStreamConnection; diff --git a/src/lib/controller/Controller.ts b/src/lib/controller/Controller.ts index af186cbb6..9bef0e639 100644 --- a/src/lib/controller/Controller.ts +++ b/src/lib/controller/Controller.ts @@ -1,5 +1,7 @@ import { Service } from "../Service"; +import type { ResourceRequestReason } from "./CameraController"; + /** * A ControllerServiceMap represents all services used by a Controller. * It is up to the Controller to choose unique and persistent names for its services. @@ -194,3 +196,28 @@ export interface SerializableController extends Controller { + /** + * @param height - requested image height + * @param width - requested image width + * @param accessoryName - display name of the accessory, for log output + * @param reason - reason of the request, if supplied by the controller + * @returns the JPEG image, or rejects with a {@link HAPStatus} + */ + handleSnapshotRequest(height: number, width: number, accessoryName?: string, reason?: ResourceRequestReason): Promise; +} + +/** + * @param controller + * @group Controller API + */ +export function isSnapshotController(controller: Controller): controller is SnapshotController { + return typeof (controller as SnapshotController).handleSnapshotRequest === "function"; +} diff --git a/src/lib/controller/SecureVideoController.spec.ts b/src/lib/controller/SecureVideoController.spec.ts index 241990669..3745c99b3 100644 --- a/src/lib/controller/SecureVideoController.spec.ts +++ b/src/lib/controller/SecureVideoController.spec.ts @@ -18,9 +18,10 @@ import { import { Accessory } from "../Accessory"; import { Characteristic } from "../Characteristic"; import "../definitions"; +import { HAPStatus } from "../HAPServer"; import { Service } from "../Service"; import * as uuid from "../util/uuid"; -import { CameraRecordingDelegate } from "./CameraController"; +import { CameraRecordingDelegate, ResourceRequestReason } from "./CameraController"; import { MultiTierRTPStreamingDelegate, SecureVideoController, SecureVideoControllerOptions, WebRTCStreamingDelegate } from "./SecureVideoController"; const recordingOptions: CameraRecordingOptions = { @@ -63,6 +64,7 @@ describe("SecureVideoController", () => { let controller: SecureVideoController; let webrtc: jest.Mocked; let rtp: jest.Mocked; + let snapshot: jest.Mock; beforeEach(() => { webrtc = { @@ -78,6 +80,8 @@ describe("SecureVideoController", () => { stopStream: jest.fn().mockResolvedValue(undefined), }; + snapshot = jest.fn().mockResolvedValue(Buffer.from([0xff, 0xd8, 0xff, 0xd9])); + const options: SecureVideoControllerOptions = { sensor: { uuid: uuid.generate("sensor"), width: 1920, height: 1080 }, video: { @@ -91,6 +95,7 @@ describe("SecureVideoController", () => { webrtc: { delegate: webrtc, maxSessions: 1 }, rtp: { delegate: rtp }, recording: { options: recordingOptions, delegate: recordingDelegate }, + snapshot, ingest: { delegate: { // eslint-disable-next-line require-yield @@ -229,6 +234,25 @@ describe("SecureVideoController", () => { expect(recording.getCharacteristic(Characteristic.SupportedCameraRecordingConfiguration).value).toBeDefined(); }); + test("serves the image resource request through the snapshot handler", async () => { + await expect(controller.handleSnapshotRequest(720, 1280, "Camera", ResourceRequestReason.PERIODIC)) + .resolves.toEqual(Buffer.from([0xff, 0xd8, 0xff, 0xd9])); + expect(snapshot).toHaveBeenCalledWith({ height: 720, width: 1280, reason: ResourceRequestReason.PERIODIC }); + + controller.globalOperatingModeService!.setCharacteristic(Characteristic.HomeKitCameraActive, 0); + await expect(controller.handleSnapshotRequest(720, 1280, "Camera")).rejects.toBe(HAPStatus.NOT_ALLOWED_IN_CURRENT_STATE); + controller.globalOperatingModeService!.setCharacteristic(Characteristic.HomeKitCameraActive, 1); + + controller.recordingManagement!.operatingModeService.setCharacteristic(Characteristic.PeriodicSnapshotsActive, false); + await expect(controller.handleSnapshotRequest(720, 1280, "Camera", ResourceRequestReason.PERIODIC)) + .rejects.toBe(HAPStatus.NOT_ALLOWED_IN_CURRENT_STATE); + await expect(controller.handleSnapshotRequest(720, 1280, "Camera", ResourceRequestReason.EVENT)).resolves.toBeDefined(); + + snapshot.mockRejectedValueOnce(new Error("camera offline")); + await expect(controller.handleSnapshotRequest(720, 1280, "Camera", ResourceRequestReason.EVENT)) + .rejects.toBe(HAPStatus.SERVICE_COMMUNICATION_FAILURE); + }); + test("hds only without an ingest delegate", () => { const hds = new Accessory("HDS", uuid.generate("hds")); const secureVideo = new SecureVideoController({ diff --git a/src/lib/controller/SecureVideoController.ts b/src/lib/controller/SecureVideoController.ts index 048e8cd0d..8fecee23d 100644 --- a/src/lib/controller/SecureVideoController.ts +++ b/src/lib/controller/SecureVideoController.ts @@ -86,7 +86,8 @@ import { HAPStatus } from "../HAPServer"; import { Service } from "../Service"; import { HapStatusError } from "../util/hapStatusError"; import * as uuid from "../util/uuid"; -import { ControllerIdentifier, ControllerServiceMap, SerializableController, StateChangeDelegate } from "./Controller"; +import { ResourceRequestReason } from "./CameraController"; +import { ControllerIdentifier, ControllerServiceMap, SerializableController, SnapshotController, StateChangeDelegate } from "./Controller"; import type { CharacteristicValue } from "../../types"; import type { CharacteristicChange } from "../Characteristic"; @@ -100,6 +101,8 @@ const debug = createDebug("HAP-NodeJS:SecureVideo:Controller"); const MAX_QUEUED_EVENTS = 256; const DEFAULT_MAX_WEBRTC_SESSIONS = 6; +// same budget as the image resource request of the CameraController (8s slow warning + 17s abort) +const SNAPSHOT_TIMEOUT_MS = 25000; function setupEndpointsError(sessionIdentifier: string): RTPSetupEndpointsResponse { const emptySRTP: RTPSRTPParameters = { cryptoSuite: 0, masterKey: Buffer.alloc(0), masterSalt: Buffer.alloc(0) }; @@ -309,8 +312,8 @@ export interface SecureVideoControllerOptions { /** reuse an existing motion sensor instead of creating one */ motionService?: Service; /** - * produces a JPEG snapshot for the HDS `ipcamera.snapshot` relay iOS 27 uses for the secure video services. Without - * it no snapshot responder is installed; the legacy image resource request of a {@link CameraController} is not used. + * Produces the JPEG snapshots of the camera. They are requested through the HAP image resource request (the + * camera tile in the Home app) and, on iOS 27, over the HDS `ipcamera.snapshot` relay. Without it both are rejected. */ snapshot?: SecureVideoSnapshotHandler; } @@ -407,7 +410,8 @@ type TLVWriteHandler = (value: Buffer, connection?: HAPConnection) => Promise { +export class SecureVideoController extends EventEmitter + implements SerializableController, SnapshotController { public static readonly CONTROLLER_ID = "secure-video"; public capabilitiesService?: CameraCapabilities; @@ -771,6 +775,55 @@ export class SecureVideoController extends EventEmitter implements SerializableC }); } + /** + * @private + */ + handleSnapshotRequest(height: number, width: number, accessoryName?: string, reason?: ResourceRequestReason): Promise { + const snapshot = this.options.snapshot; + if (!snapshot) { + return Promise.reject(HAPStatus.RESOURCE_DOES_NOT_EXIST); + } + + const operatingMode = this.recordingManagement?.operatingModeService; + if (!this.homeKitCameraActive || !operatingMode?.getCharacteristic(Characteristic.HomeKitCameraActive).value) { + debug("[%s] rejecting snapshot as the HomeKit camera is disabled", accessoryName); + return Promise.reject(HAPStatus.NOT_ALLOWED_IN_CURRENT_STATE); + } + if (!operatingMode.getCharacteristic(Characteristic.EventSnapshotsActive).value) { + if (reason == null) { + return Promise.reject(HAPStatus.INSUFFICIENT_PRIVILEGES); + } else if (reason === ResourceRequestReason.EVENT) { + debug("[%s] rejecting snapshot as event snapshots are disabled", accessoryName); + return Promise.reject(HAPStatus.NOT_ALLOWED_IN_CURRENT_STATE); + } + } + if (!operatingMode.getCharacteristic(Characteristic.PeriodicSnapshotsActive).value) { + if (reason == null) { + return Promise.reject(HAPStatus.INSUFFICIENT_PRIVILEGES); + } else if (reason === ResourceRequestReason.PERIODIC) { + debug("[%s] rejecting snapshot as periodic snapshots are disabled", accessoryName); + return Promise.reject(HAPStatus.NOT_ALLOWED_IN_CURRENT_STATE); + } + } + + return new Promise((resolve, reject) => { + const timeout = setTimeout(() => { + debug("[%s] the snapshot handler did not respond within %dms", accessoryName, SNAPSHOT_TIMEOUT_MS); + reject(HAPStatus.OPERATION_TIMED_OUT); + }, SNAPSHOT_TIMEOUT_MS); + timeout.unref(); + + snapshot({ height, width, reason }).then(buffer => { + clearTimeout(timeout); + resolve(buffer); + }, error => { + clearTimeout(timeout); + debug("[%s] error getting snapshot: %s", accessoryName, error instanceof Error ? error.message : error); + reject(HAPStatus.SERVICE_COMMUNICATION_FAILURE); + }); + }); + } + public handleControllerRemoved(): void { this.handleFactoryReset(); this.snapshotTransport?.destroy(); From d81fba565ee26e82170d5f4f8cd358c2fd773f6c Mon Sep 17 00:00:00 2001 From: seydx Date: Tue, 15 Sep 2026 02:50:04 +0200 Subject: [PATCH 3/4] add microphone and speaker services to the secure video controller --- .../controller/SecureVideoController.spec.ts | 15 +++++++++- src/lib/controller/SecureVideoController.ts | 29 +++++++++++++++++++ 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/src/lib/controller/SecureVideoController.spec.ts b/src/lib/controller/SecureVideoController.spec.ts index 3745c99b3..e6b71917b 100644 --- a/src/lib/controller/SecureVideoController.spec.ts +++ b/src/lib/controller/SecureVideoController.spec.ts @@ -10,6 +10,8 @@ import { H264Level, H264Profile, MediaContainerType, + StreamTierAudioBitDepth, + StreamTierAudioSampleRate, StreamTierVideoCodec, VideoCodecType, WebRTCSolicitOfferStatus, @@ -92,6 +94,17 @@ describe("SecureVideoController", () => { { identifier: 3, quality: CameraVideoQuality.LOW, targetAverageBitrate: 180, peakBitrate: 190, width: 640, height: 360, frameRate: 15 }, ], }, + audio: { + tier: { + identifier: 1, + targetAverageBitrate: 24000, + sampleRate: StreamTierAudioSampleRate.KHZ_16, + bitDepth: StreamTierAudioBitDepth.BITS_16, + packetTime: 20, + channels: 1, + }, + twoWayAudio: true, + }, webrtc: { delegate: webrtc, maxSessions: 1 }, rtp: { delegate: rtp }, recording: { options: recordingOptions, delegate: recordingDelegate }, @@ -116,7 +129,7 @@ describe("SecureVideoController", () => { Service.CameraCapabilities, Service.CameraGlobalOperatingMode, Service.CameraMotionZones, Service.CameraBufferManagement, Service.CameraMultiTierRTPStreamManagement, Service.CameraWebRTCStreamManagement, Service.CameraRecordingManagement, Service.CameraOperatingMode, Service.DataStreamTransportManagement, Service.CameraKeyManagement, - Service.CameraClientCertificateManagement, Service.MotionSensor, + Service.CameraClientCertificateManagement, Service.MotionSensor, Service.Microphone, Service.Speaker, ]) { expect(accessory.getService(service)).toBeDefined(); } diff --git a/src/lib/controller/SecureVideoController.ts b/src/lib/controller/SecureVideoController.ts index 8fecee23d..b313b12bc 100644 --- a/src/lib/controller/SecureVideoController.ts +++ b/src/lib/controller/SecureVideoController.ts @@ -80,7 +80,9 @@ import { CameraRecordingManagement, CameraWebRTCStreamManagement, DataStreamTransportManagement, + Microphone, MotionSensor, + Speaker, } from "../definitions"; import { HAPStatus } from "../HAPServer"; import { Service } from "../Service"; @@ -282,6 +284,8 @@ export interface SecureVideoControllerOptions { audio?: { payloadType?: number; tier: AudioStreamTier; + /** adds the Speaker service so the Home app offers talkback, like `twoWayAudio` of the {@link CameraStreamingOptions} */ + twoWayAudio?: boolean; }; webrtc: { delegate: WebRTCStreamingDelegate; @@ -349,6 +353,8 @@ export interface SecureVideoControllerServiceMap extends ControllerServiceMap { keyManagement?: CameraKeyManagement; clientCertificateManagement?: CameraClientCertificateManagement; motionSensor?: MotionSensor; + microphone?: Microphone; + speaker?: Speaker; } /** @@ -424,6 +430,8 @@ export class SecureVideoController extends EventEmitter public keyManagementService?: CameraKeyManagement; public clientCertificateManagementService?: CameraClientCertificateManagement; public motionService?: Service; + public microphoneService?: Microphone; + public speakerService?: Speaker; private readonly options: SecureVideoControllerOptions; private stateChangeDelegate?: StateChangeDelegate; @@ -982,6 +990,27 @@ export class SecureVideoController extends EventEmitter } } + if (this.options.audio) { + this.microphoneService = ensure("microphone", () => { + const service = new Service.Microphone("", ""); + service.setCharacteristic(Characteristic.Volume, 100); + return service; + }); + } else if (serviceMap.microphone) { + delete serviceMap.microphone; + updated = true; + } + if (this.options.audio?.twoWayAudio) { + this.speakerService = ensure("speaker", () => { + const service = new Service.Speaker("", ""); + service.setCharacteristic(Characteristic.Volume, 100); + return service; + }); + } else if (serviceMap.speaker) { + delete serviceMap.speaker; + updated = true; + } + if (this.options.motionService) { this.motionService = this.options.motionService; this.motionServiceExternallySupplied = true; From 16bd882a839b8e4f22c1d3e214d654b508bd1e30 Mon Sep 17 00:00:00 2001 From: seydx Date: Fri, 16 Oct 2026 04:01:05 +0200 Subject: [PATCH 4/4] refactor cmaf --- src/lib/camera/CMAFIngest.spec.ts | 365 ++++++++--- src/lib/camera/CMAFIngest.ts | 575 ++++++++++++------ src/lib/camera/CMAFTracks.spec.ts | 148 +++++ src/lib/camera/CMAFTracks.ts | 504 +++++++++++++++ src/lib/camera/index.ts | 1 + .../controller/SecureVideoController.spec.ts | 16 +- src/lib/controller/SecureVideoController.ts | 76 ++- src/test-utils/fmp4.ts | 140 +++++ 8 files changed, 1511 insertions(+), 314 deletions(-) create mode 100644 src/lib/camera/CMAFTracks.spec.ts create mode 100644 src/lib/camera/CMAFTracks.ts create mode 100644 src/test-utils/fmp4.ts diff --git a/src/lib/camera/CMAFIngest.spec.ts b/src/lib/camera/CMAFIngest.spec.ts index e36978867..e7dce22c2 100644 --- a/src/lib/camera/CMAFIngest.spec.ts +++ b/src/lib/camera/CMAFIngest.spec.ts @@ -1,101 +1,298 @@ -import crypto from "crypto"; -import { - buildMediaPlaylist, - buildMultivariantPlaylist, - deriveClipKey, - mapStatus, - ntpToDate, - sealSegment, - sealSessionValue, -} from "./CMAFIngest"; -import { CMAFError } from "./SecureVideoTypes"; - -const cameraKey = crypto.randomBytes(32); -const key = deriveClipKey(0x1234n, cameraKey); - -function open(sealed: Buffer): Buffer { - const iv = sealed.subarray(0, 16); - const tag = sealed.subarray(sealed.length - 16); - const decipher = crypto.createDecipheriv("aes-256-gcm", key.contentKey, iv, { authTagLength: 16 }); - decipher.setAuthTag(tag); - return Buffer.concat([decipher.update(sealed.subarray(16, sealed.length - 16)), decipher.final()]); +import { EventEmitter } from "events"; +import http2 from "http2"; + +import { initSegment, mediaSegment } from "../../test-utils/fmp4"; +import { buildMediaPlaylist, buildMultivariantPlaylist, CMAFIngest, formatDuration, formatUserAgent, mapStatus } from "./CMAFIngest"; +import { splitInitSegment, splitMediaSegment } from "./CMAFTracks"; +import { BufferUploadCommandType, BufferUploadStopAction, CMAFError } from "./SecureVideoTypes"; + +import type { CMAFIngestContext } from "./CMAFIngest"; +import type { CMAFTrackSegment } from "./CMAFTracks"; +import type { CMAFRecordingDelegate, CMAFSegment, SecureVideoIngestCredentials } from "../controller/SecureVideoController"; + +const VIDEO = { id: 1, handler: "vide" as const, timescale: 90000 }; +const AUDIO = { id: 2, handler: "soun" as const, timescale: 32000, defaultSampleDuration: 1024 }; +const BASE = "/v1/token/"; + +interface Request { + path: string; + contentType: string; + userAgent?: string; + extinf?: string; + body: string; +} + +function fragment(seconds: number, nonSyncStart = false): Buffer { + return mediaSegment(1, [ + { trackId: 1, durations: [seconds * 45000, seconds * 45000], samples: [Buffer.alloc(100, 1), Buffer.alloc(100, 1)], nonSyncStart }, + { trackId: 2, durations: [1024], samples: [Buffer.alloc(20, 2)] }, + ]); +} + +function fakeClient(requests: Request[], status: (path: string, attempt: number) => number, attempts: Map) { + return { + on: jest.fn(), + closed: false, + destroyed: false, + close: jest.fn(), + request: (headers: http2.OutgoingHttpHeaders) => { + const stream = new EventEmitter() as EventEmitter & { end(body: Buffer): void }; + stream.end = body => { + const path = String(headers[":path"]).slice(BASE.length); + const attempt = attempts.get(path) ?? 0; + attempts.set(path, attempt + 1); + requests.push({ + path, + contentType: String(headers["content-type"]), + userAgent: headers["user-agent"] as string | undefined, + extinf: headers["x-extinf-duration"] as string | undefined, + body: body.toString("latin1"), + }); + setImmediate(() => { + stream.emit("response", { ":status": status(path, attempt), "x-apple-request-uuid": "4f1c" }); + stream.emit("end"); + }); + }; + return stream; + }, + } as unknown as http2.ClientHttp2Session; } +function setup(segments: CMAFSegment[], status: (path: string, attempt: number) => number = () => 201) { + const requests: Request[] = []; + const events: string[] = []; + const errors: string[] = []; + const attempts = new Map(); + let sessionNumber = 0n; + const connect = jest.spyOn(http2, "connect").mockImplementation(() => fakeClient(requests, status, attempts)); + + let resolveDone!: () => void; + const done = new Promise(resolve => { + resolveDone = resolve; + }); + const delegate: CMAFRecordingDelegate = { + async *streamClip() { + try { + yield* segments; + } finally { + // the generator is closed in the upload's cleanup, after the last request; give the event loop a few turns + setTimeout(resolveDone, 20); + } + }, + }; + const context: CMAFIngestContext = { + userAgent: () => "test-agent/1.0", + credentials: () => ({ + publishingPoint: { url: `https://ingest.example.com${BASE}`, serverCACertificates: [] }, + privateKey: "key", + clientCertificate: Buffer.from("cert"), + keys: [], + }) as unknown as SecureVideoIngestCredentials, + nextSessionNumber: () => ++sessionNumber, + reportSessionStart: number => events.push(`start ${number}`), + reportSessionStop: number => events.push(`stop ${number}`), + reportError: (number, error, detail) => { + events.push(`error ${number} ${error}`); + errors.push(detail ?? ""); + }, + }; + + const ingest = new CMAFIngest(delegate, context); + const clipId = ingest.handleUploadCommand({ sessionId: 99n, command: BufferUploadCommandType.START_AND_STOP }); + return { requests, events, errors, clipId, done, connects: () => connect.mock.calls.length }; +} + +const videoSegments = (requests: Request[], session: number) => + requests.filter(request => request.path.startsWith(`session_${session}/high/segment_`)).length; + +afterEach(() => { + jest.restoreAllMocks(); +}); + describe("CMAFIngest", () => { - test("derives the clip key id and content key from the camera key", () => { - // key number in the upper bits, key type CMAF (1) at bit 14 - expect(key.keyIdString).toBe("0000000012344000"); - expect(key.contentKey).toHaveLength(32); - expect(key.contentKey).toEqual(Buffer.from(crypto.hkdfSync("sha256", cameraKey, Buffer.alloc(0), "HomeKit 1.0 CMAF Content", 32))); - expect(deriveClipKey(0x1234n, cameraKey).contentKey).toEqual(key.contentKey); + test("builds the multivariant playlist in the form of the iCloud ingest sample", () => { + const tracks = splitInitSegment(initSegment([VIDEO, AUDIO])); + const segments = [splitMediaSegment(fragment(4), tracks), splitMediaSegment(fragment(2), tracks)]; + const rate = (part: CMAFTrackSegment) => part.data.length * 8 / part.duration; + const average = (parts: CMAFTrackSegment[]) => + parts.reduce((sum, part) => sum + part.data.length, 0) * 8 / parts.reduce((sum, part) => sum + part.duration, 0); + const [video, audio] = [0, 1].map(index => segments.map(parts => parts[index])); + const peak = Math.ceil(Math.max(...video.map(rate)) + Math.max(...audio.map(rate))); + const mean = Math.ceil(average(video) + average(audio)); + + expect(buildMultivariantPlaylist(tracks, segments).split("\n")).toEqual([ + "#EXTM3U", + "#EXT-X-VERSION:11", + "#EXT-X-INDEPENDENT-SEGMENTS", + "", + "#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID=\"aud\",NAME=\"Camera Audio\",DEFAULT=YES,CHANNELS=\"1\",URI=\"audio1/index.m3u8\"", + "", + `#EXT-X-STREAM-INF:BANDWIDTH=${peak},AVERAGE-BANDWIDTH=${mean},RESOLUTION=1920x1080,CODECS="hvc1.1.6.L93.B0,mp4a.40.2",AUDIO="aud"`, + "high/index.m3u8", + "", + ]); }); - test("seals segments as iv, ciphertext, tag", () => { - const plaintext = crypto.randomBytes(1000); - const sealed = sealSegment(key, plaintext); - expect(sealed).toHaveLength(plaintext.length + 32); - expect(open(sealed)).toEqual(plaintext); - expect(sealSegment(key, plaintext)).not.toEqual(sealed); + test("lists one variant per video track, highest first", () => { + const tracks = splitInitSegment(initSegment([{ ...VIDEO, id: 3, width: 640, height: 360 }, VIDEO])); + const lines = buildMultivariantPlaylist(tracks, []).split("\n"); + + expect(lines.filter(line => !line.startsWith("#") && line)).toEqual(["high/index.m3u8", "mid/index.m3u8"]); + expect(lines.some(line => line.startsWith("#EXT-X-MEDIA") || line.includes("AUDIO="))).toBe(false); }); - test("seals session data values as base64 json", () => { - const value = JSON.parse(Buffer.from(sealSessionValue(key, "2026-09-15T00:00:00Z"), "base64").toString("utf8")); - expect(value.method).toBe("AES-256-GCM"); - expect(value.keyIDString).toBe(key.keyIdString); - const sealed = Buffer.concat([ - Buffer.from(value.initializationVector, "base64"), - Buffer.from(value.ciphertext, "base64"), - Buffer.from(value.tag, "base64"), - ]); - expect(open(sealed).toString("utf8")).toBe("2026-09-15T00:00:00Z"); + test("formats the user agent of the iCloud ingest", () => { + expect(formatUserAgent({ software: "camera.ui-homekit", vendor: "Acme", model: "Cam (2); 4K", firmwareVersion: "v1:2" })) + .toBe("HKSV/3.0 camera.ui-homekit (Acme; Cam 2 4K; v1 2)"); + expect(formatUserAgent({ software: "Home Helper 1.0", vendor: "", model: "G234", firmwareVersion: "4.56.21" })) + .toBe("HKSV/3.0 Home-Helper-1.0 (unknown; G234; 4.56.21)"); }); - test("builds the multivariant playlist", () => { - const sensor = "6d3b7b46-8a7d-4a8f-9c5a-1f7e0f0c0b1a"; - const playlist = buildMultivariantPlaylist(key, new Date("2026-09-15T00:00:00.000Z"), sensor, { - codecs: "hvc1.1.6.L120.B0", - width: 1920, - height: 1080, - bitrate: 1700000, - }); - const lines = playlist.split("\n"); - expect(lines[0]).toBe("#EXTM3U"); - expect(lines).toContain(`#EXT-X-SESSION-KEY:METHOD=AES-256-GCM,URI="${key.keyIdString}"`); - expect(lines).toContain(`#EXT-X-SESSION-DATA:DATA-ID="com.apple.homekit.sensor-id",VALUE="${sensor}"`); - expect(lines).toContain("#EXT-X-STREAM-INF:BANDWIDTH=1700000,CODECS=\"hvc1.1.6.L120.B0\",RESOLUTION=1920x1080"); - expect(lines[lines.indexOf("#EXT-X-STREAM-INF:BANDWIDTH=1700000,CODECS=\"hvc1.1.6.L120.B0\",RESOLUTION=1920x1080") + 1]).toBe("video/index.m3u8"); - - const timestamp = lines.find(line => line.includes("com.apple.encrypted-datetime.timestamp"))!; - const value = JSON.parse(Buffer.from(/VALUE="([^"]+)"/.exec(timestamp)![1], "base64").toString("utf8")); - const sealed = Buffer.concat([ - Buffer.from(value.initializationVector, "base64"), - Buffer.from(value.ciphertext, "base64"), - Buffer.from(value.tag, "base64"), + test("builds the initial and the final media playlist", () => { + const [video] = splitInitSegment(initSegment([VIDEO])); + + expect(buildMediaPlaylist(video, 5).split("\n")).toEqual([ + "#EXTM3U", + "#EXT-X-VERSION:11", + "#EXT-X-TARGETDURATION:5", + "#EXT-X-PLAYLIST-TYPE:EVENT", + "#EXT-X-INDEPENDENT-SEGMENTS", + "#EXT-X-MAP:URI=\"high.init\"", + "", ]); - expect(open(sealed).toString("utf8")).toBe("2026-09-15T00:00:00Z"); - }); - test("builds the media playlist from the segment durations", () => { - const initial = buildMediaPlaylist(key, [], false).split("\n"); - expect(initial).toContain("#EXT-X-TARGETDURATION:2"); - expect(initial).toContain("#EXT-X-MEDIA-SEQUENCE:1001"); - expect(initial).toContain("#EXT-X-MAP:URI=\"video.init\""); - expect(initial).toContain(`#EXT-X-KEY:METHOD=AES-256-GCM,URI="${key.keyIdString}"`); - expect(initial.some(line => line.startsWith("#EXTINF"))).toBe(false); - expect(initial).not.toContain("#EXT-X-ENDLIST"); - - const ended = buildMediaPlaylist(key, [4, 4.5], true).split("\n"); - expect(ended).toContain("#EXT-X-TARGETDURATION:5"); - expect(ended.slice(ended.indexOf("#EXTINF:4.000,"))).toEqual([ - "#EXTINF:4.000,", + const final = buildMediaPlaylist(video, 5, [4, 6.4]).split("\n"); + expect(final).toContain("#EXT-X-TARGETDURATION:6"); + expect(final.slice(final.indexOf("#EXTINF:4.00000,"))).toEqual([ + "#EXTINF:4.00000,", "segment_1001.m4s", - "#EXTINF:4.500,", + "#EXTINF:6.40000,", "segment_1002.m4s", "#EXT-X-ENDLIST", "", ]); }); + test("formats durations with five decimals", () => { + expect(formatDuration(4)).toBe("4.00000"); + expect(formatDuration(4.123456)).toBe("4.12346"); + }); + + test("uploads a clip in the order of the Matter HLS ingest", async () => { + const { requests, events, clipId, done } = setup([ + { type: "init", data: initSegment([VIDEO, AUDIO]) }, + { type: "media", data: fragment(4) }, + { type: "media", data: fragment(4), last: true }, + ]); + await done; + + expect(requests.map(({ path, contentType, extinf }) => `${path} ${contentType}${extinf ? ` ${extinf}` : ""}`)).toEqual([ + "session_1/index.m3u8 application/vnd.apple.mpegurl", + "session_1/high/index.m3u8 application/vnd.apple.mpegurl", + "session_1/audio1/index.m3u8 application/vnd.apple.mpegurl", + "session_1/high/high.init video/mp4", + "session_1/audio1/audio1.init video/mp4", + "session_1/high/segment_1001.m4s video/iso.segment 4.00000", + "session_1/audio1/segment_1001.m4s video/iso.segment 0.03200", + "session_1/high/segment_1002.m4s video/iso.segment 4.00000", + "session_1/audio1/segment_1002.m4s video/iso.segment 0.03200", + "session_1/high/index.m3u8 application/vnd.apple.mpegurl", + "session_1/audio1/index.m3u8 application/vnd.apple.mpegurl", + ]); + expect(requests.every(request => request.userAgent === "test-agent/1.0")).toBe(true); + expect(requests[1].body).not.toContain("#EXT-X-ENDLIST"); + expect(requests[9].body).toContain("segment_1002.m4s\n#EXT-X-ENDLIST"); + expect(events).toEqual(["start 1", "stop 1"]); + // the hub links the upload to its clip through the first CMAF session number + expect(clipId).toBe(1n); + }); + + test("continues a recording longer than five minutes in the next session", async () => { + const { requests, events, done } = setup([ + { type: "init", data: initSegment([VIDEO, AUDIO]) }, + { type: "media", data: fragment(100) }, + { type: "media", data: fragment(100) }, + { type: "media", data: fragment(90) }, + { type: "media", data: fragment(100) }, + { type: "media", data: fragment(100), last: true }, + ]); + await done; + + expect(videoSegments(requests, 1)).toBe(3); + expect(videoSegments(requests, 2)).toBe(2); + const paths = requests.map(request => request.path); + expect(paths.indexOf("session_2/index.m3u8")).toBeGreaterThan(paths.lastIndexOf("session_1/audio1/index.m3u8")); + expect(events).toEqual(["start 1", "stop 1", "start 2", "stop 2"]); + }); + + test("never leaves a session with a single segment", async () => { + const { requests, done } = setup([ + { type: "init", data: initSegment([VIDEO, AUDIO]) }, + { type: "media", data: fragment(100) }, + { type: "media", data: fragment(100) }, + { type: "media", data: fragment(50) }, + { type: "media", data: fragment(100), last: true }, + ]); + await done; + + // 100 + 100 + 50 fit, but the last 100 would then form a session of its own + expect(videoSegments(requests, 1)).toBe(2); + expect(videoSegments(requests, 2)).toBe(2); + }); + + test("lets a fragment without a sync sample continue the segment before it", async () => { + const { requests, done } = setup([ + { type: "init", data: initSegment([VIDEO, AUDIO]) }, + { type: "media", data: fragment(2) }, + { type: "media", data: fragment(0.5, true) }, + { type: "media", data: fragment(2), last: true }, + ]); + await done; + + const video = requests.filter(request => request.path.startsWith("session_1/high/segment_")); + expect(video.map(request => `${request.path.split("/").pop()} ${request.extinf}`)).toEqual(["segment_1001.m4s 2.50000", "segment_1002.m4s 2.00000"]); + expect(video[0].body.split("moof").length - 1).toBe(2); + }); + + test("sends a request again on a new connection after a server error", async () => { + const { requests, events, connects, done } = setup([ + { type: "init", data: initSegment([VIDEO, AUDIO]) }, + { type: "media", data: fragment(4), last: true }, + ], (path, attempt) => (path === "session_1/index.m3u8" && attempt === 0 ? 503 : 201)); + await done; + + expect(requests.filter(request => request.path === "session_1/index.m3u8")).toHaveLength(2); + expect(connects()).toBe(2); + expect(events).toEqual(["start 1", "stop 1"]); + }); + + test("reports the first refusal once and closes the opened tracks", async () => { + const { requests, events, errors, done } = setup([ + { type: "init", data: initSegment([VIDEO, AUDIO]) }, + { type: "media", data: fragment(4) }, + { type: "media", data: fragment(4), last: true }, + ], path => (path.endsWith("segment_1001.m4s") ? 400 : 201)); + await done; + + expect(events).toEqual(["start 1", `error 1 ${CMAFError.HTTP_BAD_REQUEST}`]); + expect(errors[0]).toMatch(/^PUT session_1\/(high|audio1)\/segment_1001\.m4s \(\d+ bytes\) -> 400 x-apple-request-uuid=4f1c$/); + // a 4xx is not sent again + expect(requests.filter(request => request.path === "session_1/high/segment_1001.m4s")).toHaveLength(1); + // the server saw the session begin, so its tracks are closed even though the upload failed + expect(requests.slice(-2).map(request => request.path)).toEqual(["session_1/high/index.m3u8", "session_1/audio1/index.m3u8"]); + expect(requests.at(-1)!.body).toContain("#EXT-X-ENDLIST"); + }); + + test("passes the stop command to the delegate", () => { + const handleUploadStop = jest.fn(); + const delegate = { streamClip: jest.fn(), handleUploadStop } as unknown as CMAFRecordingDelegate; + const ingest = new CMAFIngest(delegate, {} as CMAFIngestContext); + const stop = { sessionId: 7n, command: BufferUploadCommandType.STOP, stop: 123n, stopAction: BufferUploadStopAction.FINALIZE }; + + expect(ingest.handleUploadCommand(stop)).toBe(0n); + expect(handleUploadStop).toHaveBeenCalledWith(stop); + }); + test("maps http statuses to cmaf errors", () => { expect(mapStatus(400)).toBe(CMAFError.HTTP_BAD_REQUEST); expect(mapStatus(401)).toBe(CMAFError.HTTP_INVALID_TOKEN); @@ -107,12 +304,4 @@ describe("CMAFIngest", () => { expect(mapStatus(500)).toBe(CMAFError.HTTP_INTERNAL_SERVER_ERROR); expect(mapStatus(418)).toBe(CMAFError.UNKNOWN); }); - - test("converts ntp timestamps", () => { - const unixSeconds = Math.floor(Date.UTC(2026, 8, 14, 14, 54, 44) / 1000); - const ntp = (BigInt(unixSeconds) + 2_208_988_800n) << 32n; - expect(ntpToDate(ntp).toISOString()).toBe("2026-09-14T14:54:44.000Z"); - expect(Math.abs(ntpToDate(undefined).getTime() - Date.now())).toBeLessThan(1000); - expect(Math.abs(ntpToDate(5n).getTime() - Date.now())).toBeLessThan(1000); - }); }); diff --git a/src/lib/camera/CMAFIngest.ts b/src/lib/camera/CMAFIngest.ts index cdc1c8f55..7582ec018 100644 --- a/src/lib/camera/CMAFIngest.ts +++ b/src/lib/camera/CMAFIngest.ts @@ -1,223 +1,289 @@ -import crypto from "crypto"; import createDebug from "debug"; import http2 from "http2"; +import { splitInitSegment, splitMediaSegment } from "./CMAFTracks"; import { BufferUploadCommandType, CMAFError } from "./SecureVideoTypes"; +import type { CMAFTrack, CMAFTrackSegment } from "./CMAFTracks"; import type { BufferUploadCommandRequest } from "./SecureVideoTypes"; -import type { CMAFRecordingDelegate, SecureVideoIngestCredentials } from "../controller/SecureVideoController"; +import type { CMAFRecordingDelegate, CMAFSegment, SecureVideoIngestCredentials, SecureVideoUserAgent } from "../controller/SecureVideoController"; const debug = createDebug("HAP-NodeJS:SecureVideo:Ingest"); -const TRACK_NAME = "video"; const FIRST_SEGMENT_NUMBER = 1001; -const SEGMENT_DURATION_SECONDS = 2; +const DEFAULT_SEGMENT_DURATION_SECONDS = 2; +// Matter 1.6.1 Push AV Stream Transport 11.7.1.6: a session lasts at most five minutes and at least two segments +const MAX_SESSION_SECONDS = 300; +// DASH-IF ingest 5.3: a failed transfer is sent again on a new connection +const MAX_RETRIES = 2; +const RETRY_DELAY_MS = 500; const PLAYLIST_CONTENT_TYPE = "application/vnd.apple.mpegurl"; - -// the HomeKit HomeHub derives the clip content key from the camera key with HKDF-SHA256, empty salt, and -// expects every segment as AES-256-GCM with a 16-byte IV in front and the tag behind -const CONTENT_KEY_INFO = "HomeKit 1.0 CMAF Content"; -const CONTENT_KEY_LENGTH = 32; -const KEY_TYPE_CMAF = 1n; -const IV_LENGTH = 16; -const TAG_LENGTH = 16; -const NTP_EPOCH_OFFSET_SECONDS = 2_208_988_800; - -/** - * Media description the controller advertises in the HLS multivariant playlist. - * - * @group Camera Secure Video - */ -export interface CMAFMediaDescription { - /** HLS codecs attribute, e.g. `hvc1.1.6.L120.B0` */ - codecs: string; - width: number; - height: number; - /** bits per second */ - bitrate: number; -} +const INIT_CONTENT_TYPE = "video/mp4"; +const SEGMENT_CONTENT_TYPE = "video/iso.segment"; +// the playlist form of the iCloud ingest sample +const HLS_VERSION = 11; +const AUDIO_GROUP = "aud"; +const AUDIO_NAME = "Camera Audio"; +const USER_AGENT_PRODUCT = "HKSV/3.0"; /** - * Everything the ingest needs from the controller: the negotiated credentials, the advertised media description and - * the event reporters. Keeps the credential and event handling internal to the controller. + * Everything the ingest needs from the controller: the negotiated credentials, the persisted session number and the + * event reporters. Keeps the credential and event handling internal to the controller. * * @group Camera Secure Video */ export interface CMAFIngestContext { - sensorUUID: string; - media: CMAFMediaDescription; + /** the User-Agent of the next upload, see {@link formatUserAgent} */ + userAgent(): string; credentials(): SecureVideoIngestCredentials; + /** the number of the next CMAF session: starts at 1 for a new publishing point, persisted, never reused */ + nextSessionNumber(): bigint; reportSessionStart(cmafSessionId: bigint): void; - /** `detail` summarizes the optional playlist requests, for logging only */ - reportSessionStop(cmafSessionId: bigint, detail?: string): void; + reportSessionStop(cmafSessionId: bigint): void; /** `detail` names the failed request or the transport error, for logging only */ reportError(cmafSessionId: bigint, error: CMAFError, detail?: string): void; } -/** - * Content key of one clip, derived from the camera key the HomeKit HomeHub provisioned. - * - * @group Camera Secure Video - */ -export interface ClipKey { - /** key id as it appears in the HLS key URIs */ - keyIdString: string; - contentKey: Buffer; -} - interface UploadSession { + /** number of the first CMAF session of the clip, the hub learns it from the upload command response */ clipId: bigint; - startedAt: Date; abort: AbortController; /** no further hub command is expected, the session is dropped once the upload ends */ finalize: boolean; - /** the hub sent stop, the upload ends with the next fragment */ + /** the hub sent stop, the upload ends with the fragments already received */ stopRequested: boolean; finished: boolean; } +interface CMAFSession { + number: bigint; + /** publishing point path plus `session_/` */ + prefix: string; + startedAt: number; + seconds: number; + /** uploaded segment durations per track id */ + durations: Map; + /** tracks whose initial media playlist was accepted; only those get a final playlist */ + opened: Set; + failed: boolean; + ended: boolean; +} + +interface PreparedSegment { + parts: CMAFTrackSegment[]; + /** seconds, the longest track */ + duration: number; +} + interface PutResult { status: number; /** first bytes of the response body, the ingest edge explains rejections there */ body: string; + /** response headers as name=value pairs, they carry the request id Apple asks for */ + headers: string; } -function put(client: http2.ClientHttp2Session, path: string, body: Buffer, contentType: string): Promise { +interface Bitrate { + peak: number; + average: number; +} + +class IngestConnection { + private client?: http2.ClientHttp2Session; + + constructor(private readonly origin: string, private readonly options: http2.SecureClientSessionOptions, readonly userAgent: string) {} + + session(): http2.ClientHttp2Session { + if (!this.client || this.client.closed || this.client.destroyed) { + this.client = http2.connect(this.origin, this.options); + this.client.on("error", error => debug("http2 session error: %s", error.message)); + } + return this.client; + } + + /** closes the current connection once its streams are done, the next request opens a new one */ + renew(): void { + this.client?.close(); + this.client = undefined; + } +} + +function put(client: http2.ClientHttp2Session, path: string, body: Buffer, contentType: string, headers: http2.OutgoingHttpHeaders): Promise { return new Promise((resolve, reject) => { const request = client.request({ ":method": "PUT", ":path": path, "content-type": contentType, "content-length": body.length, + ...headers, }); let status = 0; + let summary = ""; const chunks: Buffer[] = []; - request.on("response", headers => { - status = Number(headers[":status"]); + request.on("response", responseHeaders => { + status = Number(responseHeaders[":status"]); + summary = Object.entries(responseHeaders) + .filter(([name]) => !name.startsWith(":")) + .map(([name, value]) => `${name}=${Array.isArray(value) ? value.join(",") : value}`) + .join(" "); }); request.on("data", (chunk: Buffer) => { chunks.push(chunk); }); request.on("end", () => { const response = Buffer.concat(chunks).toString("utf8").slice(0, 512); - debug("PUT %s (%d bytes) -> %d %s", path.slice(path.indexOf("session_")), body.length, status, response); - resolve({ status, body: response }); + debug("PUT %s (%d bytes) -> %d %s %s", path.slice(path.indexOf("session_")), body.length, status, response, summary); + resolve({ status, body: response, headers: summary }); }); request.on("error", reject); request.end(body); }); } -/** - * Derives the clip content key and key id from a provisioned camera key. - * - * @group Camera Secure Video - */ -export function deriveClipKey(keyNumber: bigint, cameraKey: Buffer): ClipKey { - const keyId = (keyNumber << 16n) | (KEY_TYPE_CMAF << 14n); - return { - keyIdString: keyId.toString(16).padStart(16, "0"), - contentKey: Buffer.from(crypto.hkdfSync("sha256", cameraKey, Buffer.alloc(0), CONTENT_KEY_INFO, CONTENT_KEY_LENGTH)), - }; +// appends the parts of a segment to the one before it, a CMAF segment may hold several fragments +function appendSegment(target: PreparedSegment, source: PreparedSegment): void { + for (const part of source.parts) { + const index = target.parts.findIndex(existing => existing.track === part.track); + if (index < 0) { + target.parts.push(part); + continue; + } + const existing = target.parts[index]; + target.parts[index] = { + ...existing, + data: Buffer.concat([existing.data, part.data]), + duration: existing.duration + part.duration, + samples: existing.samples + part.samples, + }; + } + target.duration = target.parts.reduce((longest, part) => Math.max(longest, part.duration), 0); } -function seal(key: ClipKey, plaintext: Buffer): { iv: Buffer, ciphertext: Buffer, tag: Buffer } { - const iv = crypto.randomBytes(IV_LENGTH); - const cipher = crypto.createCipheriv("aes-256-gcm", key.contentKey, iv, { authTagLength: TAG_LENGTH }); - const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]); - return { iv, ciphertext, tag: cipher.getAuthTag() }; +function sleep(ms: number): Promise { + return new Promise(resolve => setTimeout(resolve, ms)); } /** - * Seals an fMP4 segment for upload: 16-byte IV, AES-256-GCM ciphertext, 16-byte tag. + * Formats a segment duration for the `#EXTINF` tag and the `X-EXTINF-duration` header. * * @group Camera Secure Video */ -export function sealSegment(key: ClipKey, plaintext: Buffer): Buffer { - const { iv, ciphertext, tag } = seal(key, plaintext); - return Buffer.concat([iv, ciphertext, tag]); +export function formatDuration(seconds: number): string { + return seconds.toFixed(5); +} + +function quote(value: string): string { + return `"${value}"`; +} + +// RFC 8216bis 4.4.6.2: BANDWIDTH is the peak segment bit rate, AVERAGE-BANDWIDTH the average one +function bitrate(track: CMAFTrack, segments: CMAFTrackSegment[][]): Bitrate { + let peak = 0; + let bytes = 0; + let seconds = 0; + for (const part of segments.flat()) { + if (part.track !== track || part.duration <= 0) { + continue; + } + peak = Math.max(peak, part.data.length * 8 / part.duration); + bytes += part.data.length; + seconds += part.duration; + } + return { peak, average: seconds > 0 ? bytes * 8 / seconds : 0 }; +} + +// the vendor sub-fields may hold spaces, dashes and underscores, but no colons, semicolons or parentheses +function userAgentField(value: string): string { + return value.replace(/[^\x20-\x7e]|[:;()]/g, " ").replace(/\s+/g, " ").trim() || "unknown"; } /** - * Seals a playlist session data value: JSON with base64 fields, itself base64 inside the VALUE attribute. + * Formats the User-Agent the iCloud ingest requires on every request: + * `HKSV/3.0 (; ; )`. * * @group Camera Secure Video */ -export function sealSessionValue(key: ClipKey, plaintext: string): string { - const { iv, ciphertext, tag } = seal(key, Buffer.from(plaintext, "utf8")); - const value = { - method: "AES-256-GCM", - initializationVector: iv.toString("base64"), - ciphertext: ciphertext.toString("base64"), - tag: tag.toString("base64"), - keyIDString: key.keyIdString, - }; - return Buffer.from(JSON.stringify(value)).toString("base64"); +export function formatUserAgent(agent: SecureVideoUserAgent): string { + const software = agent.software.replace(/[^\w.-]+/g, "-") || "unknown"; + return `${USER_AGENT_PRODUCT} ${software} (${[agent.vendor, agent.model, agent.firmwareVersion].map(userAgentField).join("; ")})`; } /** - * Builds the HLS multivariant playlist of a clip. + * Builds the HLS multivariant playlist of a CMAF session in the form of the iCloud ingest sample: one variant per video + * track, highest first, and the audio tracks as renditions of one group. The bit rates come from the segments at hand + * when the session starts and include the audio of the variant. * * @group Camera Secure Video */ -export function buildMultivariantPlaylist(key: ClipKey, startedAt: Date, sensorUUID: string, media: CMAFMediaDescription): string { - const timestamp = startedAt.toISOString().replace(/\.\d{3}Z$/, "Z"); - const { codecs, width, height, bitrate } = media; - return [ - "#EXTM3U", - "#EXT-X-VERSION:7", - "#EXT-X-INDEPENDENT-SEGMENTS", - `#EXT-X-SESSION-KEY:METHOD=AES-256-GCM,URI="${key.keyIdString}"`, - `#EXT-X-SESSION-DATA:DATA-ID="com.apple.encrypted-datetime.timestamp",VALUE="${sealSessionValue(key, timestamp)}"`, - `#EXT-X-SESSION-DATA:DATA-ID="com.apple.homekit.sensor-id",VALUE="${sensorUUID}"`, - `#EXT-X-STREAM-INF:BANDWIDTH=${bitrate},CODECS="${codecs}",RESOLUTION=${width}x${height}`, - `${TRACK_NAME}/index.m3u8`, - "", - ].join("\n"); +export function buildMultivariantPlaylist(tracks: CMAFTrack[], segments: CMAFTrackSegment[][]): string { + const video = tracks.filter(track => track.kind === "video"); + if (!video.length) { + throw new Error("a CMAF session needs a video track"); + } + const audio = tracks.filter(track => track.kind === "audio"); + const audioBitrates = audio.map(track => bitrate(track, segments)); + const audioPeak = Math.max(0, ...audioBitrates.map(entry => entry.peak)); + const audioAverage = Math.max(0, ...audioBitrates.map(entry => entry.average)); + + const lines = ["#EXTM3U", `#EXT-X-VERSION:${HLS_VERSION}`, "#EXT-X-INDEPENDENT-SEGMENTS", ""]; + if (audio.length) { + audio.forEach((track, index) => { + const attributes = [ + "TYPE=AUDIO", + `GROUP-ID=${quote(AUDIO_GROUP)}`, + `NAME=${quote(index === 0 ? AUDIO_NAME : `${AUDIO_NAME} ${index + 1}`)}`, + `DEFAULT=${index === 0 ? "YES" : "NO"}`, + ...(track.channels ? [`CHANNELS=${quote(String(track.channels))}`] : []), + `URI=${quote(`${track.name}/index.m3u8`)}`, + ]; + lines.push(`#EXT-X-MEDIA:${attributes.join(",")}`); + }); + lines.push(""); + } + + for (const track of video) { + const { peak, average } = bitrate(track, segments); + const codecs = [track.codecs, ...audio.slice(0, 1).map(entry => entry.codecs)]; + const attributes = [ + `BANDWIDTH=${Math.ceil(peak + audioPeak)}`, + `AVERAGE-BANDWIDTH=${Math.ceil(average + audioAverage)}`, + ...(track.width && track.height ? [`RESOLUTION=${track.width}x${track.height}`] : []), + // CODECS lists every codec of the variant, it is left out when one of them is unknown + ...(codecs.every(Boolean) ? [`CODECS=${quote(codecs.join(","))}`] : []), + ...(audio.length ? [`AUDIO=${quote(AUDIO_GROUP)}`] : []), + ]; + lines.push(`#EXT-X-STREAM-INF:${attributes.join(",")}`, `${track.name}/index.m3u8`, ""); + } + return lines.join("\n"); } /** - * Builds the HLS media playlist of a clip from the uploaded segment durations in seconds. + * Builds the HLS media playlist of a track. Without durations it is the initial playlist that opens the track, with + * them the final one that lists every uploaded segment and closes it (Matter 1.6.1 11.7.1.8.2). * * @group Camera Secure Video */ -export function buildMediaPlaylist(key: ClipKey, durations: number[], ended: boolean): string { - const targetDuration = Math.ceil(Math.max(SEGMENT_DURATION_SECONDS, ...durations)); +export function buildMediaPlaylist(track: CMAFTrack, targetDuration: number, durations?: number[]): string { + const target = Math.max(targetDuration, ...(durations ?? []).map(Math.round)); const lines = [ "#EXTM3U", - "#EXT-X-VERSION:7", - `#EXT-X-TARGETDURATION:${targetDuration}`, - `#EXT-X-MEDIA-SEQUENCE:${FIRST_SEGMENT_NUMBER}`, + `#EXT-X-VERSION:${HLS_VERSION}`, + `#EXT-X-TARGETDURATION:${target}`, "#EXT-X-PLAYLIST-TYPE:EVENT", "#EXT-X-INDEPENDENT-SEGMENTS", - `#EXT-X-KEY:METHOD=AES-256-GCM,URI="${key.keyIdString}"`, - `#EXT-X-MAP:URI="${TRACK_NAME}.init"`, + `#EXT-X-MAP:URI=${quote(`${track.name}.init`)}`, ]; - durations.forEach((duration, index) => { - lines.push(`#EXTINF:${duration.toFixed(3)},`, `segment_${FIRST_SEGMENT_NUMBER + index}.m4s`); - }); - if (ended) { + if (durations) { + durations.forEach((duration, index) => { + lines.push(`#EXTINF:${formatDuration(duration)},`, `segment_${FIRST_SEGMENT_NUMBER + index}.m4s`); + }); lines.push("#EXT-X-ENDLIST"); } lines.push(""); return lines.join("\n"); } -/** - * Converts an NTP timestamp of the buffer upload command to a date, falling back to now. - * - * @group Camera Secure Video - */ -export function ntpToDate(ntp: bigint | undefined): Date { - if (ntp === undefined || ntp < 1n << 32n) { - return new Date(); - } - const seconds = Number(ntp >> 32n) - NTP_EPOCH_OFFSET_SECONDS; - const fraction = Number(ntp & 0xffffffffn) / 0x100000000; - return new Date((seconds + fraction) * 1000); -} - function trailingSlash(pathname: string): string { return pathname.endsWith("/") ? pathname : `${pathname}/`; } @@ -253,9 +319,10 @@ export function mapStatus(status: number): CMAFError { } /** - * Uploads HomeKit Secure Video clips to the CMAF publishing point. The media is supplied by a {@link CMAFRecordingDelegate} - * as raw fMP4 segments; this seals them, builds the HLS playlists and PUTs everything over HTTP/2 with the client - * certificate the controller manages. + * Uploads HomeKit Secure Video clips to the CMAF publishing point following DASH-IF ingest interface 2 for HLS with the + * deviations of the Matter 1.6.1 Push AV Stream Transport cluster. The media is supplied by a + * {@link CMAFRecordingDelegate} as muxed fMP4; this splits it into one CMAF track per media type and PUTs the playlists + * and segments over HTTP/2 with the client certificate the controller manages. Segments are uploaded in the clear. * * @group Camera Secure Video */ @@ -268,6 +335,7 @@ export class CMAFIngest { const existing = this.sessions.get(request.sessionId); if (request.command === BufferUploadCommandType.STOP) { + this.delegate.handleUploadStop?.(request); if (existing) { existing.finalize = true; existing.stopRequested = true; @@ -285,8 +353,7 @@ export class CMAFIngest { } const session: UploadSession = { - clipId: crypto.randomBytes(8).readBigUInt64LE(), - startedAt: ntpToDate(request.start), + clipId: this.context.nextSessionNumber(), abort: new AbortController(), finalize: request.command === BufferUploadCommandType.START_AND_STOP, stopRequested: false, @@ -312,107 +379,227 @@ export class CMAFIngest { } private async upload(request: BufferUploadCommandRequest, session: UploadSession): Promise { - const cmafSessionId = request.sessionId; - const credentials = this.context.credentials(); - const { publishingPoint, privateKey, clientCertificate, ca } = credentials; - const cameraKey = credentials.keys.find(entry => entry.keyNumber === credentials.currentKeyNumber) ?? credentials.keys.at(-1); - if (!publishingPoint || !privateKey || !clientCertificate || !cameraKey) { + const { publishingPoint, privateKey, clientCertificate, ca } = this.context.credentials(); + if (!publishingPoint || !privateKey || !clientCertificate) { debug("upload ignored, ingest is not provisioned"); - this.context.reportError(cmafSessionId, CMAFError.INVALID_STATE); + this.context.reportError(session.clipId, CMAFError.INVALID_STATE); return; } - const clipKey = deriveClipKey(cameraKey.keyNumber, cameraKey.key); const url = new URL(publishingPoint.url); - const client = http2.connect(url.origin, { + const base = trailingSlash(url.pathname); + const connection = new IngestConnection(url.origin, { key: privateKey, cert: [toPem(clientCertificate), ...(ca ? [toPem(ca)] : [])].join(""), ca: publishingPoint.serverCACertificates.map(toPem), - }); - client.on("error", error => debug("http2 session error: %s", error.message)); - - // the ingest edge routes exactly session_/index.m3u8, session_//index.m3u8, - // session_//.init and session_//segment_.m4s - const base = trailingSlash(url.pathname) + `session_${cmafSessionId}/`; - const multivariantPath = `${base}index.m3u8`; - const mediaPlaylistPath = `${base}${TRACK_NAME}/index.m3u8`; - const initPath = `${base}${TRACK_NAME}/${TRACK_NAME}.init`; + }, this.context.userAgent()); - this.context.reportSessionStart(cmafSessionId); - debug("session %s starting (clip %s, key %s)", cmafSessionId, session.clipId, cameraKey.keyNumber); - - const clip = this.delegate.streamClip({ cmafSessionId, command: request, signal: session.abort.signal }); - let index = 0; + const clip = this.delegate.streamClip({ command: request, signal: session.abort.signal }); + let tracks: CMAFTrack[] = []; + let targetDuration = 0; + let current: CMAFSession | undefined; try { const first = await clip.next(); if (first.done || first.value.type !== "init") { throw new Error("delegate did not yield an init segment first"); } + tracks = splitInitSegment(first.value.data); + if (!tracks.some(track => track.kind === "video")) { + throw new Error("init segment without a video track"); + } - const media = first.value.media ?? this.context.media; - const startedAt = first.value.startedAt ?? session.startedAt; - const durations: number[] = []; - const notes: string[] = []; + const prepare = (segment: CMAFSegment): PreparedSegment => { + const fallback = segment.duration ?? DEFAULT_SEGMENT_DURATION_SECONDS; + const parts = splitMediaSegment(segment.data, tracks).map(part => (part.duration > 0 ? part : { ...part, duration: fallback })); + return { parts, duration: parts.reduce((longest, part) => Math.max(longest, part.duration), 0) }; + }; + + // two segments of lookahead: whether the segment after the current one is the last decides where a session ends + const window: PreparedSegment[] = []; + let ended = false; + const fill = async () => { + while (!ended && window.length < 3) { + if (session.stopRequested) { + ended = true; + break; + } + const next = await clip.next(); + if (next.done) { + ended = true; + } else if (next.value.type === "media") { + const prepared = prepare(next.value); + const video = prepared.parts.find(part => part.track.kind === "video"); + const previous = window.at(-1); + // every segment starts with a sync sample (CMAF, EXT-X-INDEPENDENT-SEGMENTS), a fragment that does not + // continues the segment before it + if (previous && video && !video.startsWithSync) { + appendSegment(previous, prepared); + } else { + window.push(prepared); + } + ended = !!next.value.last; + } + } + }; - if (!(await this.putChecked(cmafSessionId, client, initPath, sealSegment(clipKey, first.value.data), "video/mp4"))) { - return; - } - // DASH-IF ingest interface 1 takes the init and media segments only, the playlists are interface 2 extras the - // publishing point may reject, so their outcome is reported but does not end the upload - await this.putOptional(client, mediaPlaylistPath, Buffer.from(buildMediaPlaylist(clipKey, durations, false)), PLAYLIST_CONTENT_TYPE, notes); - const multivariant = Buffer.from(buildMultivariantPlaylist(clipKey, startedAt, this.context.sensorUUID, media)); - await this.putOptional(client, multivariantPath, multivariant, PLAYLIST_CONTENT_TYPE, notes); - - let finished = false; - for await (const segment of clip) { - if (segment.type !== "media") { - continue; + let reserved: bigint | undefined = session.clipId; + for (;;) { + await fill(); + const segment = window.shift(); + if (!segment) { + break; } - const segmentPath = `${base}${TRACK_NAME}/segment_${FIRST_SEGMENT_NUMBER + index}.m4s`; - if (!(await this.putChecked(cmafSessionId, client, segmentPath, sealSegment(clipKey, segment.data), "video/iso.segment"))) { - return; + + const lastFollower = ended && window.length === 1 ? window[0] : undefined; + if (current && this.endsBefore(current, segment, lastFollower)) { + await this.endSession(connection, current, tracks, targetDuration); + if (!current.ended) { + return; + } + current = undefined; } - index++; - durations.push(segment.duration ?? SEGMENT_DURATION_SECONDS); - finished = session.stopRequested || !!segment.last; - await this.putOptional(client, mediaPlaylistPath, Buffer.from(buildMediaPlaylist(clipKey, durations, finished)), PLAYLIST_CONTENT_TYPE, notes); - if (finished) { - break; + if (!current) { + // the target duration must not change once announced, the headroom absorbs keyframe jitter + targetDuration ||= Math.ceil(segment.duration) + 1; + const known = [segment, ...window].map(entry => entry.parts); + current = await this.beginSession(connection, base, tracks, known, targetDuration, reserved ?? this.context.nextSessionNumber()); + reserved = undefined; + if (current.failed) { + return; + } } - } - // the generator ended on its own (source stopped or reached the stop timestamp) without a final fragment flag - if (!finished) { - await this.putOptional(client, mediaPlaylistPath, Buffer.from(buildMediaPlaylist(clipKey, durations, true)), PLAYLIST_CONTENT_TYPE, notes); + const active = current; + await Promise.all(segment.parts.map(part => this.putSegment(connection, active, part))); + if (active.failed) { + return; + } + active.seconds += segment.duration; } - this.context.reportSessionStop(cmafSessionId, notes.length ? notes.join(" | ") : undefined); - debug("session %s finished after %d segments", cmafSessionId, index); + if (current) { + await this.endSession(connection, current, tracks, targetDuration); + } + debug("upload of clip %s finished", session.clipId); } catch (error) { const message = error instanceof Error ? error.message : String(error); - debug("session %s failed: %s", cmafSessionId, message); - this.context.reportError(cmafSessionId, CMAFError.CONNECTION_FAILED, message); + debug("upload of clip %s failed: %s", session.clipId, message); + if (!current?.failed) { + this.context.reportError(current?.number ?? session.clipId, CMAFError.CONNECTION_FAILED, message); + } + if (current) { + current.failed = true; + } } finally { + // a session the server saw begin is closed even after a failure, so it is not left half open on the server side + if (current && !current.ended) { + await this.closeTracks(connection, current, tracks, targetDuration).catch(() => undefined); + } await clip.return?.(undefined).catch(() => undefined); - client.close(); + connection.renew(); } } - private async putOptional(client: http2.ClientHttp2Session, path: string, body: Buffer, contentType: string, notes: string[]): Promise { - const result = await put(client, path, body, contentType); - const note = `PUT ${path.slice(path.indexOf("session_"))} -> ${result.status}${result.body ? ` ${result.body}` : ""}`; - if (!notes.includes(note)) { - notes.push(note); + // a session ends after five minutes; a last segment that would not fit takes the current one along, so no session + // is left with a single segment + private endsBefore(session: CMAFSession, segment: PreparedSegment, lastFollower?: PreparedSegment): boolean { + if (Date.now() - session.startedAt >= MAX_SESSION_SECONDS * 1000 || session.seconds + segment.duration > MAX_SESSION_SECONDS) { + return true; } + return !!lastFollower && session.seconds + segment.duration + lastFollower.duration > MAX_SESSION_SECONDS; } - private async putChecked(cmafSessionId: bigint, client: http2.ClientHttp2Session, path: string, body: Buffer, contentType: string): Promise { - const result = await put(client, path, body, contentType); + private async beginSession(connection: IngestConnection, base: string, tracks: CMAFTrack[], known: CMAFTrackSegment[][], targetDuration: number, + number: bigint): Promise { + const session: CMAFSession = { + number, + prefix: `${base}session_${number}/`, + startedAt: Date.now(), + seconds: 0, + durations: new Map(tracks.map(track => [track.id, []])), + opened: new Set(), + failed: false, + ended: false, + }; + this.context.reportSessionStart(number); + debug("session %s starting with tracks %s", number, tracks.map(track => track.name).join(", ")); + + const multivariant = Buffer.from(buildMultivariantPlaylist(tracks, known)); + if (!(await this.putChecked(connection, session, `${session.prefix}index.m3u8`, multivariant, PLAYLIST_CONTENT_TYPE))) { + return session; + } + // Matter 1.6.1 11.7.1.8.2: tracks start after the multivariant playlist, each with its initial playlist and its + // CMAF header, and are uploaded in parallel + await Promise.all(tracks.map(async track => { + const playlist = Buffer.from(buildMediaPlaylist(track, targetDuration)); + if (!(await this.putChecked(connection, session, `${session.prefix}${track.name}/index.m3u8`, playlist, PLAYLIST_CONTENT_TYPE))) { + return; + } + session.opened.add(track.id); + await this.putChecked(connection, session, `${session.prefix}${track.name}/${track.name}.init`, track.init, INIT_CONTENT_TYPE); + })); + return session; + } + + private async putSegment(connection: IngestConnection, session: CMAFSession, part: CMAFTrackSegment): Promise { + const durations = session.durations.get(part.track.id)!; + const path = `${session.prefix}${part.track.name}/segment_${FIRST_SEGMENT_NUMBER + durations.length}.m4s`; + const headers = { "x-extinf-duration": formatDuration(part.duration) }; + if (await this.putChecked(connection, session, path, part.data, SEGMENT_CONTENT_TYPE, headers)) { + durations.push(part.duration); + } + } + + private async endSession(connection: IngestConnection, session: CMAFSession, tracks: CMAFTrack[], targetDuration: number): Promise { + await this.closeTracks(connection, session, tracks, targetDuration); + if (!session.failed) { + session.ended = true; + this.context.reportSessionStop(session.number); + debug("session %s finished after %ds", session.number, Math.round(session.seconds)); + } + } + + private async closeTracks(connection: IngestConnection, session: CMAFSession, tracks: CMAFTrack[], targetDuration: number): Promise { + await Promise.all(tracks.filter(track => session.opened.has(track.id)).map(async track => { + const playlist = Buffer.from(buildMediaPlaylist(track, targetDuration, session.durations.get(track.id))); + if (await this.putChecked(connection, session, `${session.prefix}${track.name}/index.m3u8`, playlist, PLAYLIST_CONTENT_TYPE)) { + session.opened.delete(track.id); + } + })); + } + + private async putChecked(connection: IngestConnection, session: CMAFSession, path: string, body: Buffer, contentType: string, + headers: http2.OutgoingHttpHeaders = {}): Promise { + const result = await this.transfer(connection, path, body, contentType, headers); if (result.status >= 200 && result.status < 300) { return true; } - const detail = `PUT ${path.slice(path.indexOf("session_"))} (${body.length} bytes) -> ${result.status} ${result.body}`.trim(); - this.context.reportError(cmafSessionId, mapStatus(result.status), detail); + if (!session.failed) { + session.failed = true; + const response = [result.body, result.headers].filter(Boolean).join(" "); + const detail = `PUT ${path.slice(path.indexOf("session_"))} (${body.length} bytes) -> ${result.status} ${response}`; + this.context.reportError(session.number, mapStatus(result.status), detail); + } return false; } + + // a 4xx refuses the request itself, sending it unchanged again cannot succeed; transport errors and 5xx are retried + private async transfer(connection: IngestConnection, path: string, body: Buffer, contentType: string, + headers: http2.OutgoingHttpHeaders): Promise { + for (let attempt = 0; ; attempt++) { + try { + const result = await put(connection.session(), path, body, contentType, { "user-agent": connection.userAgent, ...headers }); + if (result.status < 500 || attempt >= MAX_RETRIES) { + return result; + } + } catch (error) { + if (attempt >= MAX_RETRIES) { + throw error; + } + debug("PUT %s failed, retrying: %s", path.slice(path.indexOf("session_")), error instanceof Error ? error.message : error); + } + connection.renew(); + await sleep(RETRY_DELAY_MS); + } + } } diff --git a/src/lib/camera/CMAFTracks.spec.ts b/src/lib/camera/CMAFTracks.spec.ts new file mode 100644 index 000000000..0a7c7332b --- /dev/null +++ b/src/lib/camera/CMAFTracks.spec.ts @@ -0,0 +1,148 @@ +import { initSegment, mediaSegment } from "../../test-utils/fmp4"; +import { splitInitSegment, splitMediaSegment } from "./CMAFTracks"; + +const VIDEO = { id: 1, handler: "vide" as const, timescale: 90000 }; +const AUDIO = { id: 2, handler: "soun" as const, timescale: 32000, defaultSampleDuration: 1024 }; + +function topLevel(buffer: Buffer): { type: string, start: number, end: number }[] { + const result = []; + let position = 0; + while (position + 8 <= buffer.length) { + const size = buffer.readUInt32BE(position); + result.push({ type: buffer.toString("latin1", position + 4, position + 8), start: position, end: position + size }); + position += size; + } + return result; +} + +function count(buffer: Buffer, type: string): number { + let found = 0; + for (let index = buffer.indexOf(type, 0, "latin1"); index >= 0; index = buffer.indexOf(type, index + 1, "latin1")) { + found++; + } + return found; +} + +// the payload a single-traf segment points at: moof start + trun data offset +function payload(segment: Buffer): Buffer { + const boxes = topLevel(segment); + const moof = boxes.find(entry => entry.type === "moof")!; + const mdat = boxes.find(entry => entry.type === "mdat")!; + const trun = segment.indexOf("trun", moof.start, "latin1") - 4; + const dataOffset = segment.readInt32BE(trun + 16); + expect(moof.start + dataOffset).toBe(mdat.start + 8); + return segment.subarray(mdat.start + 8, mdat.end); +} + +describe("CMAFTracks", () => { + test("splits the init segment into one init per track", () => { + const tracks = splitInitSegment(initSegment([VIDEO, AUDIO])); + + expect(tracks).toMatchObject([ + { id: 1, kind: "video", name: "high", timescale: 90000, codecs: "hvc1.1.6.L93.B0", width: 1920, height: 1080, defaultSampleDuration: 0 }, + { id: 2, kind: "audio", name: "audio1", timescale: 32000, codecs: "mp4a.40.2", channels: 1, defaultSampleDuration: 1024 }, + ]); + for (const track of tracks) { + expect(topLevel(track.init).map(entry => entry.type)).toEqual(["ftyp", "moov"]); + // CMAF headers carry the CMAF track brand + expect(track.init.toString("latin1", 16, track.init.readUInt32BE(0))).toBe("iso6cmfc"); + expect(count(track.init, "trak")).toBe(1); + expect(count(track.init, "trex")).toBe(1); + expect(count(track.init, "mvhd")).toBe(1); + } + expect(count(tracks[0].init, "hvc1")).toBe(1); + expect(count(tracks[1].init, "mp4a")).toBe(1); + }); + + test("describes an Opus audio track", () => { + const [, audio] = splitInitSegment(initSegment([VIDEO, { ...AUDIO, timescale: 48000, codec: "opus" }])); + expect(audio).toMatchObject({ kind: "audio", name: "audio1", codecs: "Opus", channels: 1 }); + expect(count(audio.init, "Opus")).toBe(1); + expect(count(audio.init, "dOps")).toBe(1); + }); + + test("names the video tracks by resolution and numbers the audio tracks", () => { + const low = { ...VIDEO, id: 3, width: 640, height: 360 }; + const mid = { ...VIDEO, id: 4, width: 1280, height: 720 }; + const tracks = splitInitSegment(initSegment([low, AUDIO, VIDEO, mid, { ...AUDIO, id: 5 }])); + expect(tracks.map(track => `${track.id} ${track.name}`)).toEqual(["1 high", "4 mid", "3 low", "2 audio1", "5 audio2"]); + expect(() => splitInitSegment(initSegment([VIDEO, low, mid, { ...VIDEO, id: 6 }]))).toThrow("at most 3 video tracks"); + }); + + test("splits a muxed fragment and keeps every sample byte", () => { + const tracks = splitInitSegment(initSegment([VIDEO, AUDIO])); + const videoSamples = [Buffer.alloc(300, 0xaa), Buffer.alloc(120, 0xab)]; + const audioSamples = [Buffer.alloc(50, 0xba), Buffer.alloc(60, 0xbb), Buffer.alloc(70, 0xbc)]; + const segment = mediaSegment(7, [ + { trackId: 1, durations: [180000, 180000], samples: videoSamples }, + { trackId: 2, durations: [1024, 1024, 1024], samples: audioSamples }, + ]); + + const [video, audio] = splitMediaSegment(segment, tracks); + + expect(video.track.name).toBe("high"); + expect(video.duration).toBe(4); + expect(video.samples).toBe(2); + expect(topLevel(video.data).map(entry => entry.type)).toEqual(["moof", "mdat"]); + expect(payload(video.data)).toEqual(Buffer.concat(videoSamples)); + + expect(audio.track.name).toBe("audio1"); + expect(audio.duration).toBeCloseTo(3072 / 32000); + expect(audio.samples).toBe(3); + expect(topLevel(audio.data).map(entry => entry.type)).toEqual(["moof", "mdat"]); + expect(payload(audio.data)).toEqual(Buffer.concat(audioSamples)); + expect(count(audio.data, "traf")).toBe(1); + }); + + test("writes the prft again for every track", () => { + const tracks = splitInitSegment(initSegment([VIDEO, AUDIO])); + const ntp = 0xec5f3a1000000000n; + // video starts at 10 s, audio 0.1 s later; the prft refers to the video track + const segment = mediaSegment(3, [ + { trackId: 1, durations: [90000], samples: [Buffer.alloc(40, 0x01)], decodeTime: 900000n }, + { trackId: 2, durations: [1024], samples: [Buffer.alloc(30, 0x02)], decodeTime: 323200n }, + ], { prft: { trackId: 1, ntp, mediaTime: 900000n, flags: 0x18 } }); + + const [video, audio] = splitMediaSegment(segment, tracks); + for (const [part, mediaTime, expectedNtp] of [[video, 900000n, ntp], [audio, 323200n, ntp + 429496729n]] as const) { + expect(topLevel(part.data).map(entry => entry.type)).toEqual(["prft", "moof", "mdat"]); + expect(part.data.readUInt8(8)).toBe(1); + expect(part.data.readUInt32BE(8) & 0xffffff).toBe(0x18); + expect(part.data.readUInt32BE(12)).toBe(part.track.id); + expect(part.data.readBigUInt64BE(16)).toBe(expectedNtp); + expect(part.data.readBigUInt64BE(24)).toBe(mediaTime); + expect(payload(part.data.subarray(32))).toHaveLength(part.track.kind === "video" ? 40 : 30); + } + }); + + test("follows the previous traf when the moof is not the base", () => { + const tracks = splitInitSegment(initSegment([VIDEO, AUDIO])); + const videoSamples = [Buffer.alloc(40, 0x01)]; + const audioSamples = [Buffer.alloc(30, 0x02)]; + const segment = mediaSegment(1, [ + { trackId: 1, durations: [90000], samples: videoSamples }, + { trackId: 2, durations: [1024], samples: audioSamples }, + ], { defaultBaseIsMoof: false }); + + const [video, audio] = splitMediaSegment(segment, tracks); + expect(payload(video.data)).toEqual(videoSamples[0]); + expect(payload(audio.data)).toEqual(audioSamples[0]); + }); + + test("tells whether a fragment starts with a sync sample", () => { + const tracks = splitInitSegment(initSegment([VIDEO, AUDIO])); + const sample = Buffer.alloc(10); + const synced = splitMediaSegment(mediaSegment(1, [{ trackId: 1, durations: [90000], samples: [sample] }]), tracks); + const unsynced = splitMediaSegment(mediaSegment(2, [{ trackId: 1, durations: [90000], samples: [sample], nonSyncStart: true }]), tracks); + expect(synced[0].startsWithSync).toBe(true); + expect(unsynced[0].startsWithSync).toBe(false); + // the data offset still points at the samples after the extra first sample flags field + expect(payload(unsynced[0].data)).toEqual(sample); + }); + + test("leaves out tracks without samples in the fragment", () => { + const tracks = splitInitSegment(initSegment([VIDEO, AUDIO])); + const segment = mediaSegment(1, [{ trackId: 1, durations: [90000], samples: [Buffer.alloc(10)] }]); + expect(splitMediaSegment(segment, tracks).map(part => part.track.name)).toEqual(["high"]); + }); +}); diff --git a/src/lib/camera/CMAFTracks.ts b/src/lib/camera/CMAFTracks.ts new file mode 100644 index 000000000..341a89e8e --- /dev/null +++ b/src/lib/camera/CMAFTracks.ts @@ -0,0 +1,504 @@ +/** + * One CMAF track of a muxed fMP4 recording: a CMAF track carries a single media type, so audio and video are uploaded + * as separate tracks. + * + * @group Camera Secure Video + */ +export interface CMAFTrack { + id: number; + kind: "video" | "audio"; + /** + * track name in the upload paths, the names the iCloud ingest expects: `high`, `mid` and `low` for the video tracks + * by resolution, `audio1` and up for the audio tracks + */ + name: string; + timescale: number; + /** RFC 6381 codecs value from the sample entry; known for HEVC, AVC and AAC */ + codecs?: string; + /** video only, from the visual sample entry */ + width?: number; + height?: number; + /** audio only, from the audio sample entry */ + channels?: number; + /** CMAF header holding only this track */ + init: Buffer; + defaultSampleDuration: number; + defaultSampleFlags: number; +} + +/** + * The part of a media segment that belongs to one track. + * + * @group Camera Secure Video + */ +export interface CMAFTrackSegment { + track: CMAFTrack; + data: Buffer; + /** in seconds, from the sample durations */ + duration: number; + samples: number; + /** the first sample is a sync sample, so the segment can be decoded on its own */ + startsWithSync: boolean; +} + +interface Box { + type: string; + start: number; + contentStart: number; + end: number; +} + +interface Run { + start: number; + length: number; +} + +interface ProducerReference { + flags: number; + trackId: number; + /** NTP timestamp, 32.32 fixed point */ + ntp: bigint; + /** decode time in the timescale of the reference track */ + mediaTime: bigint; +} + +const VIDEO_TRACK_NAMES = ["high", "mid", "low"]; + +const TFHD_BASE_DATA_OFFSET = 0x1; +const TFHD_SAMPLE_DESCRIPTION_INDEX = 0x2; +const TFHD_DEFAULT_SAMPLE_DURATION = 0x8; +const TFHD_DEFAULT_SAMPLE_SIZE = 0x10; +const TFHD_DEFAULT_SAMPLE_FLAGS = 0x20; +const TFHD_DEFAULT_BASE_IS_MOOF = 0x20000; +const TRUN_DATA_OFFSET = 0x1; +const TRUN_FIRST_SAMPLE_FLAGS = 0x4; +const TRUN_SAMPLE_DURATION = 0x100; +const TRUN_SAMPLE_SIZE = 0x200; +const TRUN_SAMPLE_FLAGS = 0x400; +const TRUN_SAMPLE_COMPOSITION_TIME_OFFSET = 0x800; +const SAMPLE_IS_NON_SYNC = 0x10000; + +function boxes(buffer: Buffer, start = 0, end = buffer.length): Box[] { + const result: Box[] = []; + let position = start; + while (position + 8 <= end) { + let size = buffer.readUInt32BE(position); + let contentStart = position + 8; + if (size === 1) { + size = Number(buffer.readBigUInt64BE(position + 8)); + contentStart += 8; + } else if (size === 0) { + size = end - position; + } + if (size < 8 || position + size > end) { + throw new Error(`truncated ${buffer.toString("latin1", position + 4, position + 8)} box`); + } + result.push({ type: buffer.toString("latin1", position + 4, position + 8), start: position, contentStart, end: position + size }); + position += size; + } + return result; +} + +function child(buffer: Buffer, parent: Box, type: string): Box | undefined { + return boxes(buffer, parent.contentStart, parent.end).find(box => box.type === type); +} + +function slice(buffer: Buffer, box: Box): Buffer { + return buffer.subarray(box.start, box.end); +} + +function makeBox(type: string, ...children: Buffer[]): Buffer { + const header = Buffer.alloc(8); + header.writeUInt32BE(8 + children.reduce((sum, buffer) => sum + buffer.length, 0), 0); + header.write(type, 4, "latin1"); + return Buffer.concat([header, ...children]); +} + +function fullBoxVersion(buffer: Buffer, box: Box): number { + return buffer.readUInt8(box.contentStart); +} + +function trackId(buffer: Buffer, trak: Box): number { + const tkhd = child(buffer, trak, "tkhd"); + if (!tkhd) { + throw new Error("trak without tkhd"); + } + return buffer.readUInt32BE(tkhd.contentStart + (fullBoxVersion(buffer, tkhd) === 1 ? 20 : 12)); +} + +function descriptorLength(buffer: Buffer, position: number): { length: number, next: number } { + let length = 0; + for (let i = 0; i < 4; i++) { + const byte = buffer.readUInt8(position++); + length = (length << 7) | (byte & 0x7f); + if (!(byte & 0x80)) { + break; + } + } + return { length, next: position }; +} + +// RFC 6381: mp4a..