feat: deliver Sense audits to Bell (T-016)

2026-08-11 00:24:32 +08:00
parent aca22f4667
commit 4be2386421
35 changed files with 2188 additions and 42 deletions
@@ -0,0 +1,94 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "YoVision Sense Audit Relay",
+    "version": "1.0.0",
+    "description": "Internal, signed and idempotent delivery of redacted Sense device audit facts to Bell."
+  },
+  "paths": {
+    "/internal/v1/audit-events:batch": {
+      "post": {
+        "operationId": "receiveSenseAuditBatch",
+        "description": "Accepts 1-100 events in a body no larger than 1048576 bytes. The request deadline is 10 seconds. HMAC clock skew is at most 300 seconds and nonce receipts live for 600 seconds.",
+        "parameters": [
+          {"name": "X-YoVision-Key-Id", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"}},
+          {"name": "X-YoVision-Timestamp", "in": "header", "required": true, "description": "Unix seconds", "schema": {"type": "string", "pattern": "^[0-9]{10,}$"}},
+          {"name": "X-YoVision-Nonce", "in": "header", "required": true, "description": "16-48 random bytes encoded as unpadded base64url", "schema": {"type": "string", "minLength": 22, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$"}},
+          {"name": "X-YoVision-Signature", "in": "header", "required": true, "description": "Unpadded base64url HMAC-SHA256 over POST, path, timestamp, nonce and lowercase SHA-256 body digest joined by newlines", "schema": {"type": "string", "minLength": 43, "maxLength": 43}}
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BatchRequest"}}}
+        },
+        "responses": {
+          "200": {"description": "Stored, duplicate or permanently rejected per item. Same key ID, nonce and request digest returns the original response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BatchResponse"}}}},
+          "400": {"description": "Malformed batch envelope"},
+          "401": {"description": "Invalid key, timestamp, nonce or signature"},
+          "409": {"description": "Same key ID and nonce used with a different request digest; error is replay_conflict"},
+          "413": {"description": "Body exceeds 1048576 bytes"},
+          "503": {"description": "Bell cannot atomically persist the batch and receipt"}
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "BatchRequest": {
+        "type": "object", "additionalProperties": false, "required": ["events"],
+        "properties": {"events": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"$ref": "#/components/schemas/Envelope"}}}
+      },
+      "Envelope": {
+        "type": "object", "additionalProperties": false, "required": ["schema_version", "event"],
+        "properties": {
+          "schema_version": {"type": "integer", "enum": [1, 2]},
+          "event": {"$ref": "#/components/schemas/AuditEvent"}
+        }
+      },
+      "AuditEvent": {
+        "type": "object", "additionalProperties": false,
+        "required": ["event_id", "event_type", "tenant_id", "site_id", "device_id", "actor", "reason", "trace_id", "aggregate_generation", "projection_versions", "data", "occurred_at"],
+        "properties": {
+          "event_id": {"type": "string", "pattern": "^audit_[0-9a-f]{32}$"},
+          "event_type": {"type": "string", "enum": ["device.created", "device.desired_state.accepted", "device.configuration.accepted"]},
+          "tenant_id": {"$ref": "#/components/schemas/LogicalId"},
+          "site_id": {"$ref": "#/components/schemas/LogicalId"},
+          "device_id": {"$ref": "#/components/schemas/LogicalId"},
+          "actor": {"type": "object", "additionalProperties": false, "required": ["type", "id"], "properties": {"type": {"type": "string", "enum": ["user", "service", "system"]}, "id": {"type": "string", "minLength": 1, "maxLength": 200}}},
+          "reason": {"type": ["string", "null"], "maxLength": 500},
+          "trace_id": {"type": ["string", "null"], "maxLength": 128},
+          "aggregate_generation": {"type": "integer", "minimum": 1},
+          "projection_versions": {"type": "object", "additionalProperties": false, "required": ["quota_source_version", "area_policy_source_version"], "properties": {"quota_source_version": {"type": ["integer", "null"], "minimum": 1}, "area_policy_source_version": {"type": ["integer", "null"], "minimum": 1}}},
+          "data": {"type": "object"},
+          "occurred_at": {"type": "string", "format": "date-time"}
+        }
+      },
+      "LogicalId": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"},
+      "BatchResponse": {
+        "type": "object", "additionalProperties": false, "required": ["results"],
+        "properties": {"results": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"$ref": "#/components/schemas/Result"}}}
+      },
+      "Result": {
+        "type": "object", "additionalProperties": false, "required": ["event_id", "status"],
+        "properties": {
+          "event_id": {"type": "string"},
+          "status": {"type": "string", "enum": ["accepted", "duplicate", "rejected"]},
+          "error_code": {"type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$"}
+        }
+      }
+    }
+  },
+  "x-yovision-signature": {
+    "canonical": "METHOD\\nPATH\\nTIMESTAMP\\nNONCE\\nLOWERCASE_SHA256_BODY",
+    "algorithm": "HMAC-SHA256",
+    "encoding": "base64url-no-padding",
+    "clock_skew_seconds": 300,
+    "receipt_ttl_seconds": 600
+  },
+  "x-yovision-delivery": {
+    "lease_seconds": 30,
+    "initial_retry_seconds": 1,
+    "maximum_retry_seconds": 300,
+    "successful_statuses": ["accepted", "duplicate"],
+    "permanent_status": "rejected"
+  }
+}