@7365admin1/core 3.47.1-staging.131 → 3.48.0

package/CHANGELOG.md

@@ -1,5 +1,896 @@
 # @iservice365/core
 
+## 3.48.0
+
+### Minor Changes
+
+- d257156: Read the Terms and Privacy Policy acceptance record as a list.
+
+  Who accepted the platform Terms, and when, was already stored - `acceptedTerms`
+  and `acceptedTermsAt` on the user - but the only way to read it was
+  `GET /terms/:user/status`, one named user at a time. The staff console has no
+  list of user ids to walk, so it could not show the acceptance record at all, and
+  nobody could answer the question that matters the day new Terms are published:
+  who has NOT accepted them yet.
+
+  `usePlatformTermsController().getAcceptance` answers it as a paged list, filtered
+  by version number and by accepted / not accepted, either or both, neither
+  meaning everybody. With a version AND "not accepted", the answer includes the
+  accounts still sitting on an older version, not only the ones that never
+  accepted anything. A version number that was never published is a 404 rather
+  than an empty page, so a mistyped filter cannot read as "nobody has accepted".
+
+  `requirePlatformStaff` gates it, resolved from the session - the same gate the
+  console audit list and the platform user list carry, and for the same reason: it
+  is a cross-tenant read by definition. Staff-level, not owner-level; the owner
+  tier stays reserved for the actions that change a client's service.
+
+  Each row carries an id, a display name, the account type and status, the
+  accepted version and the timestamp. No e-mail, no contact number, no birthday -
+  a consent record does not need them, and this list spans every client at once.
+  Soft-deleted accounts are excluded. The version number is joined at read time,
+  so a row cannot hold a stale copy of it, and the join runs after the page is
+  cut, on at most `limit` rows.
+
+  Paging is `$skip` before `$limit`, the offset derived from the page - the defect
+  fixed in the members list is not repeated here. Not cached: whether a person has
+  accepted the current Terms is the one question where a stale answer is worse
+  than a slow one.
+
+  Additive only. `GET /terms/:user/status`, `POST /terms/:user/accept`,
+  `GET /terms/latest`, `GET /terms/:id` and `POST /terms` are untouched, and no
+  existing response shape or status code changed. The route that mounts this is a
+  separate change in `iservice365-API-core`.
+
+### Patch Changes
+
+- 821d92a: Suspending or reactivating a client is now recorded in the console audit trail.
+
+  The audit trail (`console-audit`) already carried `client.suspended` and
+  `client.reactivated` with their labels and their allow-listed fields, but nothing
+  wrote them: `organization.controller.ts` was deliberately left unhooked while the
+  suspend work was still an open PR. Now that it has landed, `updateStatus` records
+  one row per status change - the direction taken from the status that was actually
+  written, the actor taken from the owner guard's return value and never from the
+  request body, and only `status` kept from the change.
+
+  The row is written after the status has changed and before the reply, the same
+  order as every other recorded action, so a row can never describe something that
+  did not happen. `recordConsoleAction` still swallows its own failures, so a lost
+  audit row cannot undo a suspension.
+
+  `client.created` stays unconnected on purpose and its reminder is unchanged.
+
+- 3817ceb: Staff console: record who did what, and add a staff-only endpoint to read it back
+- 1e10125: Authorize the HID facial-data sync handler in its own body
+
+  `syncReaderFacialData` reached `staging` with no authorization check inside the
+  handler. The API-core router does apply `requireAuth` + `authorizeManage`, so it
+  was not reachable by an ordinary signed-in user — but this is a published
+  package, and the guard and the handler sat in two different repositories. It now
+  runs the same `manage`-level check the router applies, with the site taken from
+  the stored reader. The guard test pins it by name.
+
+- 5401d35: HID: the five reader endpoints added for production readiness now authorise in their own handlers
+
+  `listReaderUsers`, `listReaderAccessLogs`, `configureReaderIntegration`,
+  `setReaderMonitor` and `setOperatingMode` had no check in their bodies. They are
+  guarded today by `authorizeView` / `authorizeManage` in the API-core router, so
+  this is not a live hole — but the guard and the handler sit in two different
+  repositories, and this is a published package: a router edit or a second
+  consumer mounting `useHidAmicoController()` would leave an endpoint that reaches
+  a physical door reader with nothing in front of it.
+
+  Each now calls `authorizeHidAccess` itself, at the level the router already
+  applies — `view` for the two lists, `manage` for the three writes — with the
+  site resolved from the stored reader, never from the request. No caller's
+  authority changes.
+
+  The guard test now covers all fifteen HID handlers and names the unguarded ones
+  in its failure message.
+
+- 1bcf58c: Fix GET /api/members returning the same page over and over
+
+  `member.repo.ts` `getAll` built its aggregate with `{ $limit: limit }` and no
+  `$skip`. `paginate()` only _labels_ the range — it returns `items` untouched and
+  computes `pageRange` arithmetically — so the server answered page 2 with page
+  1's rows under an "11-20 of 42" heading. Every Members screen in every app was
+  affected, not one screen.
+
+  `{ $skip: page * limit }` is added ahead of the limit, matching the two
+  `getOrgs*` reads in the same file that were already correct. `page` is
+  zero-based by then, and the cache key already varies by page, so no cache
+  change is needed.
+
+  The response shape is unchanged: `{ items, pages, pageRange }`.
+
+- 00bc18e: Fix the ignored serviceProviderOrgId filter on GET /api/service-providers
+
+  `service-provider.controller.ts` `getServiceProviders` validated
+  `serviceProviderOrgId` in its Joi schema but read
+  `req.query.serviceProviderId`. Joi rejects unknown keys, so no caller could
+  ever send the name that was read — the value was permanently `undefined` and
+  the documented filter was silently ignored, answering with every service
+  provider rather than the one organisation's.
+
+  The read now uses the key the schema declares. The repository already handled
+  `serviceProviderOrgId` correctly, so nothing below the controller changes.
+
+  Raised in web-app-org #142.
+
+- a1b964a: Suspending a client now actually blocks sign-in for that client's people.
+
+  Both login services (`auth.service.ts` and `auth-v2.service.ts`) checked only the
+  person's own account status and never looked at the organisation, so suspending a
+  client stopped nobody. Every session either service mints - login and mobile
+  refresh, v1 and v2 - now resolves the caller's organisation (staff and guards via
+  `members`, residents via `persons`, both directly or through their site) and
+  refuses with its own wording when that client is suspended. Seven365 staff
+  accounts are exempt.
+
+  Suspend and reactivate (`PATCH /api/organizations/:id/status`) move from the
+  staff gate to a new owner-only gate, `requirePlatformOwner`.
+
+  The hourly subscription job gains a second rule: a subscription whose `endDate`
+  passed more than `SUBSCRIPTION_END_GRACE_DAYS` (default 7) ago is suspended. It
+  is inert unless `SUBSCRIPTION_AUTO_SUSPEND_ENABLED` is set to "true".
+
+- 8d1d5c0: Require Seven365 staff to read the platform-wide user list
+
+  `GET /api/users` was `requireAuth` only. It is not filtered by organisation or
+  by site, so it returns every account on the platform — every client's residents,
+  guards and cleaners — and any signed-in account could page through the lot.
+
+  It now calls `requirePlatformStaff`, the same gate the rest of the staff console
+  uses. No second mechanism is introduced.
+
+  The per-user endpoints in the same controller (`getById`, `getByEmail`,
+  `getUsersByOrgId`, the profile and password writes) are deliberately unchanged —
+  they are a person's own account, not a cross-tenant read — and a test pins that
+  so a later sweep cannot close them by reflex.
+
+- 3c90886: Require Seven365 staff to read the platform-wide user list on /api/users/v2 too
+
+  `/api/users` and `/api/users/v2` are separate mounts onto separate controllers,
+  each with its own copy of the same unfiltered platform-wide list. Gating only
+  v1 left the gate bypassable by adding `/v2` to the URL.
+
+  `user-v2.controller.ts` `getUsers` now calls `requirePlatformStaff`, the same
+  gate. The v2 per-user endpoints are unchanged, and the test that pins the v1
+  profile endpoints as ungated now covers both controllers.
+
+## 3.47.0
+
+### Minor Changes
+
+- 35e1ba6: 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."
+
+- a2bfbb1: 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.
+
+- e11fbb5: 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).
+
+- 2d6bc0e: CCTV reliability: cache the capability probe per channel, and stop reporting a
+  missing sub-stream as a dead camera.
+
+  Two defects in the camera proxy, both of which made one camera answer for
+  another.
+
+  **The capability probe was cached per recorder.** The key was `probe:<baseUrl>`,
+  so the first camera anyone opened decided `ptz` and `presets` for every channel
+  on that recorder until the TTL expired (default 900s). On this estate twelve
+  cameras are twelve channels on one device, and they are not all the same model.
+  The key is now `cameraProbeCacheKey(baseUrl, channel)` and every reader passes a
+  channel - `refreshProbe`, the health sweep, and the monitoring wall, whose own
+  de-duplication `Map` was keyed by recorder too and would have re-created the
+  same fault a layer above the cache. Cache lifetime and eviction are unchanged.
+
+  Only `ptz` and `presets` are channel-specific. `reachable`, `lockedOut`,
+  `softwareVersion` and `deviceType` are recorder facts that answer identically on
+  every channel, which is what `deviceInfo`, `playback` and `events` read, and a
+  test pins that so it stays true. The cost is at most one probe per channel per
+  TTL, and only on the deliberate single-camera status path - the wall and the
+  health sweep still never probe.
+
+  **A channel with no sub-stream failed exactly like a dead camera.** An
+  ONVIF-attached third-party camera frequently publishes no sub-stream, and the
+  recorder answers that channel with no picture, which surfaced as "The camera did
+  not return a picture." - indistinguishable from a camera that is off.
+  `getSnapshot` now goes through `grabWithSubStreamFallback`: the sub-stream
+  first, then exactly one main-stream attempt if and only if the failure is
+  `camera-no-picture`. The result carries `stream` and `fellBackToMain`, exposed
+  on the snapshot response as `X-Camera-Stream` and `X-Camera-Stream-Fallback`
+  alongside the existing `X-Camera-Snapshot-Cached`, so the fallback is explicit
+  rather than silent and a client can say "showing full resolution: this camera
+  has no low-bandwidth stream". A `nosub:<cameraId>` marker keeps the wasted
+  attempt to once per TTL, and a channel later given a sub-stream heals itself.
+
+  A refused credential, a timeout, a busy server, an oversized picture or a
+  missing ffmpeg never falls back - one attempt each, unchanged. Patrol evidence
+  (`hd: true`) already asks for the main stream and never enters the fallback.
+
+  Per-camera stream configuration is the better long-term answer but needs a
+  schema field, a form, an API surface and a migration for the existing cameras;
+  the automatic fallback needs no data change and is raised as a follow-up.
+
+- 2b23b62: 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.
+
+- 62e4eb6: 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.
+
+- 0af88b8: Add the staff console endpoints that set up, change and read back a client subscription, and the optional plan, start date, end date and billing mode fields they store.
+- 348fde3: Stop the dashboards reporting figures nothing measured, and stop a recorder
+  socket being reported as camera health.
+
+  Five values were being returned in a shape that made "we measured this" and "we
+  never measured this" indistinguishable. Each is now either computed from real
+  data or returned as an explicit `null` with a reason a client can show.
+
+  **Patrol Compliance showed 100% on a site with no patrol data.**
+  `complianceRate` fell back to `100` when the checkpoint total was 0, so a site
+  with no patrol logs drew the same tile a perfect week draws - and a failed
+  request drew 0%. `calculateComplianceRate` now returns `null` when no checkpoint
+  was due, alongside `patrolCompliance.checkpointsDue` and an
+  `unavailableReason`. The Virtual Patrol process itself is untouched; this is
+  reporting only.
+
+  **"0 high severity" was a hard-coded literal**, at `openIncidents.highSeverity`
+  in both the security and property dashboards, on every site, on every day. It
+  read as "we checked your incidents and none of them are serious". Incident
+  reports record no severity at all - `TIncidentReport` has no severity, priority
+  or criticality field, and the only `highPriority` flags in this package are on
+  work orders and feedbacks - so there is nothing to count. It now returns `null`
+  with `highSeverityUnavailableReason`. `highSeverityIncidentCount` counts rather
+  than hard-returning `null`, so the tile starts telling the truth on its own the
+  day the incident form records a severity. Nothing is guessed in the meantime.
+
+  **The trend percentage compared the wrong period, in the wrong timezone.** The
+  `+/-%` beside every KPI tile was always today-vs-yesterday even on the Week and
+  Month views, so a month's count sat next to a yesterday comparison, unlabelled.
+  And the day boundary came from `new Date()` + `setHours(0,0,0,0)` - the HOST's
+  midnight - while `formatEndDate` and the period range beside it force
+  Asia/Singapore. On a UTC container the two halves disagree by eight hours:
+  "today" silently loses SGT 00:00-08:00 while "yesterday" keeps its full 24, so
+  the comparison was biased before any data was counted.
+
+  `getPeriodRange` / `getPreviousPeriodRange` (new,
+  `src/utils/dashboard-metrics.util.ts`) state Asia/Singapore explicitly and take
+  an injectable clock. Week now compares against the previous ISO week and month
+  against the previous month, in all three dashboards plus the facility-booking
+  tile. The boundary is correct whatever the host is set to; the host's own `TZ`
+  still wants reading by someone with DigitalOcean access, but only to size the
+  damage already done.
+
+  **A missing prior period now yields no percentage.**
+  `calculatePercentageChange` returned `100` when the prior period was empty and
+  `0` when both were empty, so a first-ever record read as growth and a site where
+  nothing has ever happened read as measured stability. Both now return `null`.
+
+  **"Supply Alert" is not an alert.** The query is `sort by qty ascending, limit
+3` with no threshold, because `site.supplies` records no stock level to compare
+  against - no `minQty`, no `reorderLevel`, no `threshold`, on any model in this
+  package. 900 gloves appeared under a heading that said "alert". No threshold is
+  invented: the payload now carries `basis: "lowest-quantity"` and
+  `thresholdUnavailableReason` so no client can present the list as a low-stock
+  warning. The client already relabels the tile "Lowest Stock".
+
+  **Camera health was a socket on the recorder, presented as the camera's.**
+  `probeDevice` is a bare TCP connect to the recorder's RTSP port, cached per
+  recorder. That caching is deliberate and worth keeping - twelve channels on one
+  device is one connect, not twelve - but it means one dead camera among twelve
+  stayed invisible (the recorder still answers, so every channel returned
+  `reachable: true`, `health: "ok"`, `reason: null`), and a relay outage read as
+  twelve healthy tiles because the relay is never probed.
+
+  A true per-camera liveness check is not available on this path: it would mean an
+  authenticated per-channel RTSP frame grab for every tile on every sweep, which
+  is device contact this change is in no position to make or to test and is enough
+  of it to reach the recorder's own lockout. So none is faked. Every health answer
+  now carries `cameraHealthClaim` - `verified` (`"recorder-video-port"` or
+  `"nothing"`), a `verifiedDescription` sentence, and `cameraVerified` /
+  `relayVerified` as explicit `null`s - so the response states exactly what was
+  checked and cannot be read as a stronger claim. `health` and `reachable` keep
+  their existing values and meanings, so the web wall (which already labels this
+  "Recorder responding") and the mobile monitoring screen are unaffected. A camera
+  that resolves to no recorder reports `"nothing"` rather than a check that
+  failed, because no request left the server.
+
+  Nothing else in the health descriptor overstates itself: `firmwareVersion`,
+  `deviceTime` and `driftSeconds` already return `null` with
+  `detailUnavailableReason`, and capabilities already carry an explicit
+  `"unknown"` state with a reason.
+
+  **Response contract:** `patrolCompliance.count`, `openIncidents.highSeverity`
+  and every tile's `percentage` may now be `null`. Checked against the current
+  published client rather than assumed: `DashboardMain.vue` coerces through
+  `toNumber(value ?? 0)`, so nothing crashes and nothing prints "null". A `null`
+  percentage is coerced to 0, which `v-if="card.percentage"` treats as falsy, so
+  the trend pill correctly disappears - the intended behaviour, for free. But a
+  `null` compliance rate still draws "0%" and a `null` high-severity count still
+  draws "0 high severity" until the layer renders the not-available. So on a site
+  with no patrol data the tile moves from a fabricated 100% to a fabricated 0%
+  until that lands; both are wrong, and the API is now the half that is right.
+  The client-side half is `layer-common` #1229 (open).
+
+  Dead code removed as a consequence: the local `formatEndDate` and
+  `getSiteDayRange` in `new-dashboard.repo.ts` have no remaining callers.
+
+  Deliberately not changed: the duplicate current-period aggregations (the trend's
+  current-side query now matches the tile's own count query and could be dropped,
+  but that is an optimisation, not a correctness fix); the Dahua URL convention;
+  and the disabled device-control capabilities, which stay off.
+
+- f334ae3: Add dedicated physical HID card APIs for PACS and CSN credentials, including
+  manual assignment, reader enrollment, cancellation, verified removal, duplicate
+  protection, reader configuration checks, identity lookup metadata, and audited
+  device events.
+- 907df46: Hold property-manager service-provider invitations for Seven365 approval, and give an invitation a life
+
+  A property management company inviting a service provider used to reach that
+  provider immediately. It now waits for the Seven365 super admin, and the
+  provider is told nothing at all until it is approved — no email, no in-app
+  message, and the invitation is not even readable to them. Approval is the one
+  place an invitation reaches the provider, so there is a single function that can
+  leak an unapproved one. An invitation Seven365 sends itself is not held.
+
+  An invitation now has seven states instead of two: waiting for Seven365, waiting
+  for the provider, accepted, not approved (with a reason the property manager
+  sees word for word), declined, cancelled and expired. Every change goes through
+  one conditional update that moves the row only from an expected state and
+  appends an immutable history line in the same write — so approving or accepting
+  twice writes nothing the second time, and no path can move an invitation
+  silently. Deleting is a soft delete: the row leaves the property manager's list,
+  the record and its history stay and remain visible to Seven365.
+
+  Authorization, which this endpoint did not have: the caller is resolved from the
+  session and must belong to the organisation the invitation is sent for — being
+  signed in used to be enough to invite a provider to any organisation's site.
+  Approving and rejecting require the Seven365 super-admin membership (an org-less
+  `members` row of type `admin` whose role is also of type `admin`), not an email
+  address, so it behaves the same in staging and production.
+
+  An already-onboarded provider still never sees sign-up or a one-time code, and
+  the sign-up path for a brand-new company is unchanged.
+
+### Patch Changes
+
+- b5b41ea: 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.
+
+- 91ba6e8: 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.
+
+- 21d5d74: 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.
+
+- 8dea8b8: Give the Add / Edit Site form's property details somewhere to land.
+
+  The Organization app's Add Site form collects eight fields beyond the name,
+  category and address: MCST plan no., UEN, date of constitution, financial year
+  end, billing quarter, share capital, temporary occupation permit and
+  certificate of statutory. **None of them has ever been stored.** On create
+  `schemaCustomerSite` rejects any key it does not list, so sending them returns
+  400 - which is why the form quietly leaves them out of the request. On update
+  `updateCusSiteById` builds a whitelist of `name`, `address` and `category` and
+  drops the rest. The Edit dialog reads them back from the customer-site
+  document, so they display as empty every time.
+
+  Eight optional string fields are added to `schemaCustomerSite`, to
+  `TCustomerSite`, to the `MCustomerSite` projection, and to the update
+  whitelist. One exported list (`customerSitePropertyFields`) drives both the
+  create projection and the update whitelist, so the two cannot drift apart.
+
+  **Additive and optional only.** No migration, no backfill, no index change,
+  nothing written to any existing record. A field the caller did not send stays
+  absent from the document rather than being written as an empty string, so a
+  customer-site written before this change is byte-identical afterwards and still
+  validates. An empty string IS kept, because clearing a field on the Edit form
+  has to clear it. Unknown keys are still rejected on create - this widens the
+  allow-list, it does not open it.
+
+  Blast radius, checked across every repository in the organisation rather than
+  assumed: `POST /api/customer-sites` has exactly **one** caller in the estate
+  (`iservice365-web-app-org` `components/SiteForm.vue`) and `PUT
+/api/customer-sites/:id` has the same one. Every other consumer - all eleven
+  Nuxt apps via `layer-common`'s `useCustomerSite`, the resident app, the six
+  service-provider mobile apps, `iservice365-mobile-app-security` and
+  `isecure365-mobile-app` - only ever reads (`GET`), and reads name their fields
+  explicitly. `addViaInvite` sends none of the eight, so the invite-acceptance
+  path writes exactly the document it wrote before.
+
+  Covered by `test/customer-site-property-fields.test.mjs`, which asserts the
+  before-and-after shape both ways round: the details are accepted and survive
+  into the document, and a create without them still writes none of them.
+
+- 78a3053: Stop logging camera and mailer credentials
+
+  Six places wrote a secret or a resident's details to stdout on an ordinary code
+  path. `getTrafficJunction` dumped the whole `TSiteCamera` object — including the
+  camera's `username` and plaintext `password` — on every reconnect, and
+  `addPlateNumber` logged its argument, which carries the same password plus a
+  resident's plate number and owner name. `checkOutBySiteAndPlate` logged the
+  matched visitor transaction. `siteCameraRepo.updateById` logged the re-read
+  camera document, and `vehicleService.add` logged the whole array of a site's
+  cameras, both with credentials in them. `sendEmail` printed `MAILER_PASSWORD`
+  itself on every message sent.
+
+  All now log identifiers, counts and outcomes only, through the module's logger
+  rather than `console.log`; the mailer line is removed outright because it
+  carried nothing but the secret.
+
+- bbd97b4: Fix three Dahua HTTP API defects found by checking our integration against the
+  vendor specification (V3.37):
+
+  - The ANPR reconnect loop retried authentication ten times at one-second
+    intervals. The device locks the account for 1800 seconds after three failed
+    logins in thirty, so our own recovery could take ANPR down at a site for half
+    an hour. Authentication now backs off well past the device's counting window,
+    and a network fault is distinguished from an authentication failure.
+  - 401 and 403 were handled backwards. Per spec §3.4, 401 is the digest
+    challenge (retry) and 403 is a credentials rejection (stop). We treated 403 as
+    an account lock and killed the listener, and counted 401s toward a "wrong
+    password" warning.
+  - `updatePlateNumber`, `bulkInsertPlateNumber` and `removePlateNumber`
+    interpolated values into the CGI query string unencoded, against the spec's
+    stated RFC 3986 requirement. A plate or owner name containing a space or "&"
+    broke the request or appended extra parameters to it.
+
+- ac0c6e1: Resolve the seeded platform staff role by type as well as name, so the default staff account cannot be bound to an ordinary organisation role that happens to share the name.
+- ea2f1a3: HID Amico: authorise the card, PIN, discovery and visitor-QR endpoints
+
+  Ten HID Amico handlers required a session and nothing else. The reader id in
+  the URL was the only thing selecting the device, and `GET /readers` returns
+  every reader in the estate when no `site` is supplied, so any signed-in account
+  could act on any reader at any site of any organisation — assign or delete a
+  physical access card, set or clear a keypad PIN, put a reader into card
+  enrolment, list a user's stored card values, or revoke a visitor's QR pass.
+
+  Each of the ten now authorises before it does anything:
+
+  - `listUserCards`, `assignUserCard`, `enrollUserCard`, `cancelUserCardEnrollment`,
+    `deleteUserCard` and `revokeVisitorQr` require `site-settings:manage-entry-pass`
+    at the site of the **stored** reader.
+  - `getUserPinStatus`, `setUserPin` and `deleteUserPin` allow either that same
+    administrator, or the person whose own device user it is — entitlement to the
+    reader's site plus an ownership check on `hidUserId`, so the resident and MA
+    mobile apps' "Access PIN" screen keeps working while a neighbour's PIN cannot
+    be rewritten.
+  - `discoverReader` now takes the `site` the reader is being added to and
+    authorises it, and the address it may be pointed at is constrained: an
+    `http(s)` origin only, no credentials, no path, and never the API host itself
+    or the instance-metadata range. `HID_DISCOVERY_ALLOWED_HOSTS` optionally pins
+    it to named hosts; unset, nothing changes operationally.
+
+  A reader that is not yours answers exactly like a reader that does not exist, so
+  reader ids cannot be enumerated by watching the difference.
+
+  **Consumer change required:** `POST /access-management/hid/readers/discover` now
+  requires `site` in the body. `HidReaderForm.vue` in `@7365admin1/layer-common` is
+  the only caller and must be updated to send it.
+
+- db402eb: Add the notification categories the marketplace order flow needs, and a way to
+  offer a switch to a vendor organization's staff.
+
+  Every send funnels through `filterRecipients`, which hands back nobody when the
+  category key is not in the catalogue. There was no key for buying or selling, so
+  a marketplace order notification would have reached no one; and the existing
+  `prelovedMarketplace` key is the resident neighbour noticeboard, so reusing it
+  would have meant somebody muting a neighbour's bookshelf silently losing their
+  own order updates.
+
+  Two new keys, deliberately separate from each other and from the noticeboard:
+
+  - `marketplaceOrder` — "My Marketplace Orders", offered to residents, for the
+    buyer's own sub-order changes and the seller's replies.
+  - `marketplaceVendorOrder` — "Marketplace Sales", offered to members of an
+    organization that sells, for a new sub-order and the buyer's replies.
+
+  Selling is not granted by a role permission anywhere in the estate — it is a
+  flag on the organization (`organizations.isMarketplaceVendor`) — so there is no
+  permission resource that could carry the sales switch. `categoriesForPermissions`
+  gains an optional `isMarketplaceVendor` ground, the exact twin of the existing
+  `isResident`/`residentDefault` pair, and `categoriesForUser` resolves it from the
+  organizations the caller is already a member of. No permission string is
+  introduced and no role data changes.
+
+  Additive throughout: both new parameters default to false, so a caller that does
+  not pass them is offered precisely what it was offered before. No existing
+  category changed its key, label, channels, defaults or offered-set.
+
+  Both keys are `rendered: true`, so the switches exist the moment this is
+  published. The senders live in `iservice365-API-core` and follow immediately —
+  the two must reach staging in the same cycle, or the screen shows a switch that
+  governs nothing. Setting them `rendered: false` is the alternative, but then
+  nothing offers the switch while the senders CAN already deliver, which is the
+  worse of the two.
+
+- c99436e: Let a person choose which notifications they get, and enforce it where they are
+  sent.
+
+  Adds a `notification-preferences` collection (one row per user, storing only what
+  they switched OFF), a catalogue of what the product can notify about and on which
+  routes, and an authenticated pair of endpoints for reading and changing your own
+  settings — the user comes from the session, never from the request.
+
+  The guard runs inside `NotificationService.send`, so a switch actually stops the
+  message: the in-app copy and the phone alert are filtered independently. Somebody
+  with no saved row is never filtered, so behaviour is unchanged until they choose
+  to change it.
+
+  Two notice-board senders tag their messages `module: "feedback"`; they now pass
+  the honest category to the guard while leaving the stored tag alone, so switching
+  Feedback off does not silence the notice board.
+
+- ce464b2: Scope the notification inbox to the signed-in person.
+
+  Every handler on `/notifications` read the user id out of the query string or
+  the URL and acted on it without comparing it to the session, so any signed-in
+  account could list another person's notifications, mark them read, and read
+  their unread count. Whose inbox is opened now comes from the session; a request
+  naming somebody else is refused rather than quietly served.
+
+  `POST /notifications` writes into up to 5000 inboxes at once and had no
+  authorisation beyond being signed in. It now requires a Seven365 super admin.
+
+  The `user` parameter is still accepted, so no app has to be released in step
+  with this: every caller in the organisation already sends its own id.
+
+- 8266484: Fix defects in the occurrence-book and patrol modules, and move their day
+  windows to Singapore time
+
+  - Every day window in the occurrence-book and patrol queries is now
+    Asia/Singapore (UTC+8), midnight to midnight. Computed in UTC, a day ran
+    08:00–08:00 SGT, so an entry or a patrol scan logged at 00:30 fell into the
+    previous day and the guard who made it could not find it under "today".
+    Stored data and response shapes are unchanged; only the window moves.
+  - Occurrence-book date filter returned the previous day for `DD/MM/YYYY`
+    callers, and rejected the ISO form its own validation accepts.
+  - Occurrence-book pagination was collapsed to page one whenever a date filter
+    was set, while the response still reported the full page count.
+  - Occurrence-entry search by book number could never match, because `$regex`
+    was applied to the numeric `bookEntryCount`.
+  - `PUT /api/patrol-logs/id/:id` and `PUT /api/patrol-routes/id/:id` answered
+    HTTP 200 when the update matched no document, so a failed incident-report
+    attach was reported to the user as a success.
+  - Amending an occurrence entry whose subject or signature had been deleted
+    answered HTTP 500; and deleting an already-deleted patrol route answered
+    HTTP 500 instead of succeeding.
+
+- 6315a67: Promo codes: enforce expiry and disabled at redemption, and let staff edit, disable and remove a code
+- b762baf: Make the "an invitation is already waiting" check actually find the invitation
+
+  The duplicate-invitation guard added with the existing-provider invite fix never
+  fired. Invitations are written with `metadata.siteId` as an ObjectId, but the
+  lookup searched for the site id as the plain string it arrived as on the request,
+  and MongoDB does not treat the two as equal. The query therefore always came back
+  empty: a property manager could send the same service provider a second, third
+  and fourth invitation for the same site while the first was still valid, and each
+  one produced another email and another pending row for them to chase.
+
+  The lookup now matches either form, so older records that hold the string are
+  still found. Nothing else changes: the refusal message and the status code are
+  the ones already shipped.
+
+- d6c92d7: Stop rejecting site names that only differ by their building number
+
+  Adding a site refused any name within a Levenshtein distance of 2 of an
+  existing site in the same organisation, and told the user to contact support.
+  That is exactly one character, so "Winsland House II" could not be added next
+  to "Winsland House I". The same rule blocked "Tower A" beside "Tower B",
+  "Phase 2" beside "Phase 1" and "Block 15" beside "Block 5" — the standard way
+  buildings are named here.
+
+  The check now treats trailing numbers, Roman numerals and single letters as the
+  part that tells two buildings apart: if they differ, the names are different
+  sites and the distance is never measured. Real duplicates are still refused —
+  an exact repeat, a different capitalisation, stray or doubled whitespace,
+  punctuation-only differences, and a one or two character typo within the same
+  building. "House 1" and "House I" are still read as the same building.
+
+  The refusal now names the site it matched and says what to do about it instead
+  of pointing the user at support.
+
+  `site.repo.getByExactName` also built its case-insensitive regex from the raw
+  name; a name containing regex characters either threw or matched a site it is
+  not. It is escaped.
+
+- b803f36: Staff console authorization: subscriptions, plans, promo codes, client status and platform Terms now require a Seven365 staff membership
+
+  The organisation, subscription, subscription-plan, promo-code and platform-terms
+  controllers checked only that a session existed, so every write behind the
+  Seven365 staff console was reachable by any signed-in account on the platform.
+
+  - `requirePlatformStaff` (new `src/utils/console-authz.util.ts`) gates the writes
+    that are ours to make: creating an organisation, suspending or reactivating a
+    client, the plan catalogue, minting a promo code, and publishing platform-wide
+    Terms. It reuses `isSuperAdmin` — a `members` row of type "admin" whose role is
+    also of type "admin" — the same check SP Approvals, Marketplace Vendors and the
+    notification broadcast already use. No role-name string takes part.
+  - `requireOrgAccess` gates the two writes a client legitimately makes on their
+    own account — editing their organisation during onboarding, and changing the
+    seat count on their own subscription. The organisation is read off the stored
+    subscription, never off the request.
+  - `POST /terms` took `createdBy` from the request body; it is now the session, so
+    published Terms can no longer be attributed to somebody else. The `user` field
+    is still accepted and ignored, so no application has to be released in step.
+  - The two `organizations/v2` reads page over every organisation on the platform
+    with its subscription and billing data; they are gated to staff for the same
+    reason.
+
+  The paid signup checkout and self-signup organisation creation are deliberately
+  left open — they are customer paths, and a test pins them that way.
+
+- 2e0b41a: Terms acceptance: gate the per-user status and accept handlers to the person themselves
+
 ## 3.46.0
 
 ### Minor Changes