This commit is contained in:
2026-05-12 19:25:14 +02:00
commit 0f3173d93e
93 changed files with 11865 additions and 0 deletions
+949
View File
@@ -0,0 +1,949 @@
{
"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"
}
]
}