PK-261005-002 · Milestone XProtect — API Gateway

• CHANGELOG.md331 B
• README.md2,674 B
• config/config.example.json431 B
• config/config.schema.json1,765 B
• fixtures/events.jsonl602 B
• fixtures/expected.json136 B
• manifest.json2,720 B
• mapping/event-map.json952 B
• src/Connector.php5,753 B
• src/Transport.php2,856 B
• tests/SandboxTest.php2,039 B
• SHA256SUMS

1# Milestone XProtect — API Gateway
2
3**Build** `PK-261005-002` · **Version** `0.1.2` · **Target site** Oxford Hills Comprehensive High School · **Mode** READ-ONLY
4
5Generated by Integration Bot (tpl-r4) for the MSAD 17 Security Platform.
6After promotion this package is owned and operated by **District IT**. There is no vendor or developer service contract behind it.
7
8## What it does
9- Protocol: REST (JSON) · OAuth2 via XProtect IDP · Events & State WebSocket
10- Capabilities: inventory, health, live_uri, playback_uri, events
11- Normalizes vendor events to `msad17.event/1` (the same taxonomy the alarm queue uses)
12
13## Endpoints called (egress is limited to these)
14| Method | Path | Purpose |
15|---|---|---|
16| `POST` | `/API/IDP/connect/token` | OAuth2 token (XProtect basic user) |
17| `GET` | `/api/rest/v1/cameras` | Camera inventory → registry reconciliation |
18| `GET` | `/api/rest/v1/recordingServers` | Recorder inventory / status |
19| `GET` | `/api/ws/events/v1` | Events & State stream |
20
21## Event mapping
22| Vendor key | Platform type | Priority | Meaning |
23|---|---|---|---|
24| `Motion Started` | `video.motion` | INFO | Motion (after hours zone) |
25| `Communication Error` | `video.loss` | P2 | Video loss |
26| `Tampering` | `video.tamper` | P2 | Camera tamper / scene change |
27| `Recording Storage Full` | `recorder.retention` | P3 | Retention below target |
28
29Unmapped vendor events are **counted and reported** on the Health page — never silently dropped. Add a row to `mapping/event-map.json`, rebuild, re-run sandbox.
30
31## Secrets
32This package contains **no credentials**. Configure these references in the platform secret store:
33- `${secret:msad17/ohchs/xprotect/username}`
34- `${secret:msad17/ohchs/xprotect/password}`
35
36## Install / verify (District IT)
371. Integration Bot → this build → **Run sandbox** (no network; fixtures only). Expect 3 mapped / 1 unmapped.
382. Optional offline check on any PHP 8.2+ box: `php tests/SandboxTest.php` → `SANDBOX PASS`.
393. Verify integrity: `sha256sum -c SHA256SUMS`.
404. **Approve** (reviewer 1) → **Promote** (reviewer 2, must differ). Promotion registers the connector read-only.
415. On the VPS runtime, point `config.base_url` at a **lab device first**, confirm events on the alarm queue, then widen `device_map`.
42
43## Rollback
44Demote this build in Integration Bot. The previously promoted build for this stack re-activates. Nothing on the device is changed by install or rollback.
45
46## Licensing / compliance
47Uses existing XProtect basic user; no extra SDK license for API Gateway REST.
48
49## Notes
50Event type names are site-configurable in XProtect — IT confirms names against Management Client before promote.