{ "openapi": "3.1.0", "info": { "title": "smgw-pki-automator", "description": "Control + observation surface for the SMGW PKI automation tool. Test/lab use only.", "license": { "name": "" }, "version": "0.1.0" }, "paths": { "/alerts": { "get": { "tags": [ "alerts" ], "operationId": "list_alerts", "responses": { "200": { "description": "Recent alerts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertListResponse" } } } } } } }, "/alerts/test": { "post": { "tags": [ "alerts" ], "operationId": "send_test_alert", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestAlertRequest" } } }, "required": true }, "responses": { "200": { "description": "Sent (or stub-logged)" } } } }, "/auth/me": { "get": { "tags": [ "auth" ], "summary": "Inspect the current session.", "operationId": "whoami", "responses": { "200": { "description": "Current session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "401": { "description": "No active session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/auth/session": { "post": { "tags": [ "auth" ], "summary": "Exchange mTLS client cert (passed via `X-Forwarded-Cert-Subject`) for a\nserver-issued session cookie. The reverse proxy terminating mTLS is the\ntrust anchor.", "operationId": "create_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Session issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "403": { "description": "No client cert subject", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "auth" ], "summary": "Revoke the current session and clear cookie.", "operationId": "end_session", "responses": { "204": { "description": "Session ended" } } } }, "/certs": { "get": { "tags": [ "certs" ], "summary": "List all known end-entity certificates with derived state.", "operationId": "list_certificates", "responses": { "200": { "description": "Certificates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertListResponse" } } } } } } }, "/certs/{gateway_id}/{usage}/renew": { "post": { "tags": [ "certs" ], "summary": "Trigger an out-of-band renewal for a specific (gateway, usage) pair.\nReturns the SOAP `messageID` so the caller can correlate the async callback.", "operationId": "renew_certificate", "parameters": [ { "name": "gateway_id", "in": "path", "description": "Gateway identifier", "required": true, "schema": { "type": "string" } }, { "name": "usage", "in": "path", "description": "Certificate usage", "required": true, "schema": { "$ref": "#/components/schemas/CertificateUsageDto" } } ], "responses": { "202": { "description": "Renewal accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewAccepted" } } } }, "501": { "description": "Sub-CA adapter not implemented yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/config": { "get": { "tags": [ "config" ], "operationId": "get_config", "responses": { "200": { "description": "Current runtime config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigView" } } } } } }, "put": { "tags": [ "config" ], "operationId": "update_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigUpdate" } } }, "required": true }, "responses": { "200": { "description": "Updated runtime config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigView" } } } } } } }, "/gateways": { "get": { "tags": [ "gateways" ], "operationId": "list_gateways", "responses": { "200": { "description": "Gateways", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayListResponse" } } } } } } }, "/iconfig/build": { "post": { "tags": [ "iconfig" ], "summary": "Build, sign via HSM, and stream back `iconfig.tar`.", "operationId": "build_iconfig", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IconfigRequest" } } }, "required": true }, "responses": { "200": { "description": "iconfig.tar", "content": { "application/x-tar": {} } }, "501": { "description": "HSM signature not implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/iconfig/preview": { "post": { "tags": [ "iconfig" ], "summary": "Render the unsigned `iconfig.xml` for review. Does not touch the HSM.", "operationId": "preview_iconfig", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IconfigRequest" } } }, "required": true }, "responses": { "200": { "description": "Preview XML", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IconfigPreview" } } } } } } }, "/scheduler": { "get": { "tags": [ "scheduler" ], "operationId": "get_status", "responses": { "200": { "description": "Scheduler state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchedulerState" } } } } } } }, "/scheduler/pause": { "post": { "tags": [ "scheduler" ], "operationId": "set_paused", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PauseRequest" } } }, "required": true }, "responses": { "200": { "description": "Pause state updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchedulerState" } } } } } } }, "/scheduler/trigger": { "post": { "tags": [ "scheduler" ], "summary": "Run renewal once, out of band. Honours the same overlap-lock as the cron job.", "operationId": "trigger_run", "responses": { "202": { "description": "Run accepted" }, "409": { "description": "Run already in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "schemas": { "AlertEntry": { "type": "object", "required": [ "at", "severity", "subject", "body" ], "properties": { "at": { "type": "string", "format": "date-time" }, "body": { "type": "string" }, "severity": { "$ref": "#/components/schemas/AlertSeverity" }, "subject": { "type": "string" } } }, "AlertListResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AlertEntry" } } } }, "AlertSeverity": { "type": "string", "enum": [ "info", "warning", "error" ] }, "ApiError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "CertListResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CertificateDto" } } } }, "CertState": { "type": "string", "enum": [ "valid", "expiring", "expired" ] }, "CertificateDto": { "type": "object", "required": [ "gateway_id", "serial", "usage", "not_before", "not_after", "days_to_expiry", "state" ], "properties": { "days_to_expiry": { "type": "integer", "format": "int64" }, "gateway_id": { "type": "string" }, "not_after": { "type": "string", "format": "date-time" }, "not_before": { "type": "string", "format": "date-time" }, "serial": { "type": "string" }, "state": { "$ref": "#/components/schemas/CertState" }, "usage": { "$ref": "#/components/schemas/CertificateUsageDto" } } }, "CertificateUsageDto": { "type": "string", "enum": [ "tls", "signature", "encryption" ] }, "ConfigUpdate": { "type": "object", "properties": { "cron_schedule": { "type": [ "string", "null" ] }, "days_window": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "hsm": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HsmConfig" } ] }, "smtp": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SmtpConfig" } ] }, "sub_ca": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubCaConfig" } ] } } }, "ConfigView": { "type": "object", "required": [ "config", "restart_required_fields" ], "properties": { "config": { "$ref": "#/components/schemas/RuntimeConfig" }, "restart_required_fields": { "type": "array", "items": { "type": "string" } } } }, "GatewayDto": { "type": "object", "required": [ "id", "serial_number", "admin_key_label" ], "properties": { "admin_key_label": { "type": "string" }, "id": { "type": "string" }, "serial_number": { "type": "string" } } }, "GatewayListResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayDto" } } } }, "HsmConfig": { "type": "object", "required": [ "module_path", "pin_env_var" ], "properties": { "module_path": { "type": "string" }, "pin_env_var": { "type": "string" }, "slot": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "IconfigPreview": { "type": "object", "required": [ "xml" ], "properties": { "xml": { "type": "string" } } }, "IconfigRequest": { "type": "object", "required": [ "gateway_id", "admin_key_label", "profile" ], "properties": { "admin_key_label": { "type": "string" }, "extras": {}, "gateway_id": { "type": "string" }, "profile": { "type": "string" } } }, "LoginRequest": { "type": "object", "properties": { "dev_subject": { "type": [ "string", "null" ], "description": "Optional fallback subject for dev mode when no mTLS header is present." } } }, "PauseRequest": { "type": "object", "required": [ "paused" ], "properties": { "paused": { "type": "boolean" } } }, "RenewAccepted": { "type": "object", "required": [ "message_id" ], "properties": { "message_id": { "type": "string" } } }, "RuntimeConfig": { "type": "object", "description": "Mutable runtime config. Seeded from env on boot; UI may override at runtime\nfor fields flagged `hot_reload`. Restart-only fields (BIND_ADDR) are read\nbut cannot be applied without restart.", "required": [ "bind_addr", "cron_schedule", "days_window", "database_url", "sub_ca", "smtp", "hsm" ], "properties": { "bind_addr": { "type": "string" }, "cron_schedule": { "type": "string" }, "database_url": { "type": "string" }, "days_window": { "type": "integer", "format": "int32", "minimum": 0 }, "hsm": { "$ref": "#/components/schemas/HsmConfig" }, "smtp": { "$ref": "#/components/schemas/SmtpConfig" }, "sub_ca": { "$ref": "#/components/schemas/SubCaConfig" } } }, "SchedulerState": { "type": "object", "required": [ "cron_schedule", "days_window", "paused" ], "properties": { "cron_schedule": { "type": "string" }, "days_window": { "type": "integer", "format": "int32", "minimum": 0 }, "last_error": { "type": [ "string", "null" ] }, "last_handled": { "type": [ "integer", "null" ], "minimum": 0 }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_run_ok": { "type": [ "boolean", "null" ] }, "paused": { "type": "boolean" } } }, "SessionResponse": { "type": "object", "required": [ "subject", "expires_at" ], "properties": { "expires_at": { "type": "string", "format": "date-time" }, "subject": { "type": "string" } } }, "SmtpConfig": { "type": "object", "required": [ "host", "port", "from", "to", "starttls" ], "properties": { "from": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer", "format": "int32", "minimum": 0 }, "starttls": { "type": "boolean" }, "to": { "type": "string" } } }, "SubCaConfig": { "type": "object", "required": [ "endpoint" ], "properties": { "ca_bundle_path": { "type": [ "string", "null" ] }, "client_cert_path": { "type": [ "string", "null" ] }, "client_key_path": { "type": [ "string", "null" ] }, "endpoint": { "type": "string" } } }, "TestAlertRequest": { "type": "object", "properties": { "body": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] } } } } }, "tags": [ { "name": "auth", "description": "mTLS-bridged session management" }, { "name": "certs", "description": "Certificate lifecycle" }, { "name": "gateways", "description": "Smart Meter Gateways" }, { "name": "config", "description": "Runtime configuration" }, { "name": "scheduler", "description": "Renewal scheduler" }, { "name": "iconfig", "description": "BSI TR-03109-1 initial config" }, { "name": "alerts", "description": "Operator alerts" } ] }