@kusinta/iot-schema 0.2.0-beta.1 → 0.2.0-beta.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kusinta/iot-schema",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.10",
   "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",
@@ -23,11 +24,16 @@
     "./space":                  "./src/kusinta/iot/space/v1/space_pb.js",
     "./access":                 "./src/kusinta/iot/access/v1/acl_pb.js",
     "./access/roles":           "./src/kusinta/iot/access/v1/roles_pb.js",
+    "./link":                   "./src/kusinta/iot/link/v1/link_pb.js",
     "./connector":              "./src/kusinta/iot/connector/v1/connector_pb.js",
     "./connector/service":      "./src/kusinta/iot/connector/v1/connector_service_pb.js",
     "./webrtc":                 "./src/kusinta/iot/webrtc/v1/envelope_pb.js",
     "./webrtc/app-token":       "./src/kusinta/iot/webrtc/v1/app_token_pb.js",
+    "./webrtc/command":         "./src/kusinta/iot/webrtc/v1/command_pb.js",
+    "./webrtc/device-state":    "./src/kusinta/iot/webrtc/v1/device_state_pb.js",
     "./webrtc/management":      "./src/kusinta/iot/webrtc/v1/management_pb.js",
+    "./webrtc/permission-push": "./src/kusinta/iot/webrtc/v1/permission_push_pb.js",
+    "./webrtc/setpoint-mode":   "./src/kusinta/iot/webrtc/v1/setpoint_mode_pb.js",
     "./registration":           "./src/kusinta/iot/registration/v1/registration_pb.js",
     "./registration/service":   "./src/kusinta/iot/registration/v1/registration_service_pb.js",
     "./signaling":              "./src/kusinta/iot/signaling/v1/signaling_pb.js",

package/src/kusinta/iot/access/v1/acl_pb.d.ts

@@ -86,6 +86,77 @@ export declare type AttributeRef = Message<"kusinta.iot.access.v1.AttributeRef">
  */
 export declare const AttributeRefSchema: GenMessage<AttributeRef>;
 
+/**
+ * CommandRef names one command on one endpoint, for DeviceAcl.allowed_command_refs.
+ *
+ * A separate type from AttributeRef because attributes and commands are numbered
+ * independently within a cluster: On/Off (0x0006) has an attribute 0x0000 (OnOff) and a
+ * command 0x0000 (Off) that have nothing to do with each other. Putting a command ID in a
+ * field named attribute_id would be the same class of ambiguity this schema removed when
+ * it made addressing numeric.
+ *
+ * @generated from message kusinta.iot.access.v1.CommandRef
+ */
+export declare type CommandRef = Message<"kusinta.iot.access.v1.CommandRef"> & {
+  /**
+   * @generated from field: uint32 cluster_id = 1;
+   */
+  clusterId: number;
+
+  /**
+   * @generated from field: uint32 matter_command_id = 2;
+   */
+  matterCommandId: number;
+
+  /**
+   * Which endpoint. Required on a grant, for the same reason as AttributeRef.endpoint_id:
+   * all four channels of a 4-channel actuator accept the same command on the same cluster,
+   * so a ref without one cannot tell channel 1 from channel 3.
+   *
+   * @generated from field: optional uint32 endpoint_id = 3;
+   */
+  endpointId?: number | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.access.v1.CommandRef.
+ * Use `create(CommandRefSchema)` to create a new message.
+ */
+export declare const CommandRefSchema: GenMessage<CommandRef>;
+
+/**
+ * EventRef names one event on one endpoint, for DeviceAcl.allowed_event_refs.
+ *
+ * Events are numbered independently of attributes and commands within a cluster, so this
+ * is a third type rather than a reuse. On Door Lock (0x0101), the LockState attribute and
+ * the lock-operation event are different elements answering different questions: what the
+ * lock's state is, and who changed it.
+ *
+ * @generated from message kusinta.iot.access.v1.EventRef
+ */
+export declare type EventRef = Message<"kusinta.iot.access.v1.EventRef"> & {
+  /**
+   * @generated from field: uint32 cluster_id = 1;
+   */
+  clusterId: number;
+
+  /**
+   * @generated from field: uint32 event_id = 2;
+   */
+  eventId: number;
+
+  /**
+   * @generated from field: optional uint32 endpoint_id = 3;
+   */
+  endpointId?: number | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.access.v1.EventRef.
+ * Use `create(EventRefSchema)` to create a new message.
+ */
+export declare const EventRefSchema: GenMessage<EventRef>;
+
 /**
  * PropertyConstraint bounds a single Matter cluster attribute.
  * MaxHeatSetpointLimit and MinHeatSetpointLimit are actual Matter Thermostat cluster
@@ -155,6 +226,14 @@ export declare type DeviceAcl = Message<"kusinta.iot.access.v1.DeviceAcl"> & {
   userId?: UserId | undefined;
 
   /**
+   * The user's role AS RESOLVED FOR THIS DEVICE. A gateway-wide role is a ceiling on the
+   * kinds of action a user may perform; reach — which devices — is decided separately by
+   * filing. This field is what the two produced together for this one device, so it may
+   * differ from any single role the user's token carries. See roles.proto.
+   *
+   * Descriptive. allowed_actions and the ref lists below are what a consumer enforces
+   * against; this says which relationship produced them.
+   *
    * @generated from field: kusinta.iot.access.v1.Role role = 3;
    */
   role: Role;
@@ -192,6 +271,39 @@ export declare type DeviceAcl = Message<"kusinta.iot.access.v1.DeviceAcl"> & {
    * @generated from field: repeated kusinta.iot.access.v1.PropertyConstraint property_constraints = 6;
    */
   propertyConstraints: PropertyConstraint[];
+
+  /**
+   * Narrows PERMISSION_ACTION_INVOKE to particular commands. Empty = every command the
+   * device accepts, matching allowed_attribute_refs — it is a filter, and an empty filter
+   * narrows nothing. It grants nothing on its own: without INVOKE in allowed_actions, no
+   * command is permitted however this list reads.
+   *
+   * Without it INVOKE is all-or-nothing, and that is the operation that moves hardware —
+   * a grant covering a thermostat setpoint would equally cover UnlockDoor on a device
+   * exposing both.
+   *
+   * A ref present with no endpoint_id is INVALID and MUST be rejected.
+   *
+   * @generated from field: repeated kusinta.iot.access.v1.CommandRef allowed_command_refs = 9;
+   */
+  allowedCommandRefs: CommandRef[];
+
+  /**
+   * Which events this user may receive. Empty = NONE.
+   *
+   * The opposite default to the two lists above, deliberately. Attributes and commands are
+   * a device's operating surface; events are its journal, and a journal discloses who did
+   * what and when. Reaching that must be an explicit grant, never something a user gets by
+   * holding SUBSCRIBE for ordinary readings.
+   *
+   * Requires PERMISSION_ACTION_SUBSCRIBE as well: the action says a standing stream is
+   * permitted, this list says which events travel on it.
+   *
+   * A ref present with no endpoint_id is INVALID and MUST be rejected.
+   *
+   * @generated from field: repeated kusinta.iot.access.v1.EventRef allowed_event_refs = 10;
+   */
+  allowedEventRefs: EventRef[];
 };
 
 /**
@@ -201,6 +313,24 @@ export declare type DeviceAcl = Message<"kusinta.iot.access.v1.DeviceAcl"> & {
 export declare const DeviceAclSchema: GenMessage<DeviceAcl>;
 
 /**
+ * Every DeviceAcl in force for one user on one gateway, at valid_at.
+ *
+ * ADVISORY WHEN SENT TO AN APP. The gateway is the sole authority and enforces every
+ * read, write, invoke and subscription against its own copy, whether or not the app has
+ * one. This is disclosed so an app can RENDER honestly — grey out a control the user may
+ * not invoke, clamp a setpoint slider to a PropertyConstraint, hide a device — instead of
+ * offering an action and discovering the refusal.
+ *
+ * Two mistakes this exists to prevent. An app MUST still handle refusal: this snapshot can
+ * be stale, and it is not a promise. A gateway MUST NOT treat having sent it as having
+ * enforced anything.
+ *
+ * It discloses only the recipient's own permissions. It says nothing about what any other
+ * user holds.
+ *
+ * Sent whole rather than as a delta, in webrtc.v1.DeviceStateSnapshot at connect and in
+ * webrtc.v1.LivePermissionUpdate when it changes.
+ *
  * @generated from message kusinta.iot.access.v1.EffectivePermissions
  */
 export declare type EffectivePermissions = Message<"kusinta.iot.access.v1.EffectivePermissions"> & {

package/src/kusinta/iot/access/v1/acl_pb.js

@@ -4,14 +4,14 @@
 
 import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
 import { file_google_protobuf_timestamp } from "@bufbuild/protobuf/wkt";
-import { file_kusinta_iot_identity_v1_identity } from "../../identity/v1/identity_pb.js";
 import { file_kusinta_iot_access_v1_roles } from "./roles_pb.js";
+import { file_kusinta_iot_identity_v1_identity } from "../../identity/v1/identity_pb.js";
 
 /**
  * Describes the file kusinta/iot/access/v1/acl.proto.
  */
 export const file_kusinta_iot_access_v1_acl = /*@__PURE__*/
-  fileDesc("Ch9rdXNpbnRhL2lvdC9hY2Nlc3MvdjEvYWNsLnByb3RvEhVrdXNpbnRhLmlvdC5hY2Nlc3MudjEirgEKDEF0dHJpYnV0ZVJlZhIWCg5hdHRyaWJ1dGVfbmFtZRgBIAEoCRISCgpjbHVzdGVyX2lkGAIgASgNEhQKDGF0dHJpYnV0ZV9pZBgEIAEoDRIYCgtlbmRwb2ludF9pZBgDIAEoDUgAiAEBEh0KEHZlbmRvcl9leHRlbnNpb24YBSABKAlIAYgBAUIOCgxfZW5kcG9pbnRfaWRCEwoRX3ZlbmRvcl9leHRlbnNpb24i5wEKElByb3BlcnR5Q29uc3RyYWludBI2CglhdHRyaWJ1dGUYCCABKAsyIy5rdXNpbnRhLmlvdC5hY2Nlc3MudjEuQXR0cmlidXRlUmVmEhEKB2ludF9tYXgYAiABKBFIABIRCgdpbnRfbWluGAMgASgRSAASEgoIdWludF9tYXgYBCABKA1IABISCgh1aW50X21pbhgFIAEoDUgAQgwKCmNvbnN0cmFpbnRKBAgBEAJKBAgGEAdKBAgHEAhSDmF0dHJpYnV0ZV9uYW1lUg5jbHVzdGVyX2lkX2hleFILZW5kcG9pbnRfaWQiiAMKCURldmljZUFjbBI0CglkZXZpY2VfaWQYASABKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZBIwCgd1c2VyX2lkGAIgASgLMh8ua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuVXNlcklkEikKBHJvbGUYAyABKA4yGy5rdXNpbnRhLmlvdC5hY2Nlc3MudjEuUm9sZRJACg9hbGxvd2VkX2FjdGlvbnMYBCADKA4yJy5rdXNpbnRhLmlvdC5hY2Nlc3MudjEuUGVybWlzc2lvbkFjdGlvbhJDChZhbGxvd2VkX2F0dHJpYnV0ZV9yZWZzGAcgAygLMiMua3VzaW50YS5pb3QuYWNjZXNzLnYxLkF0dHJpYnV0ZVJlZhJHChRwcm9wZXJ0eV9jb25zdHJhaW50cxgGIAMoCzIpLmt1c2ludGEuaW90LmFjY2Vzcy52MS5Qcm9wZXJ0eUNvbnN0cmFpbnRKBAgFEAZSEmFsbG93ZWRfYXR0cmlidXRlcyLlAQoURWZmZWN0aXZlUGVybWlzc2lvbnMSMAoHdXNlcl9pZBgBIAEoCzIfLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLlVzZXJJZBI2CgpnYXRld2F5X2lkGAIgASgLMiIua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuR2F0ZXdheUlkEjUKC2RldmljZV9hY2xzGAMgAygLMiAua3VzaW50YS5pb3QuYWNjZXNzLnYxLkRldmljZUFjbBIsCgh2YWxpZF9hdBgEIAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXBCAkgBYgZwcm90bzM", [file_google_protobuf_timestamp, file_kusinta_iot_identity_v1_identity, file_kusinta_iot_access_v1_roles]);
+  fileDesc("Ch9rdXNpbnRhL2lvdC9hY2Nlc3MvdjEvYWNsLnByb3RvEhVrdXNpbnRhLmlvdC5hY2Nlc3MudjEirgEKDEF0dHJpYnV0ZVJlZhIWCg5hdHRyaWJ1dGVfbmFtZRgBIAEoCRISCgpjbHVzdGVyX2lkGAIgASgNEhQKDGF0dHJpYnV0ZV9pZBgEIAEoDRIYCgtlbmRwb2ludF9pZBgDIAEoDUgAiAEBEh0KEHZlbmRvcl9leHRlbnNpb24YBSABKAlIAYgBAUIOCgxfZW5kcG9pbnRfaWRCEwoRX3ZlbmRvcl9leHRlbnNpb24iZQoKQ29tbWFuZFJlZhISCgpjbHVzdGVyX2lkGAEgASgNEhkKEW1hdHRlcl9jb21tYW5kX2lkGAIgASgNEhgKC2VuZHBvaW50X2lkGAMgASgNSACIAQFCDgoMX2VuZHBvaW50X2lkIloKCEV2ZW50UmVmEhIKCmNsdXN0ZXJfaWQYASABKA0SEAoIZXZlbnRfaWQYAiABKA0SGAoLZW5kcG9pbnRfaWQYAyABKA1IAIgBAUIOCgxfZW5kcG9pbnRfaWQi5wEKElByb3BlcnR5Q29uc3RyYWludBI2CglhdHRyaWJ1dGUYCCABKAsyIy5rdXNpbnRhLmlvdC5hY2Nlc3MudjEuQXR0cmlidXRlUmVmEhEKB2ludF9tYXgYAiABKBFIABIRCgdpbnRfbWluGAMgASgRSAASEgoIdWludF9tYXgYBCABKA1IABISCgh1aW50X21pbhgFIAEoDUgAQgwKCmNvbnN0cmFpbnRKBAgBEAJKBAgGEAdKBAgHEAhSDmF0dHJpYnV0ZV9uYW1lUg5jbHVzdGVyX2lkX2hleFILZW5kcG9pbnRfaWQihgQKCURldmljZUFjbBI0CglkZXZpY2VfaWQYASABKAsyIS5rdXNpbnRhLmlvdC5pZGVudGl0eS52MS5EZXZpY2VJZBIwCgd1c2VyX2lkGAIgASgLMh8ua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuVXNlcklkEikKBHJvbGUYAyABKA4yGy5rdXNpbnRhLmlvdC5hY2Nlc3MudjEuUm9sZRJACg9hbGxvd2VkX2FjdGlvbnMYBCADKA4yJy5rdXNpbnRhLmlvdC5hY2Nlc3MudjEuUGVybWlzc2lvbkFjdGlvbhJDChZhbGxvd2VkX2F0dHJpYnV0ZV9yZWZzGAcgAygLMiMua3VzaW50YS5pb3QuYWNjZXNzLnYxLkF0dHJpYnV0ZVJlZhJHChRwcm9wZXJ0eV9jb25zdHJhaW50cxgGIAMoCzIpLmt1c2ludGEuaW90LmFjY2Vzcy52MS5Qcm9wZXJ0eUNvbnN0cmFpbnQSPwoUYWxsb3dlZF9jb21tYW5kX3JlZnMYCSADKAsyIS5rdXNpbnRhLmlvdC5hY2Nlc3MudjEuQ29tbWFuZFJlZhI7ChJhbGxvd2VkX2V2ZW50X3JlZnMYCiADKAsyHy5rdXNpbnRhLmlvdC5hY2Nlc3MudjEuRXZlbnRSZWZKBAgFEAZSEmFsbG93ZWRfYXR0cmlidXRlcyLlAQoURWZmZWN0aXZlUGVybWlzc2lvbnMSMAoHdXNlcl9pZBgBIAEoCzIfLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLlVzZXJJZBI2CgpnYXRld2F5X2lkGAIgASgLMiIua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuR2F0ZXdheUlkEjUKC2RldmljZV9hY2xzGAMgAygLMiAua3VzaW50YS5pb3QuYWNjZXNzLnYxLkRldmljZUFjbBIsCgh2YWxpZF9hdBgEIAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXBCAkgBYgZwcm90bzM", [file_google_protobuf_timestamp, file_kusinta_iot_access_v1_roles, file_kusinta_iot_identity_v1_identity]);
 
 /**
  * Describes the message kusinta.iot.access.v1.AttributeRef.
@@ -20,24 +20,38 @@ export const file_kusinta_iot_access_v1_acl = /*@__PURE__*/
 export const AttributeRefSchema = /*@__PURE__*/
   messageDesc(file_kusinta_iot_access_v1_acl, 0);
 
+/**
+ * Describes the message kusinta.iot.access.v1.CommandRef.
+ * Use `create(CommandRefSchema)` to create a new message.
+ */
+export const CommandRefSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_access_v1_acl, 1);
+
+/**
+ * Describes the message kusinta.iot.access.v1.EventRef.
+ * Use `create(EventRefSchema)` to create a new message.
+ */
+export const EventRefSchema = /*@__PURE__*/
+  messageDesc(file_kusinta_iot_access_v1_acl, 2);
+
 /**
  * Describes the message kusinta.iot.access.v1.PropertyConstraint.
  * Use `create(PropertyConstraintSchema)` to create a new message.
  */
 export const PropertyConstraintSchema = /*@__PURE__*/
-  messageDesc(file_kusinta_iot_access_v1_acl, 1);
+  messageDesc(file_kusinta_iot_access_v1_acl, 3);
 
 /**
  * Describes the message kusinta.iot.access.v1.DeviceAcl.
  * Use `create(DeviceAclSchema)` to create a new message.
  */
 export const DeviceAclSchema = /*@__PURE__*/
-  messageDesc(file_kusinta_iot_access_v1_acl, 2);
+  messageDesc(file_kusinta_iot_access_v1_acl, 4);
 
 /**
  * Describes the message kusinta.iot.access.v1.EffectivePermissions.
  * Use `create(EffectivePermissionsSchema)` to create a new message.
  */
 export const EffectivePermissionsSchema = /*@__PURE__*/
-  messageDesc(file_kusinta_iot_access_v1_acl, 3);
+  messageDesc(file_kusinta_iot_access_v1_acl, 5);
 

package/src/kusinta/iot/access/v1/roles_pb.d.ts

@@ -10,6 +10,32 @@ import type { GenEnum, GenFile } from "@bufbuild/protobuf/codegenv2";
 export declare const file_kusinta_iot_access_v1_roles: GenFile;
 
 /**
+ * What kind of party a user is, gateway-wide.
+ *
+ * A role is a CEILING on the kinds of action a user may perform anywhere on this gateway.
+ * It is not reach: it says nothing about WHICH devices the user may act on. Reach is
+ * decided by filing — which spaces the user holds, and which devices are in them — and
+ * the two are independent. A role must never be read as reach, and reach must never be
+ * read as permission to act.
+ *
+ * The gateway resolves the two together into DeviceAcl.allowed_actions, per device. A
+ * role narrows what may appear there; it does not put anything there on its own.
+ *
+ * Carried in the app's token as webrtc.v1.AppTokenClaims.roles, as an array of proto3
+ * canonical enum NAME strings (e.g. ["ROLE_RESIDENT", "ROLE_GATEWAY_ADMIN"]) rather than
+ * integers, so the claim stays self-describing. A user may hold several at once and the
+ * effective ceiling is their union.
+ *
+ * UNORDERED. These are categories, not levels: a technician is not "more than" a
+ * resident, and there is no >= comparison to make between them. Anything needing a graded
+ * comparison — Matter's View/Operate/Manage/Administer, say — would be a separate concept
+ * and is deliberately not modelled here.
+ *
+ * A role is a ceiling rather than a floor, so it may be WIDENED per device by facts the
+ * role does not know: a user who owns a device may hold actions on it that their
+ * gateway-wide role alone would not grant. That widening is the gateway's to apply and is
+ * visible to the app only in the resolved DeviceAcl.
+ *
  * @generated from enum kusinta.iot.access.v1.Role
  */
 export enum Role {
@@ -19,21 +45,31 @@ export enum Role {
   UNSPECIFIED = 0,
 
   /**
+   * Lives with the devices. Operates what is in the spaces they hold.
+   *
    * @generated from enum value: ROLE_RESIDENT = 1;
    */
   RESIDENT = 1,
 
   /**
+   * Owns the property the devices are installed in. Sets the bounds residents operate
+   * within — see PropertyConstraint in acl.proto.
+   *
    * @generated from enum value: ROLE_PROPERTY_OWNER = 2;
    */
   PROPERTY_OWNER = 2,
 
   /**
+   * Installs and services devices. Present for the work, not for the tenancy.
+   *
    * @generated from enum value: ROLE_TECHNICIAN = 3;
    */
   TECHNICIAN = 3,
 
   /**
+   * Administers this gateway itself. The one role that also affects reach: some devices
+   * are visible only to a session holding it.
+   *
    * @generated from enum value: ROLE_GATEWAY_ADMIN = 4;
    */
   GATEWAY_ADMIN = 4,
@@ -49,6 +85,12 @@ export declare const RoleSchema: GenEnum<Role>;
  * names an operation that exists on the app leg, so a grant can be checked against the
  * message that arrived.
  *
+ * The action says HOW data is reached. WHICH elements it reaches is a separate question,
+ * answered by the ref lists on DeviceAcl — allowed_attribute_refs, allowed_command_refs
+ * and allowed_event_refs. Keeping the two apart is deliberate: attributes, commands and
+ * events are addressed by three different ID spaces, and folding "which kind of element"
+ * into the action verb would make the action mean two things at once.
+ *
  * @generated from enum kusinta.iot.access.v1.PermissionAction
  */
 export enum PermissionAction {
@@ -64,37 +106,61 @@ export enum PermissionAction {
   UNSPECIFIED = 0,
 
   /**
-   * Read an attribute once, on demand: webrtc.v1.PropertyReadRequest.
+   * Read an element once, on demand: webrtc.v1.PropertyReadRequest.
    *
    * @generated from enum value: PERMISSION_ACTION_READ = 1;
    */
   READ = 1,
 
   /**
-   * Write an attribute directly.
+   * Write an attribute to a value: webrtc.v1.AttributeWriteRequest, carried on
+   * AppMessage.attribute_write and forwarded to a connector as
+   * SessionResponse.execute_attribute_write.
+   *
+   * MUST be enforced separately from INVOKE. Writing an attribute and invoking a command
+   * are different operations in Matter carrying different authority: a user who may
+   * toggle a light is not thereby a user who may rewrite its attributes. An earlier form
+   * of this schema routed an absolute setpoint through DeviceCommand, which made INVOKE
+   * imply WRITE and left the distinction unenforceable — that is the mistake
+   * AttributeWriteRequest exists to undo, and checking INVOKE for a write would reinstate
+   * it.
    *
-   * NOTE: no message on the app leg does this. AppMessage carries handshake, command,
-   * read_request, ping, subscribe, unsubscribe and management — nothing that writes an
-   * attribute, so the only thing that changes a device is a DeviceCommand, which is
-   * INVOKE. This value therefore authorizes an operation that does not yet exist. It is
-   * kept rather than reserved because a direct attribute write is a plausible addition
-   * and burning the number would gain nothing; until then, granting it grants nothing.
+   * A relative adjust is NOT a write. Thermostat SetpointRaiseLower is a genuine Matter
+   * command and needs INVOKE; setting an absolute value needs WRITE.
    *
    * @generated from enum value: PERMISSION_ACTION_WRITE = 2;
    */
   WRITE = 2,
 
   /**
-   * Receive attribute changes as they happen: webrtc.v1.AppMessage.subscribe and the
-   * DevicePropertyEvent stream that follows. Distinct from READ — observing is a standing
-   * interest in a device, not a single question about it.
+   * Hold a standing stream of a device's reports: webrtc.v1.AppMessage.subscribe, and the
+   * PropertyReport and DeviceEventBatch that follow.
    *
-   * @generated from enum value: PERMISSION_ACTION_OBSERVE = 3;
+   * Covers BOTH attribute reports and events, as a Matter subscription does — one
+   * subscription carries attribute paths and event paths together. Which of them actually
+   * arrives is decided by allowed_attribute_refs and allowed_event_refs, not by this
+   * action. Note their emptiness rules differ: attributes default to all, events to none.
+   *
+   * NOT a privacy boundary. Anyone who may READ an element can poll it, so withholding
+   * SUBSCRIBE while granting READ hides nothing — it only costs the app round trips. Treat
+   * it as a RESOURCE control: bandwidth, battery, and how many standing streams a gateway
+   * will carry. Do not use it to protect data; use the ref lists for that.
+   *
+   * Was PERMISSION_ACTION_OBSERVE. Renamed because "observe" reads as a kind of access
+   * distinct from reading, which it is not — it is the same access held open.
+   *
+   * @generated from enum value: PERMISSION_ACTION_SUBSCRIBE = 3;
    */
-  OBSERVE = 3,
+  SUBSCRIBE = 3,
 
   /**
-   * Send a webrtc.v1.DeviceCommand. This is the action that moves hardware.
+   * Invoke a command on a cluster: webrtc.v1.DeviceCommand. This is the action that moves
+   * hardware.
+   *
+   * Commands are named by (cluster_id, matter_command_id), a different ID space from
+   * attributes — On/Off cluster 0x0006 has an attribute 0x0000 and a command 0x0000 that
+   * are unrelated. So allowed_attribute_refs cannot narrow this; allowed_command_refs is
+   * what does.
    *
    * @generated from enum value: PERMISSION_ACTION_INVOKE = 4;
    */

package/src/kusinta/iot/access/v1/roles_pb.js

@@ -8,7 +8,7 @@ import { enumDesc, fileDesc, tsEnum } from "@bufbuild/protobuf/codegenv2";
  * Describes the file kusinta/iot/access/v1/roles.proto.
  */
 export const file_kusinta_iot_access_v1_roles = /*@__PURE__*/
-  fileDesc("CiFrdXNpbnRhL2lvdC9hY2Nlc3MvdjEvcm9sZXMucHJvdG8SFWt1c2ludGEuaW90LmFjY2Vzcy52MSp1CgRSb2xlEhQKEFJPTEVfVU5TUEVDSUZJRUQQABIRCg1ST0xFX1JFU0lERU5UEAESFwoTUk9MRV9QUk9QRVJUWV9PV05FUhACEhMKD1JPTEVfVEVDSE5JQ0lBThADEhYKElJPTEVfR0FURVdBWV9BRE1JThAEKqsBChBQZXJtaXNzaW9uQWN0aW9uEiEKHVBFUk1JU1NJT05fQUNUSU9OX1VOU1BFQ0lGSUVEEAASGgoWUEVSTUlTU0lPTl9BQ1RJT05fUkVBRBABEhsKF1BFUk1JU1NJT05fQUNUSU9OX1dSSVRFEAISHQoZUEVSTUlTU0lPTl9BQ1RJT05fT0JTRVJWRRADEhwKGFBFUk1JU1NJT05fQUNUSU9OX0lOVk9LRRAEQgJIAWIGcHJvdG8z");
+  fileDesc("CiFrdXNpbnRhL2lvdC9hY2Nlc3MvdjEvcm9sZXMucHJvdG8SFWt1c2ludGEuaW90LmFjY2Vzcy52MSp1CgRSb2xlEhQKEFJPTEVfVU5TUEVDSUZJRUQQABIRCg1ST0xFX1JFU0lERU5UEAESFwoTUk9MRV9QUk9QRVJUWV9PV05FUhACEhMKD1JPTEVfVEVDSE5JQ0lBThADEhYKElJPTEVfR0FURVdBWV9BRE1JThAEKq0BChBQZXJtaXNzaW9uQWN0aW9uEiEKHVBFUk1JU1NJT05fQUNUSU9OX1VOU1BFQ0lGSUVEEAASGgoWUEVSTUlTU0lPTl9BQ1RJT05fUkVBRBABEhsKF1BFUk1JU1NJT05fQUNUSU9OX1dSSVRFEAISHwobUEVSTUlTU0lPTl9BQ1RJT05fU1VCU0NSSUJFEAMSHAoYUEVSTUlTU0lPTl9BQ1RJT05fSU5WT0tFEARCAkgBYgZwcm90bzM");
 
 /**
  * Describes the enum kusinta.iot.access.v1.Role.
@@ -17,6 +17,32 @@ export const RoleSchema = /*@__PURE__*/
   enumDesc(file_kusinta_iot_access_v1_roles, 0);
 
 /**
+ * What kind of party a user is, gateway-wide.
+ *
+ * A role is a CEILING on the kinds of action a user may perform anywhere on this gateway.
+ * It is not reach: it says nothing about WHICH devices the user may act on. Reach is
+ * decided by filing — which spaces the user holds, and which devices are in them — and
+ * the two are independent. A role must never be read as reach, and reach must never be
+ * read as permission to act.
+ *
+ * The gateway resolves the two together into DeviceAcl.allowed_actions, per device. A
+ * role narrows what may appear there; it does not put anything there on its own.
+ *
+ * Carried in the app's token as webrtc.v1.AppTokenClaims.roles, as an array of proto3
+ * canonical enum NAME strings (e.g. ["ROLE_RESIDENT", "ROLE_GATEWAY_ADMIN"]) rather than
+ * integers, so the claim stays self-describing. A user may hold several at once and the
+ * effective ceiling is their union.
+ *
+ * UNORDERED. These are categories, not levels: a technician is not "more than" a
+ * resident, and there is no >= comparison to make between them. Anything needing a graded
+ * comparison — Matter's View/Operate/Manage/Administer, say — would be a separate concept
+ * and is deliberately not modelled here.
+ *
+ * A role is a ceiling rather than a floor, so it may be WIDENED per device by facts the
+ * role does not know: a user who owns a device may hold actions on it that their
+ * gateway-wide role alone would not grant. That widening is the gateway's to apply and is
+ * visible to the app only in the resolved DeviceAcl.
+ *
  * @generated from enum kusinta.iot.access.v1.Role
  */
 export const Role = /*@__PURE__*/
@@ -33,6 +59,12 @@ export const PermissionActionSchema = /*@__PURE__*/
  * names an operation that exists on the app leg, so a grant can be checked against the
  * message that arrived.
  *
+ * The action says HOW data is reached. WHICH elements it reaches is a separate question,
+ * answered by the ref lists on DeviceAcl — allowed_attribute_refs, allowed_command_refs
+ * and allowed_event_refs. Keeping the two apart is deliberate: attributes, commands and
+ * events are addressed by three different ID spaces, and folding "which kind of element"
+ * into the action verb would make the action mean two things at once.
+ *
  * @generated from enum kusinta.iot.access.v1.PermissionAction
  */
 export const PermissionAction = /*@__PURE__*/

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

@@ -0,0 +1,201 @@
+// @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.
+   *
+   * Ignored where device_hint is set, and narrowed to one rather than refused: a hint names
+   * one device, so a window restricted to it can never produce a second arrival to attribute.
+   * The combination is meaningless rather than dangerous, and there is no honest code in
+   * PairingError for "your request contradicted itself" — refusing it would mean answering a
+   * malformed request with an entitlement decision that was never made.
+   *
+   * @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>;
+