@kusinta/iot-schema 0.2.0-beta.5 → 0.2.0-beta.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kusinta/iot-schema",
-  "version": "0.2.0-beta.5",
+  "version": "0.2.0-beta.6",
   "type": "module",
   "license": "MIT",
   "files": ["src"],
@@ -10,6 +10,7 @@
   },
   "exports": {
     "./common":                 "./src/kusinta/iot/common/v1/types_pb.js",
+    "./common/pairing":         "./src/kusinta/iot/common/v1/pairing_pb.js",
     "./identity":               "./src/kusinta/iot/identity/v1/identity_pb.js",
     "./device":                 "./src/kusinta/iot/device/v1/device_pb.js",
     "./device/descriptor":      "./src/kusinta/iot/device/v1/descriptor_pb.js",

package/src/kusinta/iot/common/v1/pairing_pb.d.ts

@@ -0,0 +1,199 @@
+// @generated by protoc-gen-es v2.12.0 with parameter "target=js+dts,import_extension=js"
+// @generated from file kusinta/iot/common/v1/pairing.proto (package kusinta.iot.common.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenEnum, GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { Message } from "@bufbuild/protobuf";
+
+/**
+ * Describes the file kusinta/iot/common/v1/pairing.proto.
+ */
+export declare const file_kusinta_iot_common_v1_pairing: GenFile;
+
+/**
+ * A pairing failure and what can be said about it, the pairing counterpart of CommandError.
+ *
+ * The message matters more here than elsewhere: DEVICE_UNUSABLE is the code a user is most
+ * likely to see and least able to act on, and naming the device that joined is the whole
+ * difference between "something went wrong" and "this hub does not support that model yet".
+ *
+ * @generated from message kusinta.iot.common.v1.PairingErrorDetail
+ */
+export declare type PairingErrorDetail = Message<"kusinta.iot.common.v1.PairingErrorDetail"> & {
+  /**
+   * @generated from field: kusinta.iot.common.v1.PairingError code = 1;
+   */
+  code: PairingError;
+
+  /**
+   * human-readable; may name the device, its model, or the fault
+   *
+   * @generated from field: string message = 2;
+   */
+  message: string;
+};
+
+/**
+ * Describes the message kusinta.iot.common.v1.PairingErrorDetail.
+ * Use `create(PairingErrorDetailSchema)` to create a new message.
+ */
+export declare const PairingErrorDetailSchema: GenMessage<PairingErrorDetail>;
+
+/**
+ * How long a hub accepts new devices, and which it will take.
+ *
+ * One message on both legs rather than the same three fields declared twice: the clamp rule
+ * and the meaning of a hint are the sort of thing that is written once and then diverges,
+ * and the two copies had already begun to.
+ *
+ * @generated from message kusinta.iot.common.v1.PairingWindow
+ */
+export declare type PairingWindow = Message<"kusinta.iot.common.v1.PairingWindow"> & {
+  /**
+   * How long to accept arrivals. Whoever forwards this clamps it, and so does whoever acts
+   * on it: a window is an interval during which anything nearby can join, so its length is a
+   * security parameter rather than purely the caller's to choose.
+   *
+   * Absent means "no preference, use the default" — distinct from a caller asking for zero.
+   *
+   * @generated from field: optional uint32 duration_seconds = 1;
+   */
+  durationSeconds?: number | undefined;
+
+  /**
+   * The identifier printed on the device being paired, where the technology has one that is
+   * legible and the person is holding it. Free-form: what is printed differs per technology,
+   * and nothing between the app and the hub interprets it.
+   *
+   * Setting it changes the mechanism, not just the accuracy. The hub is restricted to that
+   * device and the arrival is verified against this value, so an arrival is attributed on
+   * identity. Leaving it empty opens the window to anything nearby, and attribution falls
+   * back to the arrival being the only one — which is why one window may be open at a time.
+   *
+   * Verification is not optional where this is set. A restriction can silently fail to take,
+   * and an arrival attributed on a restriction that did not hold is the wrong device in
+   * someone's home.
+   *
+   * @generated from field: string device_hint = 2;
+   */
+  deviceHint: string;
+
+  /**
+   * How many arrivals this one window may attribute. Absent means one.
+   *
+   * A batch suits commissioning, where devices are paired in a row and become a building's
+   * rather than any person's. It does not suit a caller whose pairing mints personal
+   * ownership.
+   *
+   * A hint and a batch cannot be combined, and that is a contradiction rather than a
+   * limitation: device_hint names one device, so a window restricted to it can never produce
+   * a second arrival to attribute.
+   *
+   * @generated from field: optional uint32 max_devices = 3;
+   */
+  maxDevices?: number | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.common.v1.PairingWindow.
+ * Use `create(PairingWindowSchema)` to create a new message.
+ */
+export declare const PairingWindowSchema: GenMessage<PairingWindow>;
+
+/**
+ * Why a pairing attempt did not produce a device, in one vocabulary both the app and a
+ * connector speak.
+ *
+ * Shared rather than mirrored, for the reason CommandError's comment gives: mirrored enums
+ * leave every connector inventing its own spellings and something in the middle keeping a
+ * translation table that silently falls behind. A connector produces the subset it can
+ * observe; the gateway produces the rest and passes a connector's value through unchanged.
+ *
+ * Every value answers one question: *what should the client do now?* A code that does not
+ * change the answer does not need to exist, which is why "the device is on the hub and
+ * unusable" is one value and not two.
+ *
+ * @generated from enum kusinta.iot.common.v1.PairingError
+ */
+export enum PairingError {
+  /**
+   * Sender set no code, or sent one this client's schema does not know.
+   *
+   * This must stay the safe reading. A client decodes every value added after its build as
+   * UNSPECIFIED, so the sensible handling is "it did not work, offering a retry is
+   * reasonable" — and no value below is so dangerous that reading it this way misleads.
+   *
+   * @generated from enum value: PAIRING_ERROR_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * The caller may not pair here. Permanent for this caller: stop, and say so.
+   *
+   * @generated from enum value: PAIRING_ERROR_NOT_ENTITLED = 1;
+   */
+  NOT_ENTITLED = 1,
+
+  /**
+   * A pairing window is already open, and only one may be. Retrying after it closes is the
+   * right response; retrying at once is not.
+   *
+   * The exclusivity is not incidental. Where a request names no device, the only thing
+   * attributing an arrival to a requester is that theirs was the one window open.
+   *
+   * @generated from enum value: PAIRING_ERROR_ALREADY_IN_PROGRESS = 2;
+   */
+  ALREADY_IN_PROGRESS = 2,
+
+  /**
+   * The connector could not be reached, or refused to open its window. Transient.
+   *
+   * @generated from enum value: PAIRING_ERROR_CONNECTOR_UNAVAILABLE = 3;
+   */
+  CONNECTOR_UNAVAILABLE = 3,
+
+  /**
+   * The window closed with nothing paired: no device was put into pairing mode, or it was
+   * out of range, or its batteries are flat. The ordinary outcome of a user who walked away,
+   * so the useful response is to say what to do and offer another go, not to report a fault.
+   *
+   * @generated from enum value: PAIRING_ERROR_NO_DEVICE_APPEARED = 4;
+   */
+  NO_DEVICE_APPEARED = 4,
+
+  /**
+   * A device joined the hub and cannot be presented — the connector has no model for it, or
+   * could not assemble a complete description of it.
+   *
+   * One value rather than two, because the client does the same thing either way: stop, do
+   * not retry, and tell the user there is now an unusable device on their hub. Which of the
+   * two it was belongs in PairingErrorDetail.message, where it can name the device.
+   *
+   * It stays joined deliberately. A later connector release that models it adopts it with
+   * nobody returning to the hardware, where removing it would need someone standing there.
+   *
+   * @generated from enum value: PAIRING_ERROR_DEVICE_UNUSABLE = 5;
+   */
+  DEVICE_UNUSABLE = 5,
+
+  /**
+   * A device joined that is not the one the request named. The connector checked the arrival
+   * against the identifier it was given and they did not match, so it was not attributed.
+   *
+   * @generated from enum value: PAIRING_ERROR_WRONG_DEVICE = 6;
+   */
+  WRONG_DEVICE = 6,
+
+  /**
+   * A fault on the gateway's or the connector's own side. Not the caller's doing.
+   *
+   * @generated from enum value: PAIRING_ERROR_INTERNAL = 7;
+   */
+  INTERNAL = 7,
+}
+
+/**
+ * Describes the enum kusinta.iot.common.v1.PairingError.
+ */
+export declare const PairingErrorSchema: GenEnum<PairingError>;
+

package/src/kusinta/iot/common/v1/pairing_pb.js

@@ -0,0 +1,50 @@
+// @generated by protoc-gen-es v2.12.0 with parameter "target=js+dts,import_extension=js"
+// @generated from file kusinta/iot/common/v1/pairing.proto (package kusinta.iot.common.v1, syntax proto3)
+/* eslint-disable */
+
+import { enumDesc, fileDesc, messageDesc, tsEnum } from "@bufbuild/protobuf/codegenv2";
+
+/**
+ * Describes the file kusinta/iot/common/v1/pairing.proto.
+ */
+export const file_kusinta_iot_common_v1_pairing = /*@__PURE__*/
+  fileDesc("CiNrdXNpbnRhL2lvdC9jb21tb24vdjEvcGFpcmluZy5wcm90bxIVa3VzaW50YS5pb3QuY29tbW9uLnYxIlgKElBhaXJpbmdFcnJvckRldGFpbBIxCgRjb2RlGAEgASgOMiMua3VzaW50YS5pb3QuY29tbW9uLnYxLlBhaXJpbmdFcnJvchIPCgdtZXNzYWdlGAIgASgJIoIBCg1QYWlyaW5nV2luZG93Eh0KEGR1cmF0aW9uX3NlY29uZHMYASABKA1IAIgBARITCgtkZXZpY2VfaGludBgCIAEoCRIYCgttYXhfZGV2aWNlcxgDIAEoDUgBiAEBQhMKEV9kdXJhdGlvbl9zZWNvbmRzQg4KDF9tYXhfZGV2aWNlcyqiAgoMUGFpcmluZ0Vycm9yEh0KGVBBSVJJTkdfRVJST1JfVU5TUEVDSUZJRUQQABIeChpQQUlSSU5HX0VSUk9SX05PVF9FTlRJVExFRBABEiUKIVBBSVJJTkdfRVJST1JfQUxSRUFEWV9JTl9QUk9HUkVTUxACEicKI1BBSVJJTkdfRVJST1JfQ09OTkVDVE9SX1VOQVZBSUxBQkxFEAMSJAogUEFJUklOR19FUlJPUl9OT19ERVZJQ0VfQVBQRUFSRUQQBBIhCh1QQUlSSU5HX0VSUk9SX0RFVklDRV9VTlVTQUJMRRAFEh4KGlBBSVJJTkdfRVJST1JfV1JPTkdfREVWSUNFEAYSGgoWUEFJUklOR19FUlJPUl9JTlRFUk5BTBAHQgJIAWIGcHJvdG8z");
+
+/**
+ * Describes the message kusinta.iot.common.v1.PairingErrorDetail.
+ * Use `create(PairingErrorDetailSchema)` to create a new message.
+ */
+export const PairingErrorDetailSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_common_v1_pairing, 0);
+
+/**
+ * Describes the message kusinta.iot.common.v1.PairingWindow.
+ * Use `create(PairingWindowSchema)` to create a new message.
+ */
+export const PairingWindowSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_common_v1_pairing, 1);
+
+/**
+ * Describes the enum kusinta.iot.common.v1.PairingError.
+ */
+export const PairingErrorSchema = /*@__PURE__*/
+  enumDesc(file_kusinta_iot_common_v1_pairing, 0);
+
+/**
+ * Why a pairing attempt did not produce a device, in one vocabulary both the app and a
+ * connector speak.
+ *
+ * Shared rather than mirrored, for the reason CommandError's comment gives: mirrored enums
+ * leave every connector inventing its own spellings and something in the middle keeping a
+ * translation table that silently falls behind. A connector produces the subset it can
+ * observe; the gateway produces the rest and passes a connector's value through unchanged.
+ *
+ * Every value answers one question: *what should the client do now?* A code that does not
+ * change the answer does not need to exist, which is why "the device is on the hub and
+ * unusable" is one value and not two.
+ *
+ * @generated from enum kusinta.iot.common.v1.PairingError
+ */
+export const PairingError = /*@__PURE__*/
+  tsEnum(PairingErrorSchema);
+

package/src/kusinta/iot/connector/v1/connector_pb.d.ts

@@ -9,6 +9,7 @@ import type { ConnectorTransport } from "../../common/v1/types_pb.js";
 import type { Device } from "../../device/v1/device_pb.js";
 import type { Timestamp } from "@bufbuild/protobuf/wkt";
 import type { AttributeWriteRequest, CommandError, DeviceCommand } from "../../webrtc/v1/command_pb.js";
+import type { PairingErrorDetail, PairingWindow } from "../../common/v1/pairing_pb.js";
 import type { PropertyUpdateBatch } from "../../device/v1/property_update_pb.js";
 import type { DeviceEventBatch } from "../../device/v1/device_event_pb.js";
 
@@ -122,6 +123,25 @@ export declare type DeviceAnnouncement = Message<"kusinta.iot.connector.v1.Devic
    * @generated from field: kusinta.iot.device.v1.Device device = 2;
    */
   device?: Device | undefined;
+
+  /**
+   * The pairing request this device arrived for, empty for a device that arrived on its own.
+   *
+   * This field is the whole attribution mechanism. A connector is the only party that knows
+   * when its own hub was accepting devices, so it decides whether an arrival belongs to a
+   * request and says so here.
+   *
+   * Set it only when the arrival was actually checked. An arrival that fails the check is
+   * still announced — the device exists and has joined — but with this empty, which files it
+   * as belonging to nobody rather than to the wrong person.
+   *
+   * This is EnterPairingMode.request_id, minted per connector, and NOT an app message id:
+   * whoever forwards the outcome to the app has to map it back. The name avoids `in_reply_to`
+   * for that reason, which everywhere else in this schema means the app's own message id.
+   *
+   * @generated from field: string pairing_request_id = 3;
+   */
+  pairingRequestId: string;
 };
 
 /**
@@ -309,6 +329,127 @@ export declare type ConnectorCommandResult = Message<"kusinta.iot.connector.v1.C
  */
 export declare const ConnectorCommandResultSchema: GenMessage<ConnectorCommandResult>;
 
+/**
+ * Tells a connector to accept new devices for a while, gateway → connector.
+ *
+ * Named for what the connector does rather than for what the app asked. The two legs are
+ * named differently on purpose: the app starts one pairing, and the gateway may put several
+ * connectors into pairing mode to serve it.
+ *
+ * @generated from message kusinta.iot.connector.v1.EnterPairingMode
+ */
+export declare type EnterPairingMode = Message<"kusinta.iot.connector.v1.EnterPairingMode"> & {
+  /**
+   * echoed on PairingModeResult, PairingModeEnded and the announcement
+   *
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * How long, which device, how many. See PairingWindow — and clamp the duration again here.
+   * A connector is the last thing standing between a number on the wire and a radio that
+   * accepts anything nearby for that long.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingWindow window = 2;
+   */
+  window?: PairingWindow | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.EnterPairingMode.
+ * Use `create(EnterPairingModeSchema)` to create a new message.
+ */
+export declare const EnterPairingModeSchema: GenMessage<EnterPairingMode>;
+
+/**
+ * A connector's answer to EnterPairingMode: whether the window opened, and nothing more.
+ *
+ * The same accept-now-report-later split as ConnectorCommandResult, for the same reason — a
+ * connector that waited for a device to wake before answering would blow every deadline
+ * above it. What the window produced arrives later, as PairingModeEnded.
+ *
+ * @generated from message kusinta.iot.connector.v1.PairingModeResult
+ */
+export declare type PairingModeResult = Message<"kusinta.iot.connector.v1.PairingModeResult"> & {
+  /**
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * @generated from field: bool accepted = 2;
+   */
+  accepted: boolean;
+
+  /**
+   * Why the window did not open. Only what a connector can observe at this point:
+   * CONNECTOR_UNAVAILABLE, INTERNAL. NOT_ENTITLED and ALREADY_IN_PROGRESS are the gateway's,
+   * decided before this message is sent, and a connector must not claim them.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingErrorDetail error = 3;
+   */
+  error?: PairingErrorDetail | undefined;
+
+  /**
+   * When the window closes, if it opened. Lets the gateway expire its own record against the
+   * connector's clock rather than a guess — the connector is the party that clamped it.
+   *
+   * @generated from field: google.protobuf.Timestamp expires_at = 4;
+   */
+  expiresAt?: Timestamp | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.PairingModeResult.
+ * Use `create(PairingModeResultSchema)` to create a new message.
+ */
+export declare const PairingModeResultSchema: GenMessage<PairingModeResult>;
+
+/**
+ * What the window produced, connector → gateway, sent once when it closes.
+ *
+ * Without this the connector has no way to report anything it learned after the window
+ * opened: a device that joined and cannot be modelled, or one that joined and was not the
+ * device the hint named. Neither can travel on a DeviceAnnouncement — the first has nothing
+ * announceable, and the second is announced but unattributed, which says a device arrived
+ * and not why it was refused.
+ *
+ * It also gives a batch window a definite end. Counting announcements cannot distinguish
+ * "three of five so far" from "three of five, and that is all".
+ *
+ * @generated from message kusinta.iot.connector.v1.PairingModeEnded
+ */
+export declare type PairingModeEnded = Message<"kusinta.iot.connector.v1.PairingModeEnded"> & {
+  /**
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * How many arrivals this connector attributed to the request. The gateway can count the
+   * announcements it received, but only the connector knows it has stopped.
+   *
+   * @generated from field: uint32 devices_attributed = 2;
+   */
+  devicesAttributed: number;
+
+  /**
+   * Why it produced fewer than asked for, absent when it produced them all. DEVICE_UNUSABLE
+   * and WRONG_DEVICE are reported here and should name the device in the message, since that
+   * is the only place a user learns which device is now sitting on their hub.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingErrorDetail error = 3;
+   */
+  error?: PairingErrorDetail | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.PairingModeEnded.
+ * Use `create(PairingModeEndedSchema)` to create a new message.
+ */
+export declare const PairingModeEndedSchema: GenMessage<PairingModeEnded>;
+
 /**
  * @generated from message kusinta.iot.connector.v1.SessionRequest
  */
@@ -368,6 +509,18 @@ export declare type SessionRequest = Message<"kusinta.iot.connector.v1.SessionRe
      */
     value: DeviceEventBatch;
     case: "deviceEvents";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.connector.v1.PairingModeResult pairing_mode_result = 10;
+     */
+    value: PairingModeResult;
+    case: "pairingModeResult";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.connector.v1.PairingModeEnded pairing_mode_ended = 11;
+     */
+    value: PairingModeEnded;
+    case: "pairingModeEnded";
   } | { case: undefined; value?: undefined };
 };
 
@@ -433,6 +586,14 @@ export declare type SessionResponse = Message<"kusinta.iot.connector.v1.SessionR
      */
     value: AttributeWriteRequest;
     case: "executeAttributeWrite";
+  } | {
+    /**
+     * The connector-leg half of the pairing flow. See EnterPairingMode.
+     *
+     * @generated from field: kusinta.iot.connector.v1.EnterPairingMode enter_pairing_mode = 10;
+     */
+    value: EnterPairingMode;
+    case: "enterPairingMode";
   } | { case: undefined; value?: undefined };
 };
 

package/src/kusinta/iot/connector/v1/connector_pb.js

@@ -4,6 +4,7 @@
 
 import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
 import { file_google_protobuf_timestamp } from "@bufbuild/protobuf/wkt";
+import { file_kusinta_iot_common_v1_pairing } from "../../common/v1/pairing_pb.js";
 import { file_kusinta_iot_common_v1_types } from "../../common/v1/types_pb.js";
 import { file_kusinta_iot_device_v1_device } from "../../device/v1/device_pb.js";
 import { file_kusinta_iot_device_v1_device_event } from "../../device/v1/device_event_pb.js";
@@ -15,7 +16,7 @@ import { file_kusinta_iot_webrtc_v1_command } from "../../webrtc/v1/command_pb.j
  * Describes the file kusinta/iot/connector/v1/connector.proto.
  */
 export const file_kusinta_iot_connector_v1_connector = /*@__PURE__*/
-  fileDesc("CihrdXNpbnRhL2lvdC9jb25uZWN0b3IvdjEvY29ubmVjdG9yLnByb3RvEhhrdXNpbnRhLmlvdC5jb25uZWN0b3IudjEi5QEKDUNvbm5lY3RvckluZm8SOgoMY29ubmVjdG9yX2lkGAEgASgLMiQua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuQ29ubmVjdG9ySWQSFAoMZGlzcGxheV9uYW1lGAIgASgJEg8KB3ZlcnNpb24YAyABKAkSPAoJdHJhbnNwb3J0GAQgASgOMikua3VzaW50YS5pb3QuY29tbW9uLnYxLkNvbm5lY3RvclRyYW5zcG9ydBIQCghlbmRwb2ludBgFIAEoCRIhChlzdXBwb3J0ZWRfZGV2aWNlX3R5cGVfaWRzGAYgAygNIoEBChJDb25uZWN0b3JIYW5kc2hha2USNQoEaW5mbxgBIAEoCzInLmt1c2ludGEuaW90LmNvbm5lY3Rvci52MS5Db25uZWN0b3JJbmZvEjQKDWtub3duX2RldmljZXMYAiADKAsyHS5rdXNpbnRhLmlvdC5kZXZpY2UudjEuRGV2aWNlImgKDEhhbmRzaGFrZUFjaxIQCghhY2NlcHRlZBgBIAEoCBIOCgZyZWFzb24YAiABKAkSNgoKZ2F0ZXdheV9pZBgDIAEoCzIiLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkdhdGV3YXlJZCJVChJEZXZpY2VBbm5vdW5jZW1lbnQSLQoGZGV2aWNlGAIgASgLMh0ua3VzaW50YS5pb3QuZGV2aWNlLnYxLkRldmljZUoECAEQAlIKZGVzY3JpcHRvciJVCg1EZXZpY2VSZW1vdmFsEjQKCWRldmljZV9pZBgBIAEoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkEg4KBnJlYXNvbhgCIAEoCSILCglIZWFydEJlYXQiRwoPU3Vic2NyaWJlRGV2aWNlEjQKCWRldmljZV9pZBgBIAEoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkIkkKEVVuc3Vic2NyaWJlRGV2aWNlEjQKCWRldmljZV9pZBgBIAEoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkIkEKDEdhdGV3YXlFcnJvchIMCgRjb2RlGAEgASgJEg8KB21lc3NhZ2UYAiABKAkSEgoKcmVxdWVzdF9pZBgDIAEoCSLtAQoWQ29ubmVjdG9yQ29tbWFuZFJlc3VsdBISCgpyZXF1ZXN0X2lkGAEgASgJEg8KB3N1Y2Nlc3MYAiABKAgSMAoMY29tcGxldGVkX2F0GAQgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcBIyCgVlcnJvchgFIAEoCzIjLmt1c2ludGEuaW90LndlYnJ0Yy52MS5Db21tYW5kRXJyb3ISMwoKc2V0dGxlc19ieRgGIAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXBIAIgBAUINCgtfc2V0dGxlc19ieUoECAMQBCK7BAoOU2Vzc2lvblJlcXVlc3QSEgoKbWVzc2FnZV9pZBgBIAEoCRIrCgdzZW50X2F0GAIgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcBJBCgloYW5kc2hha2UYAyABKAsyLC5rdXNpbnRhLmlvdC5jb25uZWN0b3IudjEuQ29ubmVjdG9ySGFuZHNoYWtlSAASRQoPcHJvcGVydHlfdXBkYXRlGAQgASgLMioua3VzaW50YS5pb3QuZGV2aWNlLnYxLlByb3BlcnR5VXBkYXRlQmF0Y2hIABJIChBkZXZpY2VfYW5ub3VuY2VkGAUgASgLMiwua3VzaW50YS5pb3QuY29ubmVjdG9yLnYxLkRldmljZUFubm91bmNlbWVudEgAEkEKDmRldmljZV9yZW1vdmVkGAYgASgLMicua3VzaW50YS5pb3QuY29ubmVjdG9yLnYxLkRldmljZVJlbW92YWxIABJKCg5jb21tYW5kX3Jlc3VsdBgHIAEoCzIwLmt1c2ludGEuaW90LmNvbm5lY3Rvci52MS5Db25uZWN0b3JDb21tYW5kUmVzdWx0SAASOAoJaGVhcnRiZWF0GAggASgLMiMua3VzaW50YS5pb3QuY29ubmVjdG9yLnYxLkhlYXJ0QmVhdEgAEkAKDWRldmljZV9ldmVudHMYCSABKAsyJy5rdXNpbnRhLmlvdC5kZXZpY2UudjEuRGV2aWNlRXZlbnRCYXRjaEgAQgkKB3BheWxvYWQi8wMKD1Nlc3Npb25SZXNwb25zZRISCgptZXNzYWdlX2lkGAEgASgJEisKB3NlbnRfYXQYAiABKAsyGi5nb29nbGUucHJvdG9idWYuVGltZXN0YW1wEj8KDWhhbmRzaGFrZV9hY2sYAyABKAsyJi5rdXNpbnRhLmlvdC5jb25uZWN0b3IudjEuSGFuZHNoYWtlQWNrSAASPgoJc3Vic2NyaWJlGAUgASgLMikua3VzaW50YS5pb3QuY29ubmVjdG9yLnYxLlN1YnNjcmliZURldmljZUgAEkIKC3Vuc3Vic2NyaWJlGAYgASgLMisua3VzaW50YS5pb3QuY29ubmVjdG9yLnYxLlVuc3Vic2NyaWJlRGV2aWNlSAASNwoFZXJyb3IYByABKAsyJi5rdXNpbnRhLmlvdC5jb25uZWN0b3IudjEuR2F0ZXdheUVycm9ySAASPwoPZXhlY3V0ZV9jb21tYW5kGAggASgLMiQua3VzaW50YS5pb3Qud2VicnRjLnYxLkRldmljZUNvbW1hbmRIABJPChdleGVjdXRlX2F0dHJpYnV0ZV93cml0ZRgJIAEoCzIsLmt1c2ludGEuaW90LndlYnJ0Yy52MS5BdHRyaWJ1dGVXcml0ZVJlcXVlc3RIAEIJCgdwYXlsb2FkSgQIBBAFQgJIAWIGcHJvdG8z", [file_google_protobuf_timestamp, file_kusinta_iot_common_v1_types, file_kusinta_iot_device_v1_device, file_kusinta_iot_device_v1_device_event, file_kusinta_iot_device_v1_property_update, file_kusinta_iot_identity_v1_identity, file_kusinta_iot_webrtc_v1_command]);
+  fileDesc("CihrdXNpbnRhL2lvdC9jb25uZWN0b3IvdjEvY29ubmVjdG9yLnByb3RvEhhrdXNpbnRhLmlvdC5jb25uZWN0b3IudjEi5QEKDUNvbm5lY3RvckluZm8SOgoMY29ubmVjdG9yX2lkGAEgASgLMiQua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuQ29ubmVjdG9ySWQSFAoMZGlzcGxheV9uYW1lGAIgASgJEg8KB3ZlcnNpb24YAyABKAkSPAoJdHJhbnNwb3J0GAQgASgOMikua3VzaW50YS5pb3QuY29tbW9uLnYxLkNvbm5lY3RvclRyYW5zcG9ydBIQCghlbmRwb2ludBgFIAEoCRIhChlzdXBwb3J0ZWRfZGV2aWNlX3R5cGVfaWRzGAYgAygNIoEBChJDb25uZWN0b3JIYW5kc2hha2USNQoEaW5mbxgBIAEoCzInLmt1c2ludGEuaW90LmNvbm5lY3Rvci52MS5Db25uZWN0b3JJbmZvEjQKDWtub3duX2RldmljZXMYAiADKAsyHS5rdXNpbnRhLmlvdC5kZXZpY2UudjEuRGV2aWNlImgKDEhhbmRzaGFrZUFjaxIQCghhY2NlcHRlZBgBIAEoCBIOCgZyZWFzb24YAiABKAkSNgoKZ2F0ZXdheV9pZBgDIAEoCzIiLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkdhdGV3YXlJZCJxChJEZXZpY2VBbm5vdW5jZW1lbnQSLQoGZGV2aWNlGAIgASgLMh0ua3VzaW50YS5pb3QuZGV2aWNlLnYxLkRldmljZRIaChJwYWlyaW5nX3JlcXVlc3RfaWQYAyABKAlKBAgBEAJSCmRlc2NyaXB0b3IiVQoNRGV2aWNlUmVtb3ZhbBI0CglkZXZpY2VfaWQYASABKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZBIOCgZyZWFzb24YAiABKAkiCwoJSGVhcnRCZWF0IkcKD1N1YnNjcmliZURldmljZRI0CglkZXZpY2VfaWQYASABKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZCJJChFVbnN1YnNjcmliZURldmljZRI0CglkZXZpY2VfaWQYASABKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZCJBCgxHYXRld2F5RXJyb3ISDAoEY29kZRgBIAEoCRIPCgdtZXNzYWdlGAIgASgJEhIKCnJlcXVlc3RfaWQYAyABKAki7QEKFkNvbm5lY3RvckNvbW1hbmRSZXN1bHQSEgoKcmVxdWVzdF9pZBgBIAEoCRIPCgdzdWNjZXNzGAIgASgIEjAKDGNvbXBsZXRlZF9hdBgEIAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXASMgoFZXJyb3IYBSABKAsyIy5rdXNpbnRhLmlvdC53ZWJydGMudjEuQ29tbWFuZEVycm9yEjMKCnNldHRsZXNfYnkYBiABKAsyGi5nb29nbGUucHJvdG9idWYuVGltZXN0YW1wSACIAQFCDQoLX3NldHRsZXNfYnlKBAgDEAQiXAoQRW50ZXJQYWlyaW5nTW9kZRISCgpyZXF1ZXN0X2lkGAEgASgJEjQKBndpbmRvdxgCIAEoCzIkLmt1c2ludGEuaW90LmNvbW1vbi52MS5QYWlyaW5nV2luZG93IqMBChFQYWlyaW5nTW9kZVJlc3VsdBISCgpyZXF1ZXN0X2lkGAEgASgJEhAKCGFjY2VwdGVkGAIgASgIEjgKBWVycm9yGAMgASgLMikua3VzaW50YS5pb3QuY29tbW9uLnYxLlBhaXJpbmdFcnJvckRldGFpbBIuCgpleHBpcmVzX2F0GAQgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcCJ8ChBQYWlyaW5nTW9kZUVuZGVkEhIKCnJlcXVlc3RfaWQYASABKAkSGgoSZGV2aWNlc19hdHRyaWJ1dGVkGAIgASgNEjgKBWVycm9yGAMgASgLMikua3VzaW50YS5pb3QuY29tbW9uLnYxLlBhaXJpbmdFcnJvckRldGFpbCLRBQoOU2Vzc2lvblJlcXVlc3QSEgoKbWVzc2FnZV9pZBgBIAEoCRIrCgdzZW50X2F0GAIgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcBJBCgloYW5kc2hha2UYAyABKAsyLC5rdXNpbnRhLmlvdC5jb25uZWN0b3IudjEuQ29ubmVjdG9ySGFuZHNoYWtlSAASRQoPcHJvcGVydHlfdXBkYXRlGAQgASgLMioua3VzaW50YS5pb3QuZGV2aWNlLnYxLlByb3BlcnR5VXBkYXRlQmF0Y2hIABJIChBkZXZpY2VfYW5ub3VuY2VkGAUgASgLMiwua3VzaW50YS5pb3QuY29ubmVjdG9yLnYxLkRldmljZUFubm91bmNlbWVudEgAEkEKDmRldmljZV9yZW1vdmVkGAYgASgLMicua3VzaW50YS5pb3QuY29ubmVjdG9yLnYxLkRldmljZVJlbW92YWxIABJKCg5jb21tYW5kX3Jlc3VsdBgHIAEoCzIwLmt1c2ludGEuaW90LmNvbm5lY3Rvci52MS5Db25uZWN0b3JDb21tYW5kUmVzdWx0SAASOAoJaGVhcnRiZWF0GAggASgLMiMua3VzaW50YS5pb3QuY29ubmVjdG9yLnYxLkhlYXJ0QmVhdEgAEkAKDWRldmljZV9ldmVudHMYCSABKAsyJy5rdXNpbnRhLmlvdC5kZXZpY2UudjEuRGV2aWNlRXZlbnRCYXRjaEgAEkoKE3BhaXJpbmdfbW9kZV9yZXN1bHQYCiABKAsyKy5rdXNpbnRhLmlvdC5jb25uZWN0b3IudjEuUGFpcmluZ01vZGVSZXN1bHRIABJIChJwYWlyaW5nX21vZGVfZW5kZWQYCyABKAsyKi5rdXNpbnRhLmlvdC5jb25uZWN0b3IudjEuUGFpcmluZ01vZGVFbmRlZEgAQgkKB3BheWxvYWQivQQKD1Nlc3Npb25SZXNwb25zZRISCgptZXNzYWdlX2lkGAEgASgJEisKB3NlbnRfYXQYAiABKAsyGi5nb29nbGUucHJvdG9idWYuVGltZXN0YW1wEj8KDWhhbmRzaGFrZV9hY2sYAyABKAsyJi5rdXNpbnRhLmlvdC5jb25uZWN0b3IudjEuSGFuZHNoYWtlQWNrSAASPgoJc3Vic2NyaWJlGAUgASgLMikua3VzaW50YS5pb3QuY29ubmVjdG9yLnYxLlN1YnNjcmliZURldmljZUgAEkIKC3Vuc3Vic2NyaWJlGAYgASgLMisua3VzaW50YS5pb3QuY29ubmVjdG9yLnYxLlVuc3Vic2NyaWJlRGV2aWNlSAASNwoFZXJyb3IYByABKAsyJi5rdXNpbnRhLmlvdC5jb25uZWN0b3IudjEuR2F0ZXdheUVycm9ySAASPwoPZXhlY3V0ZV9jb21tYW5kGAggASgLMiQua3VzaW50YS5pb3Qud2VicnRjLnYxLkRldmljZUNvbW1hbmRIABJPChdleGVjdXRlX2F0dHJpYnV0ZV93cml0ZRgJIAEoCzIsLmt1c2ludGEuaW90LndlYnJ0Yy52MS5BdHRyaWJ1dGVXcml0ZVJlcXVlc3RIABJIChJlbnRlcl9wYWlyaW5nX21vZGUYCiABKAsyKi5rdXNpbnRhLmlvdC5jb25uZWN0b3IudjEuRW50ZXJQYWlyaW5nTW9kZUgAQgkKB3BheWxvYWRKBAgEEAVCAkgBYgZwcm90bzM", [file_google_protobuf_timestamp, file_kusinta_iot_common_v1_pairing, file_kusinta_iot_common_v1_types, file_kusinta_iot_device_v1_device, file_kusinta_iot_device_v1_device_event, file_kusinta_iot_device_v1_property_update, file_kusinta_iot_identity_v1_identity, file_kusinta_iot_webrtc_v1_command]);
 
 /**
  * Describes the message kusinta.iot.connector.v1.ConnectorInfo.
@@ -87,17 +88,38 @@ export const GatewayErrorSchema = /*@__PURE__*/
 export const ConnectorCommandResultSchema = /*@__PURE__*/
   messageDesc(file_kusinta_iot_connector_v1_connector, 9);
 
+/**
+ * Describes the message kusinta.iot.connector.v1.EnterPairingMode.
+ * Use `create(EnterPairingModeSchema)` to create a new message.
+ */
+export const EnterPairingModeSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_connector_v1_connector, 10);
+
+/**
+ * Describes the message kusinta.iot.connector.v1.PairingModeResult.
+ * Use `create(PairingModeResultSchema)` to create a new message.
+ */
+export const PairingModeResultSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_connector_v1_connector, 11);
+
+/**
+ * Describes the message kusinta.iot.connector.v1.PairingModeEnded.
+ * Use `create(PairingModeEndedSchema)` to create a new message.
+ */
+export const PairingModeEndedSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_connector_v1_connector, 12);
+
 /**
  * Describes the message kusinta.iot.connector.v1.SessionRequest.
  * Use `create(SessionRequestSchema)` to create a new message.
  */
 export const SessionRequestSchema = /*@__PURE__*/
-  messageDesc(file_kusinta_iot_connector_v1_connector, 10);
+  messageDesc(file_kusinta_iot_connector_v1_connector, 13);
 
 /**
  * Describes the message kusinta.iot.connector.v1.SessionResponse.
  * Use `create(SessionResponseSchema)` to create a new message.
  */
 export const SessionResponseSchema = /*@__PURE__*/
-  messageDesc(file_kusinta_iot_connector_v1_connector, 11);
+  messageDesc(file_kusinta_iot_connector_v1_connector, 14);
 

package/src/kusinta/iot/webrtc/v1/envelope_pb.d.ts

@@ -4,10 +4,12 @@
 
 import type { GenEnum, GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
 import type { Message } from "@bufbuild/protobuf";
-import type { DeviceId } from "../../identity/v1/identity_pb.js";
+import type { ConnectorId, DeviceId, SpaceId } from "../../identity/v1/identity_pb.js";
 import type { AttributeRef } from "../../access/v1/acl_pb.js";
 import type { Space } from "../../space/v1/space_pb.js";
 import type { ManagementAck, ManagementRequest, SpaceTree } from "./management_pb.js";
+import type { PairingErrorDetail, PairingWindow } from "../../common/v1/pairing_pb.js";
+import type { DeviceOwnershipType } from "../../common/v1/types_pb.js";
 import type { Timestamp } from "@bufbuild/protobuf/wkt";
 import type { DeviceAdded, DeviceRemoved, DeviceStateSnapshot, PropertyReport } from "./device_state_pb.js";
 import type { LivePermissionUpdate } from "./permission_push_pb.js";
@@ -325,6 +327,157 @@ export declare type ManagementResult = Message<"kusinta.iot.webrtc.v1.Management
  */
 export declare const ManagementResultSchema: GenMessage<ManagementResult>;
 
+/**
+ * Asks the gateway to put a connector into pairing mode, so a device joined during the
+ * window becomes the caller's rather than belonging to nobody.
+ *
+ * A payload case of its own rather than a ManagementRequest. Those are gated on a target —
+ * a space, a device — and that is the justification for keeping them behind one wrapper.
+ * This one names no target: connector_id is optional, and unset means every connector, so
+ * it is authorized against the caller's role and nothing else.
+ *
+ * Answered twice, and the two answers say different things at different times.
+ * PairingStarted reports whether the window opened; PairingFinished reports what came of
+ * it, seconds or minutes later, once someone has pressed a button on hardware that may be
+ * asleep or out of range.
+ *
+ * @generated from message kusinta.iot.webrtc.v1.StartPairing
+ */
+export declare type StartPairing = Message<"kusinta.iot.webrtc.v1.StartPairing"> & {
+  /**
+   * Which connector to open. Unset means every connector the gateway holds, which is the
+   * sensible default: a device picks its hub by radio range, and asking a user to choose is
+   * asking them to guess at something they cannot observe.
+   *
+   * Name one where the answer is not a guess — a device that will be linked to devices on a
+   * particular hub has to join that hub, because links are held by the hub that brokered
+   * them.
+   *
+   * @generated from field: kusinta.iot.identity.v1.ConnectorId connector_id = 1;
+   */
+  connectorId?: ConnectorId | undefined;
+
+  /**
+   * How long, which device, how many. See PairingWindow.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingWindow window = 2;
+   */
+  window?: PairingWindow | undefined;
+
+  /**
+   * Where to file the device once it arrives.
+   *
+   * Optional, and the two cases differ. A caller pairing a device of their own must name a
+   * space they reach, so it is theirs and placed on arrival rather than sitting unfiled and
+   * invisible to them. A caller commissioning for a building may leave it unset: a building
+   * is commissioned before its spaces are recorded, and an unfiled device is visible to the
+   * administrator, who is the person doing the pairing.
+   *
+   * @generated from field: kusinta.iot.identity.v1.SpaceId initial_space_id = 3;
+   */
+  initialSpaceId?: SpaceId | undefined;
+
+  /**
+   * What the device should become. Unset lets the gateway decide from the caller's role,
+   * which is the reading that scales: someone commissioning fifty devices for a building
+   * should not come to own fifty devices because a field defaulted.
+   *
+   * The gateway refuses an ownership the caller may not confer, and never mints ownership
+   * for a third party — handing a device to someone else is a transfer, a separate operation
+   * with its own authority.
+   *
+   * @generated from field: kusinta.iot.common.v1.DeviceOwnershipType ownership = 4;
+   */
+  ownership: DeviceOwnershipType;
+};
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.StartPairing.
+ * Use `create(StartPairingSchema)` to create a new message.
+ */
+export declare const StartPairingSchema: GenMessage<StartPairing>;
+
+/**
+ * Whether the pairing window opened, gateway → app. The first of two answers to a
+ * StartPairing.
+ *
+ * @generated from message kusinta.iot.webrtc.v1.PairingStarted
+ */
+export declare type PairingStarted = Message<"kusinta.iot.webrtc.v1.PairingStarted"> & {
+  /**
+   * AppMessage.message_id of the StartPairing
+   *
+   * @generated from field: string in_reply_to = 1;
+   */
+  inReplyTo: string;
+
+  /**
+   * When the window closes. Present when it opened, and this is the value to count down
+   * from — not the duration that was asked for, which both the gateway and the connector
+   * clamp. A countdown run on the request rather than on this one disagrees with the hub.
+   *
+   * @generated from field: google.protobuf.Timestamp expires_at = 2;
+   */
+  expiresAt?: Timestamp | undefined;
+
+  /**
+   * Why it did not open. Present instead of expires_at.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingErrorDetail error = 3;
+   */
+  error?: PairingErrorDetail | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.PairingStarted.
+ * Use `create(PairingStartedSchema)` to create a new message.
+ */
+export declare const PairingStartedSchema: GenMessage<PairingStarted>;
+
+/**
+ * What the pairing window produced, gateway → app. The second and last answer, sent once
+ * when the window closes.
+ *
+ * One message per request, not per device: a batch window attributes several, and a client
+ * given one message each has nothing telling it the window is over and no defined moment to
+ * stop waiting. The devices are listed here; each also arrives as an ordinary DeviceAdded
+ * as it appears, so a client may show them as they come and use this to finish.
+ *
+ * An error and a non-empty device list are not exclusive. A batch of five that attributed
+ * three and then expired reports both — three devices and NO_DEVICE_APPEARED — because
+ * "some worked" and "the window ran out" are both true and a user needs to be told both.
+ *
+ * @generated from message kusinta.iot.webrtc.v1.PairingFinished
+ */
+export declare type PairingFinished = Message<"kusinta.iot.webrtc.v1.PairingFinished"> & {
+  /**
+   * AppMessage.message_id of the StartPairing
+   *
+   * @generated from field: string in_reply_to = 1;
+   */
+  inReplyTo: string;
+
+  /**
+   * @generated from field: repeated kusinta.iot.identity.v1.DeviceId device_ids = 2;
+   */
+  deviceIds: DeviceId[];
+
+  /**
+   * Why the window produced fewer devices than asked for, absent when it produced them all.
+   * Note this is not always a failure of the request: a window that simply expired unused
+   * ends here too, and is the ordinary result of a user changing their mind.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingErrorDetail error = 3;
+   */
+  error?: PairingErrorDetail | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.PairingFinished.
+ * Use `create(PairingFinishedSchema)` to create a new message.
+ */
+export declare const PairingFinishedSchema: GenMessage<PairingFinished>;
+
 /**
  * GatewayMessage: gateway → app
  *
@@ -421,6 +574,18 @@ export declare type GatewayMessage = Message<"kusinta.iot.webrtc.v1.GatewayMessa
      */
     value: DeviceEventBatch;
     case: "deviceEvents";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.webrtc.v1.PairingStarted pairing_started = 17;
+     */
+    value: PairingStarted;
+    case: "pairingStarted";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.webrtc.v1.PairingFinished pairing_finished = 18;
+     */
+    value: PairingFinished;
+    case: "pairingFinished";
   } | { case: undefined; value?: undefined };
 };
 
@@ -497,6 +662,12 @@ export declare type AppMessage = Message<"kusinta.iot.webrtc.v1.AppMessage"> & {
      */
     value: AttributeWriteRequest;
     case: "attributeWrite";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.webrtc.v1.StartPairing start_pairing = 11;
+     */
+    value: StartPairing;
+    case: "startPairing";
   } | { case: undefined; value?: undefined };
 };
 

package/src/kusinta/iot/webrtc/v1/envelope_pb.js

@@ -5,6 +5,8 @@
 import { enumDesc, fileDesc, messageDesc, tsEnum } from "@bufbuild/protobuf/codegenv2";
 import { file_google_protobuf_timestamp } from "@bufbuild/protobuf/wkt";
 import { file_kusinta_iot_access_v1_acl } from "../../access/v1/acl_pb.js";
+import { file_kusinta_iot_common_v1_pairing } from "../../common/v1/pairing_pb.js";
+import { file_kusinta_iot_common_v1_types } from "../../common/v1/types_pb.js";
 import { file_kusinta_iot_device_v1_device_event } from "../../device/v1/device_event_pb.js";
 import { file_kusinta_iot_identity_v1_identity } from "../../identity/v1/identity_pb.js";
 import { file_kusinta_iot_space_v1_space } from "../../space/v1/space_pb.js";
@@ -17,7 +19,7 @@ import { file_kusinta_iot_webrtc_v1_permission_push } from "./permission_push_pb
  * Describes the file kusinta/iot/webrtc/v1/envelope.proto.
  */
 export const file_kusinta_iot_webrtc_v1_envelope = /*@__PURE__*/
-  fileDesc("CiRrdXNpbnRhL2lvdC93ZWJydGMvdjEvZW52ZWxvcGUucHJvdG8SFWt1c2ludGEuaW90LndlYnJ0Yy52MSIGCgRQaW5nIgYKBFBvbmciIwoRSGFuZHNoYWtlUmVqZWN0ZWQSDgoGcmVhc29uGAEgASgJIlwKDEFwcEhhbmRzaGFrZRILCgNqd3QYASABKAkSPwoUc3Vic2NyaWJlX2RldmljZV9pZHMYAiADKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZCJJChBTdWJzY3JpYmVEZXZpY2VzEjUKCmRldmljZV9pZHMYASADKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZCJLChJVbnN1YnNjcmliZURldmljZXMSNQoKZGV2aWNlX2lkcxgBIAMoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkIpMBChNSZWZ1c2VkU3Vic2NyaXB0aW9uEjQKCWRldmljZV9pZBgBIAEoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkEjUKBGNvZGUYAiABKA4yJy5rdXNpbnRhLmlvdC53ZWJydGMudjEuR2F0ZXdheUVycm9yQ29kZRIPCgdtZXNzYWdlGAMgASgJIpoBCg9TdWJzY3JpcHRpb25BY2sSEwoLaW5fcmVwbHlfdG8YASABKAkSNQoKc3Vic2NyaWJlZBgCIAMoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkEjsKB3JlZnVzZWQYAyADKAsyKi5rdXNpbnRhLmlvdC53ZWJydGMudjEuUmVmdXNlZFN1YnNjcmlwdGlvbiLRAQoTUHJvcGVydHlSZWFkUmVxdWVzdBI0CglkZXZpY2VfaWQYASABKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZBIzCgZ0YXJnZXQYByABKAsyIy5rdXNpbnRhLmlvdC5hY2Nlc3MudjEuQXR0cmlidXRlUmVmSgQIAhAHUg5hdHRyaWJ1dGVfbmFtZVIOY2x1c3Rlcl9pZF9oZXhSCmNsdXN0ZXJfaWRSC2VuZHBvaW50X2lkUhB2ZW5kb3JfZXh0ZW5zaW9uIswBCgxHYXRld2F5RXJyb3ISNQoEY29kZRgBIAEoDjInLmt1c2ludGEuaW90LndlYnJ0Yy52MS5HYXRld2F5RXJyb3JDb2RlEg8KB21lc3NhZ2UYAiABKAkSQwoIbWV0YWRhdGEYAyADKAsyMS5rdXNpbnRhLmlvdC53ZWJydGMudjEuR2F0ZXdheUVycm9yLk1ldGFkYXRhRW50cnkaLwoNTWV0YWRhdGFFbnRyeRILCgNrZXkYASABKAkSDQoFdmFsdWUYAiABKAk6AjgBIoICChBNYW5hZ2VtZW50UmVzdWx0EhMKC2luX3JlcGx5X3RvGAEgASgJEjQKBWVycm9yGAIgASgLMiMua3VzaW50YS5pb3Qud2VicnRjLnYxLkdhdGV3YXlFcnJvckgAEiwKBXNwYWNlGAMgASgLMhsua3VzaW50YS5pb3Quc3BhY2UudjEuU3BhY2VIABI2CgpzcGFjZV90cmVlGAQgASgLMiAua3VzaW50YS5pb3Qud2VicnRjLnYxLlNwYWNlVHJlZUgAEjMKA2FjaxgFIAEoCzIkLmt1c2ludGEuaW90LndlYnJ0Yy52MS5NYW5hZ2VtZW50QWNrSABCCAoGcmVzdWx0IpUHCg5HYXRld2F5TWVzc2FnZRISCgptZXNzYWdlX2lkGAEgASgJEisKB3NlbnRfYXQYAiABKAsyGi5nb29nbGUucHJvdG9idWYuVGltZXN0YW1wEkQKDnN0YXRlX3NuYXBzaG90GAMgASgLMioua3VzaW50YS5pb3Qud2VicnRjLnYxLkRldmljZVN0YXRlU25hcHNob3RIABJACg9wcm9wZXJ0eV9yZXBvcnQYBCABKAsyJS5rdXNpbnRhLmlvdC53ZWJydGMudjEuUHJvcGVydHlSZXBvcnRIABJIChFwZXJtaXNzaW9uX3VwZGF0ZRgFIAEoCzIrLmt1c2ludGEuaW90LndlYnJ0Yy52MS5MaXZlUGVybWlzc2lvblVwZGF0ZUgAEj4KDmNvbW1hbmRfcmVzdWx0GAYgASgLMiQua3VzaW50YS5pb3Qud2VicnRjLnYxLkNvbW1hbmRSZXN1bHRIABIrCgRwb25nGAggASgLMhsua3VzaW50YS5pb3Qud2VicnRjLnYxLlBvbmdIABJGChJoYW5kc2hha2VfcmVqZWN0ZWQYCSABKAsyKC5rdXNpbnRhLmlvdC53ZWJydGMudjEuSGFuZHNoYWtlUmVqZWN0ZWRIABI0CgVlcnJvchgKIAEoCzIjLmt1c2ludGEuaW90LndlYnJ0Yy52MS5HYXRld2F5RXJyb3JIABJCChBzdWJzY3JpcHRpb25fYWNrGAsgASgLMiYua3VzaW50YS5pb3Qud2VicnRjLnYxLlN1YnNjcmlwdGlvbkFja0gAEjoKDGRldmljZV9hZGRlZBgMIAEoCzIiLmt1c2ludGEuaW90LndlYnJ0Yy52MS5EZXZpY2VBZGRlZEgAEj4KDmRldmljZV9yZW1vdmVkGA0gASgLMiQua3VzaW50YS5pb3Qud2VicnRjLnYxLkRldmljZVJlbW92ZWRIABJEChFtYW5hZ2VtZW50X3Jlc3VsdBgOIAEoCzInLmt1c2ludGEuaW90LndlYnJ0Yy52MS5NYW5hZ2VtZW50UmVzdWx0SAASQAoNZGV2aWNlX2V2ZW50cxgQIAEoCzInLmt1c2ludGEuaW90LmRldmljZS52MS5EZXZpY2VFdmVudEJhdGNoSABCCQoHcGF5bG9hZEoECA8QEEoECAcQCFIWYXR0cmlidXRlX3dyaXRlX3Jlc3VsdFIOcHJvcGVydHlfZXZlbnQixQQKCkFwcE1lc3NhZ2USEgoKbWVzc2FnZV9pZBgBIAEoCRIrCgdzZW50X2F0GAIgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcBI4CgloYW5kc2hha2UYAyABKAsyIy5rdXNpbnRhLmlvdC53ZWJydGMudjEuQXBwSGFuZHNoYWtlSAASNwoHY29tbWFuZBgEIAEoCzIkLmt1c2ludGEuaW90LndlYnJ0Yy52MS5EZXZpY2VDb21tYW5kSAASQgoMcmVhZF9yZXF1ZXN0GAUgASgLMioua3VzaW50YS5pb3Qud2VicnRjLnYxLlByb3BlcnR5UmVhZFJlcXVlc3RIABIrCgRwaW5nGAYgASgLMhsua3VzaW50YS5pb3Qud2VicnRjLnYxLlBpbmdIABI8CglzdWJzY3JpYmUYByABKAsyJy5rdXNpbnRhLmlvdC53ZWJydGMudjEuU3Vic2NyaWJlRGV2aWNlc0gAEkAKC3Vuc3Vic2NyaWJlGAggASgLMikua3VzaW50YS5pb3Qud2VicnRjLnYxLlVuc3Vic2NyaWJlRGV2aWNlc0gAEj4KCm1hbmFnZW1lbnQYCSABKAsyKC5rdXNpbnRhLmlvdC53ZWJydGMudjEuTWFuYWdlbWVudFJlcXVlc3RIABJHCg9hdHRyaWJ1dGVfd3JpdGUYCiABKAsyLC5rdXNpbnRhLmlvdC53ZWJydGMudjEuQXR0cmlidXRlV3JpdGVSZXF1ZXN0SABCCQoHcGF5bG9hZCr2AQoQR2F0ZXdheUVycm9yQ29kZRIiCh5HQVRFV0FZX0VSUk9SX0NPREVfVU5TUEVDSUZJRUQQABIjCh9HQVRFV0FZX0VSUk9SX0NPREVfTk9UX0VOVElUTEVEEAESJgoiR0FURVdBWV9FUlJPUl9DT0RFX0lOVkFMSURfUkVRVUVTVBACEiIKHkdBVEVXQVlfRVJST1JfQ09ERV9VTkFWQUlMQUJMRRADEh8KG0dBVEVXQVlfRVJST1JfQ09ERV9JTlRFUk5BTBAEEiwKKEdBVEVXQVlfRVJST1JfQ09ERV9TRVNTSU9OX0xJTUlUX1JFQUNIRUQQBUICSAFiBnByb3RvMw", [file_google_protobuf_timestamp, file_kusinta_iot_access_v1_acl, file_kusinta_iot_device_v1_device_event, file_kusinta_iot_identity_v1_identity, file_kusinta_iot_space_v1_space, file_kusinta_iot_webrtc_v1_command, file_kusinta_iot_webrtc_v1_device_state, file_kusinta_iot_webrtc_v1_management, file_kusinta_iot_webrtc_v1_permission_push]);
+  fileDesc("CiRrdXNpbnRhL2lvdC93ZWJydGMvdjEvZW52ZWxvcGUucHJvdG8SFWt1c2ludGEuaW90LndlYnJ0Yy52MSIGCgRQaW5nIgYKBFBvbmciIwoRSGFuZHNoYWtlUmVqZWN0ZWQSDgoGcmVhc29uGAEgASgJIlwKDEFwcEhhbmRzaGFrZRILCgNqd3QYASABKAkSPwoUc3Vic2NyaWJlX2RldmljZV9pZHMYAiADKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZCJJChBTdWJzY3JpYmVEZXZpY2VzEjUKCmRldmljZV9pZHMYASADKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZCJLChJVbnN1YnNjcmliZURldmljZXMSNQoKZGV2aWNlX2lkcxgBIAMoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkIpMBChNSZWZ1c2VkU3Vic2NyaXB0aW9uEjQKCWRldmljZV9pZBgBIAEoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkEjUKBGNvZGUYAiABKA4yJy5rdXNpbnRhLmlvdC53ZWJydGMudjEuR2F0ZXdheUVycm9yQ29kZRIPCgdtZXNzYWdlGAMgASgJIpoBCg9TdWJzY3JpcHRpb25BY2sSEwoLaW5fcmVwbHlfdG8YASABKAkSNQoKc3Vic2NyaWJlZBgCIAMoCzIhLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLkRldmljZUlkEjsKB3JlZnVzZWQYAyADKAsyKi5rdXNpbnRhLmlvdC53ZWJydGMudjEuUmVmdXNlZFN1YnNjcmlwdGlvbiLRAQoTUHJvcGVydHlSZWFkUmVxdWVzdBI0CglkZXZpY2VfaWQYASABKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZBIzCgZ0YXJnZXQYByABKAsyIy5rdXNpbnRhLmlvdC5hY2Nlc3MudjEuQXR0cmlidXRlUmVmSgQIAhAHUg5hdHRyaWJ1dGVfbmFtZVIOY2x1c3Rlcl9pZF9oZXhSCmNsdXN0ZXJfaWRSC2VuZHBvaW50X2lkUhB2ZW5kb3JfZXh0ZW5zaW9uIswBCgxHYXRld2F5RXJyb3ISNQoEY29kZRgBIAEoDjInLmt1c2ludGEuaW90LndlYnJ0Yy52MS5HYXRld2F5RXJyb3JDb2RlEg8KB21lc3NhZ2UYAiABKAkSQwoIbWV0YWRhdGEYAyADKAsyMS5rdXNpbnRhLmlvdC53ZWJydGMudjEuR2F0ZXdheUVycm9yLk1ldGFkYXRhRW50cnkaLwoNTWV0YWRhdGFFbnRyeRILCgNrZXkYASABKAkSDQoFdmFsdWUYAiABKAk6AjgBIoICChBNYW5hZ2VtZW50UmVzdWx0EhMKC2luX3JlcGx5X3RvGAEgASgJEjQKBWVycm9yGAIgASgLMiMua3VzaW50YS5pb3Qud2VicnRjLnYxLkdhdGV3YXlFcnJvckgAEiwKBXNwYWNlGAMgASgLMhsua3VzaW50YS5pb3Quc3BhY2UudjEuU3BhY2VIABI2CgpzcGFjZV90cmVlGAQgASgLMiAua3VzaW50YS5pb3Qud2VicnRjLnYxLlNwYWNlVHJlZUgAEjMKA2FjaxgFIAEoCzIkLmt1c2ludGEuaW90LndlYnJ0Yy52MS5NYW5hZ2VtZW50QWNrSABCCAoGcmVzdWx0IvsBCgxTdGFydFBhaXJpbmcSOgoMY29ubmVjdG9yX2lkGAEgASgLMiQua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuQ29ubmVjdG9ySWQSNAoGd2luZG93GAIgASgLMiQua3VzaW50YS5pb3QuY29tbW9uLnYxLlBhaXJpbmdXaW5kb3cSOgoQaW5pdGlhbF9zcGFjZV9pZBgDIAEoCzIgLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLlNwYWNlSWQSPQoJb3duZXJzaGlwGAQgASgOMioua3VzaW50YS5pb3QuY29tbW9uLnYxLkRldmljZU93bmVyc2hpcFR5cGUijwEKDlBhaXJpbmdTdGFydGVkEhMKC2luX3JlcGx5X3RvGAEgASgJEi4KCmV4cGlyZXNfYXQYAiABKAsyGi5nb29nbGUucHJvdG9idWYuVGltZXN0YW1wEjgKBWVycm9yGAMgASgLMikua3VzaW50YS5pb3QuY29tbW9uLnYxLlBhaXJpbmdFcnJvckRldGFpbCKXAQoPUGFpcmluZ0ZpbmlzaGVkEhMKC2luX3JlcGx5X3RvGAEgASgJEjUKCmRldmljZV9pZHMYAiADKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZBI4CgVlcnJvchgDIAEoCzIpLmt1c2ludGEuaW90LmNvbW1vbi52MS5QYWlyaW5nRXJyb3JEZXRhaWwimwgKDkdhdGV3YXlNZXNzYWdlEhIKCm1lc3NhZ2VfaWQYASABKAkSKwoHc2VudF9hdBgCIAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXASRAoOc3RhdGVfc25hcHNob3QYAyABKAsyKi5rdXNpbnRhLmlvdC53ZWJydGMudjEuRGV2aWNlU3RhdGVTbmFwc2hvdEgAEkAKD3Byb3BlcnR5X3JlcG9ydBgEIAEoCzIlLmt1c2ludGEuaW90LndlYnJ0Yy52MS5Qcm9wZXJ0eVJlcG9ydEgAEkgKEXBlcm1pc3Npb25fdXBkYXRlGAUgASgLMisua3VzaW50YS5pb3Qud2VicnRjLnYxLkxpdmVQZXJtaXNzaW9uVXBkYXRlSAASPgoOY29tbWFuZF9yZXN1bHQYBiABKAsyJC5rdXNpbnRhLmlvdC53ZWJydGMudjEuQ29tbWFuZFJlc3VsdEgAEisKBHBvbmcYCCABKAsyGy5rdXNpbnRhLmlvdC53ZWJydGMudjEuUG9uZ0gAEkYKEmhhbmRzaGFrZV9yZWplY3RlZBgJIAEoCzIoLmt1c2ludGEuaW90LndlYnJ0Yy52MS5IYW5kc2hha2VSZWplY3RlZEgAEjQKBWVycm9yGAogASgLMiMua3VzaW50YS5pb3Qud2VicnRjLnYxLkdhdGV3YXlFcnJvckgAEkIKEHN1YnNjcmlwdGlvbl9hY2sYCyABKAsyJi5rdXNpbnRhLmlvdC53ZWJydGMudjEuU3Vic2NyaXB0aW9uQWNrSAASOgoMZGV2aWNlX2FkZGVkGAwgASgLMiIua3VzaW50YS5pb3Qud2VicnRjLnYxLkRldmljZUFkZGVkSAASPgoOZGV2aWNlX3JlbW92ZWQYDSABKAsyJC5rdXNpbnRhLmlvdC53ZWJydGMudjEuRGV2aWNlUmVtb3ZlZEgAEkQKEW1hbmFnZW1lbnRfcmVzdWx0GA4gASgLMicua3VzaW50YS5pb3Qud2VicnRjLnYxLk1hbmFnZW1lbnRSZXN1bHRIABJACg1kZXZpY2VfZXZlbnRzGBAgASgLMicua3VzaW50YS5pb3QuZGV2aWNlLnYxLkRldmljZUV2ZW50QmF0Y2hIABJACg9wYWlyaW5nX3N0YXJ0ZWQYESABKAsyJS5rdXNpbnRhLmlvdC53ZWJydGMudjEuUGFpcmluZ1N0YXJ0ZWRIABJCChBwYWlyaW5nX2ZpbmlzaGVkGBIgASgLMiYua3VzaW50YS5pb3Qud2VicnRjLnYxLlBhaXJpbmdGaW5pc2hlZEgAQgkKB3BheWxvYWRKBAgPEBBKBAgHEAhSFmF0dHJpYnV0ZV93cml0ZV9yZXN1bHRSDnByb3BlcnR5X2V2ZW50IoMFCgpBcHBNZXNzYWdlEhIKCm1lc3NhZ2VfaWQYASABKAkSKwoHc2VudF9hdBgCIAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXASOAoJaGFuZHNoYWtlGAMgASgLMiMua3VzaW50YS5pb3Qud2VicnRjLnYxLkFwcEhhbmRzaGFrZUgAEjcKB2NvbW1hbmQYBCABKAsyJC5rdXNpbnRhLmlvdC53ZWJydGMudjEuRGV2aWNlQ29tbWFuZEgAEkIKDHJlYWRfcmVxdWVzdBgFIAEoCzIqLmt1c2ludGEuaW90LndlYnJ0Yy52MS5Qcm9wZXJ0eVJlYWRSZXF1ZXN0SAASKwoEcGluZxgGIAEoCzIbLmt1c2ludGEuaW90LndlYnJ0Yy52MS5QaW5nSAASPAoJc3Vic2NyaWJlGAcgASgLMicua3VzaW50YS5pb3Qud2VicnRjLnYxLlN1YnNjcmliZURldmljZXNIABJACgt1bnN1YnNjcmliZRgIIAEoCzIpLmt1c2ludGEuaW90LndlYnJ0Yy52MS5VbnN1YnNjcmliZURldmljZXNIABI+CgptYW5hZ2VtZW50GAkgASgLMigua3VzaW50YS5pb3Qud2VicnRjLnYxLk1hbmFnZW1lbnRSZXF1ZXN0SAASRwoPYXR0cmlidXRlX3dyaXRlGAogASgLMiwua3VzaW50YS5pb3Qud2VicnRjLnYxLkF0dHJpYnV0ZVdyaXRlUmVxdWVzdEgAEjwKDXN0YXJ0X3BhaXJpbmcYCyABKAsyIy5rdXNpbnRhLmlvdC53ZWJydGMudjEuU3RhcnRQYWlyaW5nSABCCQoHcGF5bG9hZCr2AQoQR2F0ZXdheUVycm9yQ29kZRIiCh5HQVRFV0FZX0VSUk9SX0NPREVfVU5TUEVDSUZJRUQQABIjCh9HQVRFV0FZX0VSUk9SX0NPREVfTk9UX0VOVElUTEVEEAESJgoiR0FURVdBWV9FUlJPUl9DT0RFX0lOVkFMSURfUkVRVUVTVBACEiIKHkdBVEVXQVlfRVJST1JfQ09ERV9VTkFWQUlMQUJMRRADEh8KG0dBVEVXQVlfRVJST1JfQ09ERV9JTlRFUk5BTBAEEiwKKEdBVEVXQVlfRVJST1JfQ09ERV9TRVNTSU9OX0xJTUlUX1JFQUNIRUQQBUICSAFiBnByb3RvMw", [file_google_protobuf_timestamp, file_kusinta_iot_access_v1_acl, file_kusinta_iot_common_v1_pairing, file_kusinta_iot_common_v1_types, file_kusinta_iot_device_v1_device_event, file_kusinta_iot_identity_v1_identity, file_kusinta_iot_space_v1_space, file_kusinta_iot_webrtc_v1_command, file_kusinta_iot_webrtc_v1_device_state, file_kusinta_iot_webrtc_v1_management, file_kusinta_iot_webrtc_v1_permission_push]);
 
 /**
  * Describes the message kusinta.iot.webrtc.v1.Ping.
@@ -96,19 +98,40 @@ export const GatewayErrorSchema = /*@__PURE__*/
 export const ManagementResultSchema = /*@__PURE__*/
   messageDesc(file_kusinta_iot_webrtc_v1_envelope, 10);
 
+/**
+ * Describes the message kusinta.iot.webrtc.v1.StartPairing.
+ * Use `create(StartPairingSchema)` to create a new message.
+ */
+export const StartPairingSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_webrtc_v1_envelope, 11);
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.PairingStarted.
+ * Use `create(PairingStartedSchema)` to create a new message.
+ */
+export const PairingStartedSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_webrtc_v1_envelope, 12);
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.PairingFinished.
+ * Use `create(PairingFinishedSchema)` to create a new message.
+ */
+export const PairingFinishedSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_webrtc_v1_envelope, 13);
+
 /**
  * Describes the message kusinta.iot.webrtc.v1.GatewayMessage.
  * Use `create(GatewayMessageSchema)` to create a new message.
  */
 export const GatewayMessageSchema = /*@__PURE__*/
-  messageDesc(file_kusinta_iot_webrtc_v1_envelope, 11);
+  messageDesc(file_kusinta_iot_webrtc_v1_envelope, 14);
 
 /**
  * Describes the message kusinta.iot.webrtc.v1.AppMessage.
  * Use `create(AppMessageSchema)` to create a new message.
  */
 export const AppMessageSchema = /*@__PURE__*/
-  messageDesc(file_kusinta_iot_webrtc_v1_envelope, 12);
+  messageDesc(file_kusinta_iot_webrtc_v1_envelope, 15);
 
 /**
  * Describes the enum kusinta.iot.webrtc.v1.GatewayErrorCode.

package/src/kusinta/iot/webrtc/v1/management_pb.d.ts

@@ -265,8 +265,18 @@ export declare type ClaimDevice = Message<"kusinta.iot.webrtc.v1.ClaimDevice"> &
   initialSpaceId?: SpaceId | undefined;
 
   /**
-   * Evidence the claimant is standing at the device: the serial printed on it,
-   * matched against DeviceDescriptor.serial_number. Required precisely when the
+   * Evidence the claimant is standing at the device: the identifier printed on it,
+   * matched against DeviceDescriptor.serial_number.
+   *
+   * The match is by SUFFIX, because what a connector announces is not always the whole
+   * of what is printed and the announced value is commonly the tail of the printed one.
+   * Both sides are normalised first — lowercased, with whitespace and ASCII hyphens
+   * removed, since a label prints the value in groups and a scan does not — and the proof
+   * is accepted when what remains ends with the announced serial. Spelled out because two
+   * gateways normalising differently would accept different proofs for the same device.
+   *
+   * A serial shorter than eight characters cannot be proved at all: under a suffix rule a
+   * short one is proved by almost anything ending with it. Required precisely when the
    * caller cannot already reach the device, which is the ordinary case for a
    * resident claiming something they just bought — an unfiled device is invisible
    * to them, so possession is the only thing left that can distinguish them from