feat(nestsClient): NIP-98 auth + nests room-info client

Phase 3a of the Clubhouse/nests integration. Adds a new KMP module `nestsClient` (Android + JVM targets) that owns the HTTP control plane for talking to a nests audio-room backend. No transport/audio yet — that arrives in 3b with WebTransport + MoQ. Surface: - `NestsAuth.header(signer, url, method)` signs a kind 27235 event via Quartz's existing HTTPAuthorizationEvent and returns a ready-to-use `Authorization: Nostr <base64>` header value. - `NestsRoomInfo` data class + tolerant JSON parser (ignores unknown fields so newer nests server revisions don't break older clients). - `NestsClient.resolveRoom(serviceBase, roomId, signer)` calls `<serviceBase>/<roomId>` with the signed NIP-98 header and returns the MoQ endpoint + token the audio layer will need. - `OkHttpNestsClient` (jvmAndroid) is the default implementation shared between Android and desktop JVM. Tests: - `NestsRoomInfoTest` (commonTest) covers full/minimal payloads, unknown-field tolerance, missing-endpoint rejection, and URL construction edge cases. - `NestsAuthTest` (jvmTest) signs a real 27235 event, decodes the base64 back through Quartz's JacksonMapper, and asserts the signature verifies and the url+method tags bind correctly. https://claude.ai/code/session_013nVLALALKaHVgHm9u5Cg8D
2026-04-22 02:58:24 +00:00
parent 0db80c66b8
commit 933b522273
8 changed files with 519 additions and 0 deletions
@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.nestsclient
+
+import com.vitorpamplona.quartz.nip01Core.signers.NostrSigner
+import com.vitorpamplona.quartz.nip98HttpAuth.HTTPAuthorizationEvent
+
+/**
+ * Helper for building the `Authorization: Nostr <base64>` header required by
+ * nests audio-room HTTP endpoints (NIP-98).
+ *
+ * The header value binds the signed event to a specific URL + method so the
+ * backend can reject replayed or repurposed tokens. We deliberately do NOT
+ * cache the signed event — the nests server enforces a short (~60 s) validity
+ * window on `created_at`, so callers should build a fresh header per request.
+ */
+object NestsAuth {
+    /**
+     * Sign a kind 27235 event for (`url`, `method`) and return it as a
+     * ready-to-use `Authorization` header value (`"Nostr <base64-json>"`).
+     *
+     * Optionally include a payload hash when the request has a body.
+     */
+    suspend fun header(
+        signer: NostrSigner,
+        url: String,
+        method: String,
+        payload: ByteArray? = null,
+    ): String {
+        val template = HTTPAuthorizationEvent.build(url = url, method = method, file = payload)
+        val signed = signer.sign(template)
+        return signed.toAuthToken()
+    }
+}
@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.nestsclient
+
+import com.vitorpamplona.quartz.nip01Core.signers.NostrSigner
+
+/**
+ * High-level entry point for talking to a nests-compatible audio-room backend.
+ *
+ * Phase 3a only exposes the HTTP control plane — resolving a room's MoQ
+ * endpoint + token via NIP-98 auth. Phase 3b will add the WebTransport/MoQ
+ * transport on top, keeping this interface stable so audio-room callers only
+ * depend on [resolveRoom] for the control-plane step.
+ */
+interface NestsClient {
+    /**
+     * Fetch [NestsRoomInfo] for a specific room.
+     *
+     * @param serviceBase value of the NIP-53 kind 30312 `service` tag
+     *     (e.g. `https://nostrnests.com/api/v1/nests`)
+     * @param roomId the event's `d` tag
+     * @param signer signs the NIP-98 auth event that the server uses to verify
+     *     the caller owns the pubkey it claims
+     * @throws NestsException on transport errors, non-2xx responses, or malformed
+     *     JSON
+     */
+    suspend fun resolveRoom(
+        serviceBase: String,
+        roomId: String,
+        signer: NostrSigner,
+    ): NestsRoomInfo
+}
+
+/**
+ * Single exception type surfaced to UI code so callers don't have to know about
+ * platform HTTP libraries (OkHttp on Android/JVM today).
+ */
+class NestsException(
+    message: String,
+    cause: Throwable? = null,
+    val status: Int? = null,
+) : RuntimeException(message, cause)
@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.nestsclient
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+
+/**
+ * Information returned by a nests audio-room backend when a client
+ * authenticates against `<service>/api/v1/nests/<roomId>`.
+ *
+ * Field names mirror the nests reference server payload:
+ * ```
+ * { "endpoint": "...", "token": "...", "codec": "opus", "sample_rate": 48000 }
+ * ```
+ * All fields except [endpoint] are optional so the client can negotiate with
+ * alternate nests implementations that omit codec/token metadata.
+ */
+@Serializable
+data class NestsRoomInfo(
+    val endpoint: String,
+    val token: String? = null,
+    val codec: String? = null,
+    @SerialName("sample_rate") val sampleRate: Int? = null,
+    val transport: String? = null,
+    val extra: Map<String, JsonElement> = emptyMap(),
+) {
+    companion object {
+        private val json =
+            Json {
+                ignoreUnknownKeys = true
+                explicitNulls = false
+            }
+
+        fun parse(body: String): NestsRoomInfo = json.decodeFromString(serializer(), body)
+    }
+}
+
+/**
+ * Build the URL a client should call to resolve [NestsRoomInfo] for a specific
+ * room. [serviceBase] comes from the `service` tag of the NIP-53 kind 30312
+ * event; [roomId] is the event's `d` tag.
+ *
+ * Example: `https://nostrnests.com/api/v1/nests` + `abc-123` →
+ * `https://nostrnests.com/api/v1/nests/abc-123`.
+ */
+fun nestsRoomInfoUrl(
+    serviceBase: String,
+    roomId: String,
+): String {
+    val trimmed = serviceBase.trimEnd('/')
+    val encoded = roomId.trim()
+    return "$trimmed/$encoded"
+}