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

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("CiFrdXNpbnRhL2lvdC9hY2Nlc3MvdjEvcm9sZXMucHJvdG8SFWt1c2ludGEuaW90LmFjY2Vzcy52MSp1CgRSb2xlEhQKEFJPTEVfVU5TUEVDSUZJRUQQABIRCg1ST0xFX1JFU0lERU5UEAESFwoTUk9MRV9QUk9QRVJUWV9PV05FUhACEhMKD1JPTEVfVEVDSE5JQ0lBThADEhYKElJPTEVfR0FURVdBWV9BRE1JThAEKq0BChBQZXJtaXNzaW9uQWN0aW9uEiEKHVBFUk1JU1NJT05fQUNUSU9OX1VOU1BFQ0lGSUVEEAASGgoWUEVSTUlTU0lPTl9BQ1RJT05fUkVBRBABEhsKF1BFUk1JU1NJT05fQUNUSU9OX1dSSVRFEAISHwobUEVSTUlTU0lPTl9BQ1RJT05fU1VCU0NSSUJFEAMSHAoYUEVSTUlTU0lPTl9BQ1RJT05fSU5WT0tFEARCAkgBYgZwcm90bzM");
+  fileDesc("CiFrdXNpbnRhL2lvdC9hY2Nlc3MvdjEvcm9sZXMucHJvdG8SFWt1c2ludGEuaW90LmFjY2Vzcy52MSp1CgRSb2xlEhQKEFJPTEVfVU5TUEVDSUZJRUQQABIRCg1ST0xFX1JFU0lERU5UEAESFwoTUk9MRV9QUk9QRVJUWV9PV05FUhACEhMKD1JPTEVfVEVDSE5JQ0lBThADEhYKElJPTEVfR0FURVdBWV9BRE1JThAEKq0BChBQZXJtaXNzaW9uQWN0aW9uEiEKHVBFUk1JU1NJT05fQUNUSU9OX1VOU1BFQ0lGSUVEEAASGgoWUEVSTUlTU0lPTl9BQ1RJT05fUkVBRBABEhsKF1BFUk1JU1NJT05fQUNUSU9OX1dSSVRFEAISHwobUEVSTUlTU0lPTl9BQ1RJT05fU1VCU0NSSUJFEAMSHAoYUEVSTUlTU0lPTl9BQ1RJT05fSU5WT0tFEAQqpQEKEk1lbWJlcnNoaXBSZWxhdGlvbhIjCh9NRU1CRVJTSElQX1JFTEFUSU9OX1VOU1BFQ0lGSUVEEAASIAocTUVNQkVSU0hJUF9SRUxBVElPTl9SRVNJREVOVBABEh8KG01FTUJFUlNISVBfUkVMQVRJT05fU0VSVklDRRACEicKI01FTUJFUlNISVBfUkVMQVRJT05fSE9VU0VIT0xEX0FETUlOEANCAkgBYgZwcm90bzM");
 
 /**
  * Describes the enum kusinta.iot.access.v1.Role.
@@ -28,10 +28,13 @@ export const RoleSchema = /*@__PURE__*/
  * 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.
+ * The building-server gateway holds each user's roles itself and authorises from what it
+ * holds. The one role it cannot know is the administration of the organisation that owns it,
+ * which the api-server keeps: that one it takes from the app's token
+ * (webrtc.v1.AppTokenClaims.roles), and the api-server tells it who those administrators are
+ * (signaling.v1.VouchedAdministrators), which can end that administration but never grant it. The api-server learns the rest from the gateway
+ * (reporting.v1.GatewayMember). 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
@@ -43,6 +46,15 @@ export const RoleSchema = /*@__PURE__*/
  * 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.
  *
+ * STAFF. A user who holds ROLE_TECHNICIAN, ROLE_PROPERTY_OWNER or ROLE_GATEWAY_ADMIN on a
+ * gateway is staff there: they serve the building rather than live in it. Wherever this
+ * schema says "staff" or "a staff member" it means exactly that, as the gateway holds roles,
+ * every vouched administrator included; holding ROLE_RESIDENT besides changes nothing. The
+ * term carries one rule about people: staff are named to whoever may list every member; a
+ * resident is named only to the people they live with; and where anyone lives is told by
+ * user id only to their own household, and to anyone else only under a residency id
+ * (MembershipRelation, RESIDENCY IDS).
+ *
  * @generated from enum kusinta.iot.access.v1.Role
  */
 export const Role = /*@__PURE__*/
@@ -70,3 +82,114 @@ export const PermissionActionSchema = /*@__PURE__*/
 export const PermissionAction = /*@__PURE__*/
   tsEnum(PermissionActionSchema);
 
+/**
+ * Describes the enum kusinta.iot.access.v1.MembershipRelation.
+ */
+export const MembershipRelationSchema = /*@__PURE__*/
+  enumDesc(file_kusinta_iot_access_v1_roles, 2);
+
+/**
+ * How a member stands to a space they are filed in. Held per membership — set by
+ * webrtc.v1.AssignUserToSpace — unlike Role, which is gateway-wide. The two are independent:
+ * a technician who lives in an apartment is filed on it as RESIDENT, and a resident who
+ * looks after a building's plant room is filed there as SERVICE. RESIDENT is refused on a
+ * room: a home's residents live in all of it.
+ *
+ * HOUSEHOLD ADMIN. HOUSEHOLD_ADMIN is RESIDENT and more: a resident who also governs the
+ * home (webrtc.v1 household.proto). It is held on an apartment and nowhere else, and is never
+ * a role: the app's token, and every role the gateway holds, are the same with it as without
+ * it. Wherever this schema says RESIDENT, a resident or a home's residents, it means
+ * HOUSEHOLD_ADMIN too, unless it names HOUSEHOLD_ADMIN apart: what a household admin sees of
+ * the home, and when from, is exactly what a resident sees. A change between RESIDENT and
+ * HOUSEHOLD_ADMIN on the same apartment continues the residency below, with its id and its
+ * since; it is no relation change in the sense the residency rules use.
+ *
+ * A HOME is an apartment and the rooms in it. What a user learns of a home depends on how
+ * they reach it; where several apply, the first wins:
+ *
+ *   * As its resident — RESIDENT on the apartment. They see and operate everything filed
+ *     in it, and its history from the start of their current residency, never before: a new
+ *     tenant does not read the previous one's, nor learn when or by whom anything was
+ *     changed before they moved in: every time from before that a home's rooms and devices
+ *     carry — a reading's timestamp included — is unset for them, save a
+ *     webrtc.v1.ServiceStatus, which always carries its times and so gives none before the first
+ *     quarter hour of their residency, from that quarter hour on.
+ *   * As an installer under a commissioning grant on the home, while it is active — the
+ *     service view below, and on top of it what commissioning.v1 (GRANTS) lists: the home's
+ *     commissioning and heating records, its devices' write behaviours to bind outputs by
+ *     (device.v1.AttributeBehaviour), and the readings a test they run is judged by while it
+ *     runs. Never its history, savings, comfort settings or device events, nor who lives
+ *     there.
+ *   * As service — SERVICE on the apartment, a room in it, or a building or floor above it,
+ *     or as the gateway's administrator. Of the building's own devices in what they reach of
+ *     the home — any
+ *     device no person owns — they see what each is and a webrtc.v1.ServiceStatus,
+ *     evaluated each quarter hour, and no reading, event or time of the device itself; they
+ *     operate none of them. Of what they reach of the home — from the room they are filed
+ *     on, or all of it — they see how its rooms are set up, with
+ *     RoomClimate.state_withheld marking what is not shown, and its links with
+ *     DeviceLink.details_withheld; modes on a home are not sent to them at all — save that the
+ *     property owner and the gateway administrators are sent an empty home's rooms and modes
+ *     in full, and its floor zones (webrtc.v1 household.proto, EMPTY HOME). Service
+ *     that reaches the apartment itself also gets its climate summary over the disclosed
+ *     period. What they newly see of the home reaches them as it happens; what they lose,
+ *     at once.
+ *   * Not at all — RESIDENT on a building or floor above it. Living in a building is not
+ *     living in every apartment in it.
+ *
+ * What was recorded while a room or device was in a home stays with the home after it
+ * leaves: its history, and the times and people it carries from then, are never given to
+ * whoever reaches it later.
+ *
+ * A residency starts when a user is assigned RESIDENT on an apartment while not already its
+ * resident — a membership recorded with no relation included, so its holder starts afresh —
+ * and ends with any other change to that membership. Assigning RESIDENT to a resident
+ * changes nothing. A space becoming an apartment starts the residency of each RESIDENT
+ * member on it, and ceasing to be one ends it — though it releases no device: what is no
+ * longer a home holds nobody's devices for a next tenant. A device in a space becoming an
+ * apartment, owned by someone who is not to be its resident, is taken out of that space.
+ *
+ * A device filed in a home counts as in the home wherever else it is also filed, a device a
+ * resident owns included: reaching it through another space shows it to nobody. A link
+ * never joins a device in a home to one outside it. Outside homes the relation changes
+ * nothing: what is filed there is visible to whoever reaches it. A device owned as RESIDENT
+ * is the exception everywhere, whoever owns it: it is visible to its owner and the RESIDENT
+ * members filed on the space it is filed in — for a device in a home, the home's residents
+ * alone, wherever else it is filed; never those who merely reach a space from above — and
+ * to nobody else. An owner who stops living in the home it is filed in gives it up: it is
+ * released, with no owner, and stays filed in the home alone, as one of the building's own
+ * devices there. A device given up so, or released, then appears to service as any device
+ * newly in the home does, as it happens; that much a release shows.
+ *
+ * Who may change a home's members, move its spaces or file devices into and out of it is
+ * restricted by the gateway, and a refused caller gets NOT_ENTITLED; within the household it
+ * is its household admins' (webrtc.v1 household.proto). This keeps a home's
+ * life — its readings, history and modes — from anyone but its residents by default; those
+ * who service the building get the service view above and no more. It does not keep the
+ * property owner or the administrator out by force — they hold the building's filing
+ * authority and the gateway itself — but it makes their seeing in a deliberate act on the
+ * home, such as filing themselves on it, rather than something handed out by default. They
+ * remove a resident who moves out, so they are shown every residency, and since when
+ * (webrtc.v1.ListGatewayMembers), but never who holds it (see RESIDENCY IDS).
+ *
+ * RESIDENCY IDS. To a caller who does not live in the home, a RESIDENT membership is told
+ * only under its residency id: an id the gateway mints for that residency alone, when it
+ * begins, holds for as long as it lasts unbroken, and never reuses. It is opaque, begins
+ * with "residency:", and is never a user's id or derived from one, so nothing told under it
+ * ties the residency to a name, a role or another membership — and nothing changes it when
+ * the person who holds it becomes staff or stops being staff (Role, STAFF). A relation
+ * change, or the residency ending, ends its id. The people of the home see one another
+ * under their user ids. Where a request below names a member, it says whether a residency
+ * id may stand for one; a request that does not say so refuses one as INVALID_REQUEST, so
+ * that no user is ever made under one.
+ *
+ * A membership recorded with no relation, made before relations existed, sees no more than
+ * either relation would where it is held: on an apartment or a room, a home as service; on a
+ * building or floor, no home at all. It is listed with UNSPECIFIED so that it can be found
+ * and assigned again.
+ *
+ * @generated from enum kusinta.iot.access.v1.MembershipRelation
+ */
+export const MembershipRelation = /*@__PURE__*/
+  tsEnum(MembershipRelationSchema);
+