From 51468b0e82ab0cec7d08b8e8e3659afd3d5692ae Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Mon, 27 Jan 2025 16:50:51 +0100
Subject: [PATCH] Mention password policies for MySQL users in all appropriate
 places

---
 docs/api/security/_category_.json  |  7 +++++++
 docs/api/security/passwords.md     | 18 ++++++++++++++++++
 generator/overlays/v2/overlay.yaml | 17 +++++++++++++++++
 3 files changed, 42 insertions(+)
 create mode 100644 docs/api/security/_category_.json
 create mode 100644 docs/api/security/passwords.md

diff --git a/docs/api/security/_category_.json b/docs/api/security/_category_.json
new file mode 100644
index 0000000..0a10b98
--- /dev/null
+++ b/docs/api/security/_category_.json
@@ -0,0 +1,7 @@
+{
+  "label": "API security",
+  "position": 10,
+  "link": {
+    "type": "generated-index"
+  }
+}
diff --git a/docs/api/security/passwords.md b/docs/api/security/passwords.md
new file mode 100644
index 0000000..f56b18e
--- /dev/null
+++ b/docs/api/security/passwords.md
@@ -0,0 +1,18 @@
+# Password security
+
+<!--
+NOTE: This document is linked from various places with in the API reference.
+DO NOT change the document ID or the header IDs
+-->
+
+Various API calls enforce password policies. This document serves as a reference for different password policies enforced by the mStudio API.
+
+## MySQL user passwords {#mysql}
+
+Passwords for MySQL users must fulfill the following requirements:
+
+- at least 8 characters
+- at least one lowercase character
+- at least one uppercase character
+- at least one digit
+- at least one special character out of `#!~%^*_+-=?{}()<>|.,;`
diff --git a/generator/overlays/v2/overlay.yaml b/generator/overlays/v2/overlay.yaml
index 422bfcd..0fe419d 100644
--- a/generator/overlays/v2/overlay.yaml
+++ b/generator/overlays/v2/overlay.yaml
@@ -14,6 +14,14 @@ actions:
       accessIpMask:
         description: An IP range (in CIDR notation) for which access should be allowed.
         example: "203.0.113.123/32"
+      externalAccess:
+        description: >
+          Describes if users should be able to connection to this database from external
+          sources. Defaults to `false` when not set.
+      password:
+        description: >
+          The password for the database user. This password has to comply with the password
+          policy specified for MySQL users in the [password security specification](/docs/v2/api/security/passwords#mysql).
   - target: $.components.schemas['de.mittwald.v1.database.CreateMySqlUserWithDatabase'].properties.accessIpMask
     remove: true
   - target: $.components.schemas['de.mittwald.v1.database.CreateMySqlUserWithDatabase'].properties
@@ -22,6 +30,10 @@ actions:
         description: >
           Describes if users should be able to connection to this database from external
           sources. Defaults to `false` when not set.
+      password:
+        description: >
+          The password for the database user. This password has to comply with the password
+          policy specified for MySQL users in the [password security specification](/docs/v2/api/security/passwords#mysql).
   - target: $.components.schemas['de.mittwald.v1.database.characterSettings'].properties
     update:
       characterSet:
@@ -30,6 +42,11 @@ actions:
       collation:
         description: A valid MySQL collation
         example: utf8mb4_general_ci
+  - target: $.paths['/v2/mysql-users/{mysqlUserId}/password'].patch.requestBody.content['application/json'].schema.properties.password
+    update:
+      description: >
+        The password for the database user. This password has to comply with the password
+        policy specified for MySQL users in the [password security specification](/docs/v2/api/security/passwords#mysql).
 
   - target: $.paths['/v2/dns-zones/{dnsZoneId}/record-sets/{recordSet}'].put.parameters[?(@.name=="recordSet")]
     update: