@7365admin1/core 3.42.3 → 3.43.0

package/CHANGELOG.md

@@ -1,5 +1,301 @@
 # @iservice365/core
 
+## 3.43.0
+
+### Minor Changes
+
+- f8750e6: Camera functions for Virtual Patrol, proxied server-side.
+
+  Adds authenticated camera endpoints so the apps can use a site camera without ever
+  holding its credential. Dahua devices authenticate with digest and the cleartext
+  password on every request (HTTP API V3.37 §3.4) and the specification offers no
+  session or usable token, so the only safe shape is a server-side proxy.
+
+  - `useCameraViewController` — snapshot, snapshot-to-file for evidence, and
+    per-recorder health.
+  - A camera record does not hold a device address: `site.cameras.host` is the CCTV
+    relay's page URL and its numeric last path segment is the stream channel. A
+    camera is therefore resolved as **recorder (from `CAMERA_RTSP_DEVICES`, keyed by
+    relay authority) + channel (from the stored host)**. The address and credential
+    live in deployment configuration only — never in the database, never in a client.
+  - Pictures come off the video stream (one `ffmpeg` frame per snapshot, substream
+    for a tile, main stream for an evidence capture). The recorder in use exposes
+    RTSP only; its HTTP CGI ports are not reachable, so `snapshot.cgi`, firmware
+    (§4.6.14), device clock (§4.6.2) and PTZ (§8.1.5) cannot be used against it.
+    Firmware and clock are reported as unavailable with a reason, and PTZ refuses.
+    `GET /site-cameras/capabilities` reports `ptz: false` whatever
+    `CAMERA_PTZ_ENABLED` says, so a client hides the control rather than drawing a
+    pad whose every press fails.
+  - A camera whose relay has no configured recorder, or whose address carries no
+    channel, is refused up-front with a reason rather than failing as a blank picture.
+  - At most `CAMERA_MAX_CONCURRENT_GRABS` (4) pictures are taken at once across the
+    process, so the endpoint cannot fill the API host with ffmpeg or overpull the
+    recorder; over that, the caller is told the cameras are busy.
+  - Access is decided by the caller's site/org membership and their role's
+    permissions, never by the camera id in the URL.
+  - ANPR units are refused: ANPR belongs to visitor and vehicle management, not to
+    Virtual Patrol or CCTV.
+  - Camera host, username, password and the RTSP URL are never returned and never
+    logged; ffmpeg's stderr is discarded because it echoes the credential.
+  - No retry on a camera call: the device locks an account for 1800 s after 3
+    failures in 30 s (§4.7.x).
+
+  Requires `ffmpeg` on the API host (or `CAMERA_FFMPEG_PATH`); where it is absent the
+  snapshot endpoints answer with "Video tooling is not available on this server."
+
+- b06ae8f: Camera integration layer: a capability descriptor, a transport registry, and the
+  Dahua device HTTP adapter (written, tested, switched off).
+
+  Every camera in the wall and status responses now carries a `capabilities`
+  descriptor: `liveVideo`, `stillFrame`, `digitalZoom`, `ptz`, `presets`,
+  `playback`, `events`, `audio`, `deviceInfo`, each `supported` / `unsupported` /
+  `unknown` with a machine-readable reason code and one sentence. A client renders
+  itself from it without knowing anything about relays, recorders or networks.
+  `unknown` is distinct on purpose: "we have not been allowed to ask" is not the
+  same fact as "this camera cannot".
+
+  Capabilities resolve through a transport registry instead of the service picking
+  a path. `RELAY_PLAYER` is the stored player-page URL rendered in a WebView (the
+  live product's picture path, live video only, no control channel). `RTSP_FRAME`
+  is one ffmpeg still off the recorder. `DEVICE_HTTP` is the camera's own CGI API.
+  Registration order is preference order, so one camera serves live video over the
+  relay and evidence stills over RTSP at the same time, and adding a transport
+  later needs no service change.
+
+  `DEVICE_HTTP` covers device info/version, snapshot, PTZ (continuous, absolute,
+  stop), presets (list and recall), recorded-file query with playback URL
+  construction, and event subscription - digest auth only, values percent-encoded,
+  403 treated as bad credentials and 401 as an ordinary challenge. It contacts
+  nothing today: the recorder in this estate answers on RTSP only. Enabling it is
+  configuration, not a code change.
+
+  A shared, persistent authentication failure budget is mandatory on that path. The
+  device locks an account for 1800 s after 3 failed logins in 30 s, so failures are
+  counted per device in the cache, the budget stops at 2, and once spent no request
+  leaves the process. Nothing retries anywhere.
+
+  Mutating operations are structurally unreachable while disabled: the adapter is
+  `null` without `CAMERA_DEVICE_HTTP_ENABLED`, and its `control` object is `null`
+  without `CAMERA_DEVICE_CONTROL_ENABLED`. Movement codes are an allow-list;
+  `SetPreset`, `ClearPreset`, tours, patterns, `configManager` writes and reboot are
+  absent.
+
+  Capability probing is read-only, cached, budget-aware, never throws, and happens
+  only on a deliberate single-camera status request - never as a side effect of a
+  list.
+
+  `host` is now returned for `type: "ip"` cameras on the wall response. It is the
+  video relay's player-page URL, not a device address and not a credential, and
+  `GET /site-cameras` already returns it to every authenticated caller. `anpr`
+  records, whose `host` is a real device endpoint, are excluded by the allow-list
+  itself.
+
+  New configuration, all optional and all off by default: `CAMERA_DEVICE_HTTP`
+  (JSON keyed by relay authority, credential referenced by environment variable
+  name), `CAMERA_DEVICE_HTTP_ENABLED`, `CAMERA_DEVICE_CONTROL_ENABLED`,
+  `CAMERA_DEVICE_HTTP_TIMEOUT_MS` (8000),
+  `CAMERA_DEVICE_HTTP_PROBE_TTL_SECONDS` (900). See
+  `docs/camera-integration-config.md`.
+
+  Existing responses keep every field they had, with the same wording, so current
+  consumers are unaffected.
+
+- e6e1c4c: CCTV monitoring wall: a site-scoped camera list and a batched health sweep.
+
+  Two additions to the camera proxy so a supervisor can watch a whole site rather
+  than one checkpoint at a time.
+
+  `getSiteWall` returns the cameras of one site from `site.cameras` - the
+  collection the real cameras are in - together with the polling intervals and
+  fan-out caps the client should use. No device is contacted, so opening a wall is
+  one database read. Entitlement is by site membership, not by the id in the URL,
+  and a caller outside the site gets the same answer as one asking for a site that
+  does not exist.
+
+  `getSiteHealth` probes the cameras currently on screen with at most
+  `CAMERA_WALL_MAX_CONCURRENT_PROBES` in flight. Reachability is a **per-recorder**
+  answer, cached per recorder: twelve of this estate's cameras are twelve channels
+  on one device, so a full wall is one connect rather than one per tile. It never
+  throws for a camera that is down; unreachable is the answer, and a camera whose
+  relay has no configured recorder is refused with a reason instead.
+
+  Firmware version and device clock are reported as unavailable with a reason: they
+  are HTTP CGI facts and the recorder in use exposes RTSP only.
+
+  Snapshots now record when a camera last returned a picture, so a tile can say
+  "last frame 40 minutes ago" instead of "never".
+
+  New, all optional and conservative by default: `CAMERA_WALL_POLL_MS` (5000),
+  `CAMERA_SINGLE_POLL_MS` (2000), `CAMERA_WALL_MAX_TILES` (9),
+  `CAMERA_WALL_MAX_CONCURRENT_PROBES` (4), `CAMERA_HEALTH_CACHE_SECONDS` (20).
+
+- dbc9026: Camera setup from the recorder and channel, and a read-only test before saving.
+
+  A CCTV camera record stores a video-relay player-page URL. Nothing printed on a
+  camera or shown in a recorder's own screens tells anybody what that URL is, so
+  adding a camera meant asking whoever runs the video service for one address per
+  camera and pasting it in unverified.
+
+  `POST /site-cameras` and `PATCH /site-cameras/id/:id` now also accept
+  `recorderHost`, `recorderPort` and `channel`. The server reads the existing
+  `CAMERA_RTSP_DEVICES` map backwards - relay authority to recorder becomes
+  recorder to relay authority - and derives the same `https://<relay>/<channel>`
+  address it has always stored. There is deliberately no second map and no new
+  stored field: the recorder fields are consumed by the controller and never reach
+  the model, so `site.cameras` keeps exactly the shape it has today.
+
+  Additive and ordered so: a request that sends `host` behaves exactly as it
+  always has, so every camera configured that way and anyone holding a ready-made
+  address is unaffected. A recorder with no configured entry is refused with a
+  sentence a property manager can act on rather than a code.
+
+  New: `POST /site-cameras/site/:siteId/test` - does this address actually show a
+  picture? Site-scoped because the camera does not exist yet, and it requires
+  `site-settings:manage-cctv-camera`. The probe is read only: one TCP connect with
+  no credential, then at most one video frame off the stream. There is no mutating
+  call in the path.
+
+  It is rationed before it can reach a device - one test per camera per 15 s, four
+  per recorder per 5 minutes - and it consults the shared authentication failure
+  budget first, so pressing the button cannot walk a recorder into its own
+  3-failures-in-30-seconds, 1800-second lockout. It answers with one of five plain
+  sentences and never an address, port, credential or device message.
+
+  `ffmpeg`'s stderr is now read for one fact - was the handshake rejected - and
+  discarded chunk by chunk without being accumulated, logged or returned, so "the
+  recorder refused the credential" can be told apart from "the channel is not
+  sending video". Snapshot failures gain that distinction too.
+
+  `authorizeSite` takes an optional permission list; existing callers are unchanged
+  and still require the camera view permissions.
+
+- 6238e88: Authorize creating, editing and deleting a site camera.
+
+  `POST /site-cameras`, `PATCH /site-cameras/id/:id` and `DELETE
+/site-cameras/id/:id` carried `requireAuth` and nothing else. There was no
+  permission check and no site scoping, so any signed-in account in any
+  organisation could add a camera to a site it has no relationship with, rewrite
+  another customer's camera address, or hard-delete one - the delete is a real
+  `deleteOne`, not a soft delete, and it reported success whether or not it matched
+  anything.
+
+  All three now go through `authorizeSite`, the same rule the read paths already
+  use: the caller must be a member of the camera's site, and their role must hold
+  the permission the Settings panel that draws the button is drawn on -
+  `site-settings:manage-cctv-camera` for a CCTV camera, `site-settings:manage-anpr-camera`
+  for an ANPR one. One endpoint serves both panels, so the permission follows the
+  camera's own `type` rather than being one string for both; asking only for the
+  CCTV string would have refused a role provisioned to manage ANPR alone.
+
+  For `PATCH` and `DELETE` the site and the type are read off the stored camera,
+  never off the request - `schemaUpdateSiteCamera` carries neither, and a caller
+  must not be able to supply either. A camera the caller may not reach is reported
+  exactly as a camera that does not exist, so the difference cannot be used to
+  enumerate camera ids.
+
+  Measured on staging before shipping: of the 107 users entitled to a site that has
+  a CCTV camera, 12 pass this gate and every one of them passes on the `*`
+  wildcard. No role that would now be refused holds any `site-settings:` string at
+  all, so no account that can open the CCTV or ANPR panel today is refused by this
+  change.
+
+  No response shape, status code or field changed for a permitted caller.
+
+### Patch Changes
+
+- aea01a0: Camera entitlement: an engagement grants a site only to an org-level membership, and permissions resolve against the granting role
+
+  Two follow-ups to the camera entitlement change:
+
+  - the engagement branch of `cameraGrant` ignored `members.siteId`, so a member
+    pinned to one site could reach every site their organisation is engaged at.
+    It now requires an org-level membership, matching the owning-org branch above
+    it: a membership pinned to a site never grants a different site.
+  - `getUserPermissions` accepts the granting membership's `role`, so a caller
+    holding several memberships in one organisation is no longer resolved by
+    whichever member document Mongo returns first.
+
+- e890a82: Let camera authorization understand engagements, and resolve it against the
+  right organisation.
+
+  Three defects in the same decision, fixed together because they are the same
+  question: "may this person reach this site, and on whose behalf?"
+
+  **1. An engagement was not an entitlement.** The product routes a service
+  provider - a security agency, a property management agency - to a customer's
+  site through an ACTIVE `customer.sites` record (`{org: provider, siteOrg: owner,
+site}`). 227 of those are active on staging, 53 of them cross-organisation. It
+  is the same list the web apps' own site switcher is drawn from
+  (`useCustomerSite().getAll()`). No camera authorization code read it, so a guard
+  whose agency is contracted at a site was refused the cameras of the site the
+  switcher had just offered them. Measured on staging: **11 people reach a site
+  holding an active IP camera by this route and no other, 7 of them on wildcard
+  `owner` / `Super Admin` roles** - and across all 200 sites the figure is 125
+  people, 43 of them on wildcard roles. Nobody loses access; the change is
+  additive.
+
+  **2. `site.org` does not exist.** `authorizeSite` and `authorizeCamera`
+  projected `{org: 1}` and tested `site?.org`. All 200 site documents carry
+  `orgId`; not one carries `org`. So the org-level branch of the rule - the branch
+  for the 90 membership rows (56 people) that carry no `siteId` - could never
+  match. It reads `orgId` now, with `org` kept as a fallback. This WIDENS access,
+  so it was measured before it was enabled: on staging it admits **0** additional
+  people to a site holding a camera, and 14 across all 200 sites.
+
+  **3. Permissions resolved against an arbitrary organisation.**
+  `getUserPermissions({user, org: memberships[0]?.org})` took whichever membership
+  Mongo returned first, which for the 22 people who belong to more than one
+  organisation is a coin toss - it could read the permissions of an organisation
+  that has nothing to do with the site being asked about. It now resolves against
+  the membership that actually granted access.
+
+  Also splits `entitleSite` (may this person reach this site) out of
+  `authorizeSite` (that, plus the permission this particular use needs), so a
+  plain read of a site's own camera list can be scoped without also being gated on
+  a permission that would strand people who are legitimately at the site.
+
+  No response field changed. No route changed. No device is contacted by any of
+  this.
+
+- c205571: Scope `GET /site-cameras` to the caller's own site.
+
+  The site was an OPTIONAL query parameter and nothing on the handler looked at
+  the session beyond `requireAuth`. So any signed-in account, in any organisation,
+  could page the whole estate's cameras - on staging that is all 15 active IP
+  cameras across 3 owner organisations, each record carrying its `host` and its
+  `username`. It is the plainest cross-tenant read left in the camera module.
+
+  `site` is now required, and the caller is authorised against it with
+  `entitleSite`: membership of the site, of its owning organisation, or an ACTIVE
+  `customer.sites` engagement with it. "Not yours" and "does not exist" answer
+  identically, so site ids cannot be enumerated from the difference.
+
+  **Every caller in the estate already sends `site`** - checked across every
+  repository, not assumed:
+
+  | caller                                                          | sends                         |
+  | --------------------------------------------------------------- | ----------------------------- |
+  | `iservice365-mobile-app-security` `pages/cctv/index.vue` (live) | `site`, `type: ip`, `page`    |
+  | `iservice365-mobile-app-security` `useAnprEnabled` (live)       | `site`, `type: anpr`          |
+  | `iservice365-layer-common` `CameraMain.vue` (Site Settings)     | `site`, `type`, `page`        |
+  | `iservice365-layer-common` `CameraWall.vue`                     | `site`, `type: ip`, `page`    |
+  | `iservice365-web-app-security` `VirtualPatrolRoutesForm.vue`    | `site`, `type: ip`, `page: 1` |
+  | `isecure365-mobile-app` `site.service.ts` `getAnprCameras`      | `site`, `type: anpr`          |
+
+  So no running client breaks.
+
+  Deliberately NOT gated on a camera permission. This is the same list the site's
+  own Settings panel and the guard's app have always read; on staging only 25 of
+  the 118 people entitled to a site with a camera hold a camera-view permission,
+  so a permission gate here would strand people who are legitimately at the site.
+  Restricting the read to the caller's own sites is the fix; who among them may
+  look is a separate decision that needs its own measurement.
+
+  The repository's 15-minute cache key already carries the site, so a cached page
+  can only be served to callers authorised for that same site. No caller id was
+  added to the key - it would make the cache per-person for an answer that is
+  identical per site.
+
 ## 3.42.3
 
 ### Patch Changes