@kusinta/iot-schema 0.1.0-beta.9 → 0.2.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kusinta/iot-schema",
-  "version": "0.1.0-beta.9",
+  "version": "0.2.0-beta.2",
   "type": "module",
   "license": "MIT",
   "files": ["src"],
@@ -14,13 +14,24 @@
     "./device":                 "./src/kusinta/iot/device/v1/device_pb.js",
     "./device/descriptor":      "./src/kusinta/iot/device/v1/descriptor_pb.js",
     "./device/properties":      "./src/kusinta/iot/device/v1/properties_pb.js",
+    "./device/matter-options":   "./src/kusinta/iot/device/v1/matter_options_pb.js",
     "./device/property-update": "./src/kusinta/iot/device/v1/property_update_pb.js",
+    "./device/cluster-state":   "./src/kusinta/iot/device/v1/cluster_state_pb.js",
+    "./device/event":           "./src/kusinta/iot/device/v1/device_event_pb.js",
+    "./vendor/options":         "./src/kusinta/iot/vendor/v1/vendor_options_pb.js",
+    "./vendor/homematic":       "./src/kusinta/iot/vendor/homematic/v1/homematic_pb.js",
     "./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",
     "./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":                 "./src/kusinta/iot/webrtc/v1/envelope_pb.js",
+    "./webrtc/app-token":       "./src/kusinta/iot/webrtc/v1/app_token_pb.js",
+    "./webrtc/management":      "./src/kusinta/iot/webrtc/v1/management_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",
+    "./signaling/service":      "./src/kusinta/iot/signaling/v1/signaling_service_pb.js"
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.12.0"

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

@@ -13,9 +13,152 @@ import type { Timestamp } from "@bufbuild/protobuf/wkt";
  */
 export declare const file_kusinta_iot_access_v1_acl: GenFile;
 
+/**
+ * AttributeRef names one attribute on one endpoint. It is the schema's single way to say
+ * "this attribute of this device" — used to grant it, to bound it, to read it and to write
+ * it, so a consumer writes one matcher rather than several that must agree.
+ *
+ * Addressed exactly as device.v1.PropertyUpdate is, and for the same reasons:
+ *
+ *   * cluster_id and attribute_id are NUMERIC and are what resolution matches. Attribute
+ *     names repeat across clusters — MeasuredValue is Temperature (0x0402), Relative
+ *     Humidity (0x0405) and Pressure (0x0403) — and a numeric pair is what the
+ *     (matter_cluster_id)/(matter_attribute_id) annotations carry, so nothing has to be
+ *     parsed or looked up to compare them.
+ *   * attribute_name is advisory: the attribute's own spelling, for logs and rendering. It
+ *     is NOT matched on the Matter branch. On the vendor branch it is the only address
+ *     there is, and there it is authoritative.
+ *   * endpoint_id matters because a device presents several endpoints, often of the same
+ *     device type: all four channels of a 4-channel actuator are OnOff on cluster 0x0006,
+ *     so a reference without one cannot tell channel 1 from channel 3.
+ *
+ * What an ABSENT endpoint_id means is decided by the field holding this message, not here,
+ * and the current holders mean opposite things on purpose — see
+ * DeviceAcl.allowed_attribute_refs and PropertyConstraint.attribute. It is optional on the
+ * wire so that "not stated" is representable and rejectable, rather than a bare uint32
+ * decoding an omission to endpoint 0, which is the Matter root node.
+ *
+ * @generated from message kusinta.iot.access.v1.AttributeRef
+ */
+export declare type AttributeRef = Message<"kusinta.iot.access.v1.AttributeRef"> & {
+  /**
+   * Advisory on the Matter branch, authoritative on the vendor branch. See above.
+   *
+   * @generated from field: string attribute_name = 1;
+   */
+  attributeName: string;
+
+  /**
+   * Matter branch. Both required there, both unset on the vendor branch.
+   *
+   * @generated from field: uint32 cluster_id = 2;
+   */
+  clusterId: number;
+
+  /**
+   * @generated from field: uint32 attribute_id = 4;
+   */
+  attributeId: number;
+
+  /**
+   * @generated from field: optional uint32 endpoint_id = 3;
+   */
+  endpointId?: number | undefined;
+
+  /**
+   * Set to name a vendor parameter instead of a Matter attribute, by its
+   * (vendor_extension) key. Then attribute_name addresses it and cluster_id/attribute_id
+   * play no part — a vendor parameter has no Matter cluster and no numeric ID in any
+   * specification.
+   *
+   * Without this a vendor parameter could be reported but never granted, bounded or
+   * written: a valve position would be all-or-nothing for permissions, which would undo
+   * most of the point of making vendor extensions reachable at all.
+   *
+   * @generated from field: optional string vendor_extension = 5;
+   */
+  vendorExtension?: string | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.access.v1.AttributeRef.
+ * Use `create(AttributeRefSchema)` to create a new message.
+ */
+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.
- * attribute_name uses PascalCase Matter attribute naming (e.g. "MaxHeatSetpointLimit").
  * MaxHeatSetpointLimit and MinHeatSetpointLimit are actual Matter Thermostat cluster
  * attributes (0x0016, 0x0015) — the gateway writes them directly via the connector.
  *
@@ -23,9 +166,14 @@ export declare const file_kusinta_iot_access_v1_acl: GenFile;
  */
 export declare type PropertyConstraint = Message<"kusinta.iot.access.v1.PropertyConstraint"> & {
   /**
-   * @generated from field: string attribute_name = 1;
+   * An absent AttributeRef.endpoint_id here means EVERY endpoint of the device — the
+   * opposite of what it means on a grant, deliberately. A constraint is a restriction, so
+   * omission broadens what is restricted; a grant is permission, so omission there would
+   * broaden access and is invalid instead. Both defaults fail safe.
+   *
+   * @generated from field: kusinta.iot.access.v1.AttributeRef attribute = 8;
    */
-  attributeName: string;
+  attribute?: AttributeRef | undefined;
 
   /**
    * @generated from oneof kusinta.iot.access.v1.PropertyConstraint.constraint
@@ -55,11 +203,6 @@ export declare type PropertyConstraint = Message<"kusinta.iot.access.v1.Property
     value: number;
     case: "uintMin";
   } | { case: undefined; value?: undefined };
-
-  /**
-   * @generated from field: string cluster_id_hex = 6;
-   */
-  clusterIdHex: string;
 };
 
 /**
@@ -83,26 +226,84 @@ 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;
 
   /**
+   * What this user may do to this device. EMPTY GRANTS NOTHING — an ACL with no actions
+   * permits no operation at all.
+   *
+   * Deliberately the opposite default to allowed_attribute_refs below, which is empty for
+   * "every attribute". The two are not the same kind of list: this one IS the grant, so an
+   * empty grant is empty, while that one is a FILTER narrowing the grant, so an empty
+   * filter narrows nothing. Reading either as the other fails open.
+   *
+   * PERMISSION_ACTION_UNSPECIFIED in this list is invalid and MUST be rejected; it is not
+   * a wildcard. See roles.proto for what each action authorizes.
+   *
    * @generated from field: repeated kusinta.iot.access.v1.PermissionAction allowed_actions = 4;
    */
   allowedActions: PermissionAction[];
 
   /**
-   * empty = all attributes allowed
+   * Narrows allowed_actions to particular attributes. Empty = every attribute on every
+   * endpoint, unchanged in meaning from the field it replaces — an empty filter narrows
+   * nothing. It does NOT grant anything on its own: with allowed_actions empty, this
+   * being empty still permits no operation.
+   *
+   * A ref present with no endpoint_id is INVALID and MUST be rejected, not read as a grant
+   * over every endpoint: omission must never be what widens access.
    *
-   * @generated from field: repeated string allowed_attributes = 5;
+   * @generated from field: repeated kusinta.iot.access.v1.AttributeRef allowed_attribute_refs = 7;
    */
-  allowedAttributes: string[];
+  allowedAttributeRefs: AttributeRef[];
 
   /**
    * @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[];
 };
 
 /**
@@ -112,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

@@ -11,26 +11,47 @@ import { file_kusinta_iot_access_v1_roles } from "./roles_pb.js";
  * Describes the file kusinta/iot/access/v1/acl.proto.
  */
 export const file_kusinta_iot_access_v1_acl = /*@__PURE__*/
-  fileDesc("Ch9rdXNpbnRhL2lvdC9hY2Nlc3MvdjEvYWNsLnByb3RvEhVrdXNpbnRhLmlvdC5hY2Nlc3MudjEioAEKElByb3BlcnR5Q29uc3RyYWludBIWCg5hdHRyaWJ1dGVfbmFtZRgBIAEoCRIRCgdpbnRfbWF4GAIgASgRSAASEQoHaW50X21pbhgDIAEoEUgAEhIKCHVpbnRfbWF4GAQgASgNSAASEgoIdWludF9taW4YBSABKA1IABIWCg5jbHVzdGVyX2lkX2hleBgGIAEoCUIMCgpjb25zdHJhaW50IsUCCglEZXZpY2VBY2wSNAoJZGV2aWNlX2lkGAEgASgLMiEua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuRGV2aWNlSWQSMAoHdXNlcl9pZBgCIAEoCzIfLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLlVzZXJJZBIpCgRyb2xlGAMgASgOMhsua3VzaW50YS5pb3QuYWNjZXNzLnYxLlJvbGUSQAoPYWxsb3dlZF9hY3Rpb25zGAQgAygOMicua3VzaW50YS5pb3QuYWNjZXNzLnYxLlBlcm1pc3Npb25BY3Rpb24SGgoSYWxsb3dlZF9hdHRyaWJ1dGVzGAUgAygJEkcKFHByb3BlcnR5X2NvbnN0cmFpbnRzGAYgAygLMikua3VzaW50YS5pb3QuYWNjZXNzLnYxLlByb3BlcnR5Q29uc3RyYWludCLlAQoURWZmZWN0aXZlUGVybWlzc2lvbnMSMAoHdXNlcl9pZBgBIAEoCzIfLmt1c2ludGEuaW90LmlkZW50aXR5LnYxLlVzZXJJZBI2CgpnYXRld2F5X2lkGAIgASgLMiIua3VzaW50YS5pb3QuaWRlbnRpdHkudjEuR2F0ZXdheUlkEjUKC2RldmljZV9hY2xzGAMgAygLMiAua3VzaW50YS5pb3QuYWNjZXNzLnYxLkRldmljZUFjbBIsCgh2YWxpZF9hdBgEIAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXBCAkgBYgZwcm90bzM", [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_identity_v1_identity, file_kusinta_iot_access_v1_roles]);
+
+/**
+ * Describes the message kusinta.iot.access.v1.AttributeRef.
+ * Use `create(AttributeRefSchema)` to create a new message.
+ */
+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, 0);
+  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, 1);
+  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, 2);
+  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,
@@ -45,30 +81,87 @@ export enum Role {
 export declare const RoleSchema: GenEnum<Role>;
 
 /**
+ * What a user may do to a device, as listed in DeviceAcl.allowed_actions. Each value
+ * 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 {
   /**
+   * Names no action. Present only because buf's ENUM_ZERO_VALUE_SUFFIX requires a zero
+   * value; it is not a wildcard and carries no permission.
+   *
+   * In allowed_actions it is INVALID and MUST be rejected — never read as "any action".
+   * Omission must never be what widens access.
+   *
    * @generated from enum value: PERMISSION_ACTION_UNSPECIFIED = 0;
    */
   UNSPECIFIED = 0,
 
   /**
+   * Read an element once, on demand: webrtc.v1.PropertyReadRequest.
+   *
    * @generated from enum value: PERMISSION_ACTION_READ = 1;
    */
   READ = 1,
 
   /**
+   * 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.
+   *
+   * 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,
 
   /**
-   * @generated from enum value: PERMISSION_ACTION_OBSERVE = 3;
+   * Hold a standing stream of a device's reports: webrtc.v1.AppMessage.subscribe, and the
+   * PropertyReport and DeviceEventBatch that follow.
+   *
+   * 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,
 
   /**
+   * 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;
    */
   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__*/
@@ -29,6 +55,16 @@ export const PermissionActionSchema = /*@__PURE__*/
   enumDesc(file_kusinta_iot_access_v1_roles, 1);
 
 /**
+ * What a user may do to a device, as listed in DeviceAcl.allowed_actions. Each value
+ * 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__*/