Accept and echo Octi-Device-Capabilities header

Adds support for a new per-device capability tag set published by clients via the Octi-Device-Capabilities HTTP header. The server is a dumb pipe — it parses, validates (max 64 tags, 128 chars each, ASCII namespace:value shape), stores per device, and echoes back in the device-list response. No knowledge of tag semantics required.

Honored on every state-updating authenticated request that already updates version/platform/label: register, heartbeat (via touchAuthenticatedDevice), WebSocket connect. Absent header = no update (matches the existing pattern for label/version/platform). Malformed headers are dropped (treated as absent) with a WARN log; entire set is rejected on any bad tag for wire-format consistency.

Activates the client-side capability mechanism shipped in octi#309. Until clients send the header, this is a no-op; once they do, the data flows end-to-end. CORS allowlist updated so SPAs can send the header in preflight.

Author: d4rken

src/main/kotlin/eu/darken/octi/server/Server.kt

@@ -96,6 +96,7 @@ class Server @Inject constructor(
                     allowHeader("Octi-Device-Version")
                     allowHeader("Octi-Device-Platform")
                     allowHeader("Octi-Device-Label")
+                    allowHeader("Octi-Device-Capabilities")
                     allowHeader("Upload-Offset")
                     exposeHeader(HttpHeaders.ETag)
                     exposeHeader(HttpHeaders.LastModified)

src/main/kotlin/eu/darken/octi/server/account/AccountRoute.kt

@@ -10,6 +10,7 @@ import eu.darken.octi.server.common.debug.logging.logTag
 import eu.darken.octi.server.common.debug.logging.shortId
 import eu.darken.octi.server.common.headerDeviceId
 import eu.darken.octi.server.common.normalizeLabel
+import eu.darken.octi.server.common.parseCapabilitiesHeader
 import eu.darken.octi.server.common.verifyCaller
 import eu.darken.octi.server.device.DeviceClientIdentityTracker
 import eu.darken.octi.server.device.DeviceLimitExceededException
@@ -96,6 +97,7 @@ class AccountRoute @Inject constructor(
                 version = call.request.headers["Octi-Device-Version"] ?: call.request.headers["User-Agent"],
                 platform = call.request.headers["Octi-Device-Platform"],
                 label = normalizeLabel(call.request.headers["Octi-Device-Label"]),
+                capabilities = parseCapabilitiesHeader(call.request.headers["Octi-Device-Capabilities"]),
             )
         } catch (e: DeviceLimitExceededException) {
             if (share != null) {

src/main/kotlin/eu/darken/octi/server/common/HttpExtensions.kt

@@ -15,6 +15,10 @@ import io.ktor.server.request.*
 import io.ktor.server.response.*
 import io.ktor.server.routing.*
 import io.ktor.util.*
+import kotlinx.serialization.SerializationException
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonPrimitive
 import java.time.Instant
 import java.util.*
 
@@ -45,10 +49,62 @@ data class DeviceMetadataPatch(
     val version: String? = null,
     val platform: String? = null,
     val label: String? = null,
+    val capabilities: Set<String>? = null,
 )
 
 fun normalizeLabel(raw: String?): String? = raw?.trim()?.take(128)?.ifBlank { null }
 
+private val capabilityParseJson = Json { ignoreUnknownKeys = true }
+
+/**
+ * Parses the `Octi-Device-Capabilities` HTTP header value into a validated [Set] of tag
+ * strings. Mirrors the validation in the client-side `CapabilitiesCodec`: max [MAX_CAPABILITY_TAGS]
+ * tags, max [MAX_CAPABILITY_TAG_LENGTH] chars each, ASCII `<namespace>:<value>` shape.
+ *
+ * Returns `null` if the header is absent, blank, malformed, or violates a limit — the device
+ * is treated as not reporting capabilities. Drops the whole set on any bad tag (no partial
+ * acceptance) so peers see a consistent "either valid or absent" wire contract.
+ */
+fun parseCapabilitiesHeader(raw: String?): Set<String>? {
+    if (raw.isNullOrBlank()) return null
+    if (raw.length > MAX_CAPABILITY_HEADER_LENGTH) {
+        log(TAG, WARN) { "parseCapabilitiesHeader: header too long (${raw.length})" }
+        return null
+    }
+    val element = try {
+        capabilityParseJson.parseToJsonElement(raw)
+    } catch (e: SerializationException) {
+        log(TAG, WARN) { "parseCapabilitiesHeader: malformed JSON: ${e.message}" }
+        return null
+    }
+    val array = element as? JsonArray ?: run {
+        log(TAG, WARN) { "parseCapabilitiesHeader: not a JSON array" }
+        return null
+    }
+    if (array.size > MAX_CAPABILITY_TAGS) {
+        log(TAG, WARN) { "parseCapabilitiesHeader: too many tags (${array.size})" }
+        return null
+    }
+    val result = LinkedHashSet<String>(array.size.coerceAtLeast(1))
+    for (item in array) {
+        val str = (item as? JsonPrimitive)?.takeIf { it.isString }?.content ?: run {
+            log(TAG, WARN) { "parseCapabilitiesHeader: non-string element" }
+            return null
+        }
+        if (str.length > MAX_CAPABILITY_TAG_LENGTH || !CAPABILITY_TAG_REGEX.matches(str)) {
+            log(TAG, WARN) { "parseCapabilitiesHeader: invalid tag shape '$str'" }
+            return null
+        }
+        result.add(str)
+    }
+    return result
+}
+
+const val MAX_CAPABILITY_TAGS = 64
+const val MAX_CAPABILITY_TAG_LENGTH = 128
+const val MAX_CAPABILITY_HEADER_LENGTH = 4096
+val CAPABILITY_TAG_REGEX = Regex("""[a-z][a-z0-9]*:[A-Za-z0-9._\-]+""")
+
 /**
  * Validates the auth headers and returns the device on success — no side effects.
  * Use [touchAuthenticatedDevice] to record lastSeen/IP after the per-account rate
@@ -110,6 +166,7 @@ suspend fun touchAuthenticatedDevice(
         metadata?.version?.let { v -> updated = updated.copy(version = v) }
         metadata?.platform?.let { p -> updated = updated.copy(platform = p) }
         metadata?.label?.let { l -> updated = updated.copy(label = l) }
+        metadata?.capabilities?.let { c -> updated = updated.copy(capabilities = c) }
         updated
     }
     if (clientIp != null && ipTracker != null) {
@@ -191,6 +248,7 @@ suspend fun RoutingContext.verifyCaller(tag: String, deviceRepo: DeviceRepo): De
             version = call.request.header("Octi-Device-Version"),
             platform = call.request.header("Octi-Device-Platform"),
             label = normalizeLabel(call.request.header("Octi-Device-Label")),
+            capabilities = parseCapabilitiesHeader(call.request.header("Octi-Device-Capabilities")),
         ),
     )
 }

src/main/kotlin/eu/darken/octi/server/device/Device.kt

@@ -43,6 +43,9 @@ data class Device(
     val label: String?
         get() = data.label
 
+    val capabilities: Set<String>?
+        get() = data.capabilities
+
     val addedAt: Instant
         get() = data.addedAt
 
@@ -56,6 +59,13 @@ data class Device(
         val version: String? = null,
         val platform: String? = null,
         val label: String? = null,
+        /**
+         * Feature capability tags published by the device, format `<namespace>:<value>`
+         * (e.g. `encryption:AES256_GCM_SIV`). Opaque to the server — stored and echoed
+         * as-is. `null` = device hasn't reported capabilities; an empty set = device
+         * explicitly reports no capabilities. See [eu.darken.octi.server.common.parseCapabilitiesHeader].
+         */
+        val capabilities: Set<String>? = null,
         @Contextual val addedAt: Instant = Instant.now(),
         @Contextual val lastSeen: Instant = Instant.now(),
     ) {

src/main/kotlin/eu/darken/octi/server/device/DeviceRepo.kt

@@ -141,12 +141,14 @@ class DeviceRepo @Inject constructor(
         version: String?,
         platform: String? = null,
         label: String? = null,
+        capabilities: Set<String>? = null,
     ): Device {
         val data = Device.Data(
             id = deviceId,
             version = version,
             platform = platform,
             label = label,
+            capabilities = capabilities,
         )
         val device = Device(
             data = data,

src/main/kotlin/eu/darken/octi/server/device/DeviceRoute.kt

@@ -74,6 +74,7 @@ class DeviceRoute @Inject constructor(
                     version = it.version,
                     platform = it.platform,
                     label = it.label,
+                    capabilities = it.capabilities,
                     addedAt = it.addedAt,
                     lastSeen = it.lastSeen,
                 )

src/main/kotlin/eu/darken/octi/server/device/DevicesResponse.kt

@@ -15,7 +15,8 @@ data class DevicesResponse(
         @SerialName("version") val version: String?,
         @SerialName("platform") val platform: String?,
         @SerialName("label") val label: String?,
+        @SerialName("capabilities") val capabilities: Set<String>? = null,
         @Contextual @SerialName("addedAt") val addedAt: Instant,
         @Contextual @SerialName("lastSeen") val lastSeen: Instant,
     )
-}
+}

src/main/kotlin/eu/darken/octi/server/ws/WsRoute.kt

@@ -8,6 +8,7 @@ import eu.darken.octi.server.common.IpDeviceTracker
 import eu.darken.octi.server.common.authenticateDevice
 import eu.darken.octi.server.common.clientIp
 import eu.darken.octi.server.common.normalizeLabel
+import eu.darken.octi.server.common.parseCapabilitiesHeader
 import eu.darken.octi.server.common.touchAuthenticatedDevice
 import eu.darken.octi.server.common.debug.logging.Logging.Priority.INFO
 import eu.darken.octi.server.common.debug.logging.Logging.Priority.WARN
@@ -80,6 +81,7 @@ class WsRoute @Inject constructor(
                     version = call.request.headers["Octi-Device-Version"],
                     platform = call.request.headers["Octi-Device-Platform"],
                     label = normalizeLabel(call.request.headers["Octi-Device-Label"]),
+                    capabilities = parseCapabilitiesHeader(call.request.headers["Octi-Device-Capabilities"]),
                 ),
             )
 

src/test/kotlin/eu/darken/octi/TestRunnerExtensions.kt

@@ -59,6 +59,7 @@ suspend fun TestEnvironment.createDeviceRaw(
     version: String? = null,
     platform: String? = null,
     label: String? = null,
+    capabilities: String? = null,
     userAgent: String? = null,
 ): HttpResponse = this.http.run {
     post {
@@ -70,6 +71,7 @@ suspend fun TestEnvironment.createDeviceRaw(
         if (version != null) headers.append("Octi-Device-Version", version)
         if (platform != null) headers.append("Octi-Device-Platform", platform)
         if (label != null) headers.append("Octi-Device-Label", label)
+        if (capabilities != null) headers.append("Octi-Device-Capabilities", capabilities)
         if (userAgent != null) headers.set(HttpHeaders.UserAgent, userAgent)
     }
 }
@@ -80,9 +82,10 @@ suspend fun TestEnvironment.createDevice(
     version: String? = null,
     platform: String? = null,
     label: String? = null,
+    capabilities: String? = null,
     userAgent: String? = null,
 ): Credentials {
-    val credentials = createDeviceRaw(deviceId, shareCode, version, platform, label, userAgent).asAuth()
+    val credentials = createDeviceRaw(deviceId, shareCode, version, platform, label, capabilities, userAgent).asAuth()
     return Credentials(deviceId, credentials)
 }
 
@@ -115,6 +118,7 @@ data class TestDevices(
         val version: String? = "ktor-client",
         val platform: String? = null,
         val label: String? = null,
+        val capabilities: Set<String>? = null,
         val addedAt: String? = null,
         val lastSeen: String? = null,
     )

src/test/kotlin/eu/darken/octi/server/common/CorsFlowTest.kt

@@ -140,12 +140,21 @@ class CorsFlowTest : TestRunner() {
         val response = http.options("/v1/account") {
             header(HttpHeaders.Origin, allowedOrigin)
             header(HttpHeaders.AccessControlRequestMethod, HttpMethod.Post.value)
-            header(HttpHeaders.AccessControlRequestHeaders, "${HttpHeaders.Authorization},X-Device-ID,Octi-Device-Platform,Octi-Device-Label")
+            header(
+                HttpHeaders.AccessControlRequestHeaders,
+                "${HttpHeaders.Authorization},X-Device-ID,Octi-Device-Platform,Octi-Device-Label,Octi-Device-Capabilities",
+            )
         }
         response.status shouldBe HttpStatusCode.OK
         val allowed = response.headers[HttpHeaders.AccessControlAllowHeaders]?.lowercase() ?: ""
         // Ktor folds requested headers into the response — assert each one we plan to send
-        listOf("authorization", "x-device-id", "octi-device-platform", "octi-device-label").forEach {
+        listOf(
+            "authorization",
+            "x-device-id",
+            "octi-device-platform",
+            "octi-device-label",
+            "octi-device-capabilities",
+        ).forEach {
             (it in allowed) shouldBe true
         }
     }