Harden the smart-account demo and add a copyable token contract

App: resolve the spend-cap decimals at submit time and fail closed when a
custom token's decimals cannot be read; format inbox amounts at the
per-request token scale; unify the approval report-back; make a
confirmed-without-hash approval terminal; propagate CancellationException at
the flow and screen boundaries; decode XDR off the composition pass; add a
tap-to-copy token contract to the delegate result card; debounce the token
decimals lookup.

Coordination server: temp-file write cleanup, application logging, body-size
limit, cancellation propagation. Reference agent: validate the amount against
the SDK and bound the poll settings, restrict escalation to the policy-denial
codes, reconcile the coordination wire contract.

Author: christian-rogobete

smart-account-demo/coordination-server/src/main/kotlin/com/soneso/smartdemo/coordination/Errors.kt

@@ -16,6 +16,11 @@ class NotFoundException(override val message: String) : Exception(message)
  */
 class ConflictException(override val message: String) : Exception(message)
 
+/**
+ * Raised when a request body exceeds the accepted size limit. Maps to HTTP 413.
+ */
+class PayloadTooLargeException(override val message: String) : Exception(message)
+
 /**
  * Raised when configuration cannot be resolved into a runnable state.
  */

smart-account-demo/coordination-server/src/main/kotlin/com/soneso/smartdemo/coordination/Models.kt

@@ -10,38 +10,30 @@ import kotlinx.serialization.Serializable
  * [APPROVED] or [REJECTED]. No other transition is permitted.
  */
 @Serializable
-enum class RequestStatus {
+enum class RequestStatus(
+    /** The string used on the wire and in persisted JSON. */
+    val wireName: String,
+) {
     @SerialName("pending")
-    PENDING,
+    PENDING("pending"),
 
     @SerialName("approved")
-    APPROVED,
+    APPROVED("approved"),
 
     @SerialName("rejected")
-    REJECTED;
-
-    /** The string used on the wire and in persisted JSON. */
-    val wireName: String
-        get() = when (this) {
-            PENDING -> "pending"
-            APPROVED -> "approved"
-            REJECTED -> "rejected"
-        }
+    REJECTED("rejected");
 
     companion object {
         /**
          * Parses a wire value into a [RequestStatus].
          *
          * Throws [ValidationException] when [value] is not a known status.
          */
-        fun fromWire(value: String): RequestStatus = when (value) {
-            "pending" -> PENDING
-            "approved" -> APPROVED
-            "rejected" -> REJECTED
-            else -> throw ValidationException(
-                "status must be one of 'pending', 'approved', 'rejected'"
-            )
-        }
+        fun fromWire(value: String): RequestStatus =
+            entries.firstOrNull { it.wireName == value }
+                ?: throw ValidationException(
+                    "status must be one of ${entries.joinToString(", ") { "'${it.wireName}'" }}"
+                )
     }
 }
 

smart-account-demo/coordination-server/src/main/kotlin/com/soneso/smartdemo/coordination/RequestStore.kt

@@ -35,10 +35,6 @@ class RequestStore(
     /** Insertion order of ids. Reversed when listing so newest appears first. */
     private val order = mutableListOf<String>()
 
-    /** Path of the backing JSON file, or `null` when persistence is disabled. */
-    val backingStorePath: String?
-        get() = storePath
-
     /**
      * Loads persisted records when a store path is configured and the file
      * exists. Safe to call once during startup.
@@ -170,27 +166,35 @@ class RequestStore(
                 Files.createDirectories(directory)
             }
             val temp = Files.createTempFile(directory, "coordination-store", ".tmp")
-            Files.writeString(temp, data)
             try {
-                Files.move(
-                    temp,
-                    target,
-                    StandardCopyOption.REPLACE_EXISTING,
-                    StandardCopyOption.ATOMIC_MOVE,
-                )
-            } catch (_: Exception) {
-                // ATOMIC_MOVE is unsupported on some filesystems; fall back to a
-                // replace move so persistence still works for those targets.
-                Files.move(temp, target, StandardCopyOption.REPLACE_EXISTING)
+                Files.writeString(temp, data)
+                try {
+                    Files.move(
+                        temp,
+                        target,
+                        StandardCopyOption.REPLACE_EXISTING,
+                        StandardCopyOption.ATOMIC_MOVE,
+                    )
+                } catch (_: Exception) {
+                    // ATOMIC_MOVE is unsupported on some filesystems; fall back to a
+                    // replace move so persistence still works for those targets.
+                    Files.move(temp, target, StandardCopyOption.REPLACE_EXISTING)
+                }
+            } catch (e: Exception) {
+                // A failed write or move leaves the temp file behind; remove it so a
+                // failed flush does not leak orphaned temp files into the store
+                // directory, then propagate the failure to the caller.
+                Files.deleteIfExists(temp)
+                throw e
             }
         }
     }
 
     private companion object {
-        val json = Json {
-            encodeDefaults = true
-            explicitNulls = true
-            ignoreUnknownKeys = true
-        }
+        // Strict variant of the shared wire codec: persistence reads disable input
+        // coercion so a corrupt or hand-edited store file fails loudly instead of
+        // silently coercing malformed values to defaults. Encoding is identical to
+        // the wire codec, so the persisted JSON matches the wire shape field-for-field.
+        val json = Json(from = wireJson) { coerceInputValues = false }
     }
 }

smart-account-demo/coordination-server/src/main/kotlin/com/soneso/smartdemo/coordination/Server.kt

@@ -14,6 +14,7 @@ import io.ktor.server.application.log
 import io.ktor.server.cio.CIO
 import io.ktor.server.engine.embeddedServer
 import io.ktor.server.plugins.statuspages.StatusPages
+import io.ktor.server.request.contentLength
 import io.ktor.server.request.header
 import io.ktor.server.request.httpMethod
 import io.ktor.server.request.path
@@ -23,13 +24,21 @@ import io.ktor.server.response.respondText
 import io.ktor.server.routing.get
 import io.ktor.server.routing.post
 import io.ktor.server.routing.routing
+import kotlinx.coroutines.CancellationException
 import kotlinx.serialization.KSerializer
 import kotlinx.serialization.json.Json
-import java.time.Instant
 
 /** `Bearer ` prefix on the Authorization header. */
 private const val BEARER_PREFIX = "Bearer "
 
+/**
+ * Largest request body the API decodes, in bytes. Bodies declaring or carrying
+ * more than this are rejected with HTTP 413 before any JSON parsing, bounding the
+ * memory a single request can pin. Generous for the small JSON call descriptors
+ * this relay handles while still capping abuse.
+ */
+private const val MAX_REQUEST_BODY_BYTES = 256L * 1024
+
 /**
  * JSON codec for the wire contract: nullable fields are always present (as
  * `null`), and unknown keys in request bodies are ignored so server-assigned
@@ -38,7 +47,7 @@ private const val BEARER_PREFIX = "Bearer "
  * that default rather than rejected, matching the iOS and Dart servers which
  * treat a missing or null amount as the empty string.
  */
-private val json = Json {
+internal val wireJson = Json {
     encodeDefaults = true
     explicitNulls = true
     ignoreUnknownKeys = true
@@ -73,7 +82,14 @@ fun Application.coordinationModule(store: RequestStore, token: String) {
         exception<StoreFormatException> { call, cause ->
             call.respondError(HttpStatusCode.BadRequest, cause.message)
         }
+        exception<PayloadTooLargeException> { call, cause ->
+            call.respondError(HttpStatusCode.PayloadTooLarge, cause.message)
+        }
         exception<Throwable> { call, cause ->
+            // Cancellation is cooperative coroutine control flow (client disconnects,
+            // shutdown), not a server fault: propagate it untouched so it is not
+            // logged as an error or masked behind a 500.
+            if (cause is CancellationException) throw cause
             call.application.log.error("Unhandled error", cause)
             call.respondError(HttpStatusCode.InternalServerError, "internal server error")
         }
@@ -89,16 +105,17 @@ fun Application.coordinationModule(store: RequestStore, token: String) {
         }
     }
 
-    // Request logging: one line per request to stdout. CORS `OPTIONS` preflights are
-    // short-circuited noise and are not logged.
+    // Request logging: one line per request through the application logger, which
+    // adds its own timestamp. CORS `OPTIONS` preflights are short-circuited noise
+    // and are not logged.
     intercept(ApplicationCallPipeline.Monitoring) {
         val start = System.nanoTime()
         proceed()
         if (call.request.httpMethod == HttpMethod.Options) return@intercept
         val millis = (System.nanoTime() - start) / 1_000_000
         val status = call.response.status()?.value ?: 0
-        println(
-            "${Instant.now()} ${call.request.httpMethod.value} ${call.request.path()} $status ${millis}ms"
+        call.application.log.info(
+            "${call.request.httpMethod.value} ${call.request.path()} $status ${millis}ms"
         )
     }
 
@@ -138,7 +155,7 @@ fun Application.coordinationModule(store: RequestStore, token: String) {
         }
 
         post("/requests") {
-            val input = decodeBody(call.receiveText(), CreateRequestInput.serializer(), allowEmpty = false)
+            val input = decodeBody(call.receiveBoundedText(), CreateRequestInput.serializer(), allowEmpty = false)
                 .validated()
             val created = store.create(input)
             call.respondJson(HttpStatusCode.Created, SmartAccountRequest.serializer(), created)
@@ -163,7 +180,7 @@ fun Application.coordinationModule(store: RequestStore, token: String) {
 
         post("/requests/{id}/approve") {
             val id = call.parameters["id"].orEmpty()
-            val body = decodeBody(call.receiveText(), ApproveBody.serializer(), allowEmpty = false)
+            val body = decodeBody(call.receiveBoundedText(), ApproveBody.serializer(), allowEmpty = false)
             val resultHash = body.resultHash
             if (resultHash.isNullOrEmpty()) {
                 throw ValidationException("field 'resultHash' must be a non-empty string")
@@ -174,7 +191,7 @@ fun Application.coordinationModule(store: RequestStore, token: String) {
 
         post("/requests/{id}/reject") {
             val id = call.parameters["id"].orEmpty()
-            val body = decodeBody(call.receiveText(), RejectBody.serializer(), allowEmpty = true)
+            val body = decodeBody(call.receiveBoundedText(), RejectBody.serializer(), allowEmpty = true)
             val updated = store.reject(id, body.note)
             call.respondJson(HttpStatusCode.OK, SmartAccountRequest.serializer(), updated)
         }
@@ -190,6 +207,27 @@ fun buildServer(store: RequestStore, token: String, port: Int) =
         coordinationModule(store, token)
     }
 
+/**
+ * Reads the request body as text, rejecting anything larger than
+ * [MAX_REQUEST_BODY_BYTES] with a [PayloadTooLargeException] (HTTP 413).
+ *
+ * A declared `Content-Length` over the limit is rejected before the body is read,
+ * so an oversized request never reaches [receiveText]. Bodies without a usable
+ * `Content-Length` (e.g. chunked transfer) are checked again after reading, since
+ * their true size is only known once buffered.
+ */
+private suspend fun ApplicationCall.receiveBoundedText(): String {
+    val declaredLength = request.contentLength()
+    if (declaredLength != null && declaredLength > MAX_REQUEST_BODY_BYTES) {
+        throw PayloadTooLargeException("request body exceeds the $MAX_REQUEST_BODY_BYTES byte limit")
+    }
+    val text = receiveText()
+    if (text.toByteArray(Charsets.UTF_8).size.toLong() > MAX_REQUEST_BODY_BYTES) {
+        throw PayloadTooLargeException("request body exceeds the $MAX_REQUEST_BODY_BYTES byte limit")
+    }
+    return text
+}
+
 /**
  * Decodes a JSON object request body into [T].
  *
@@ -201,12 +239,12 @@ private fun <T> decodeBody(text: String, serializer: KSerializer<T>, allowEmpty:
     val trimmed = text.trim()
     if (trimmed.isEmpty()) {
         if (allowEmpty) {
-            return json.decodeFromString(serializer, "{}")
+            return wireJson.decodeFromString(serializer, "{}")
         }
         throw ValidationException("request body must be a JSON object")
     }
     return try {
-        json.decodeFromString(serializer, trimmed)
+        wireJson.decodeFromString(serializer, trimmed)
     } catch (e: Exception) {
         throw ValidationException("request body is not a valid JSON object: ${e.message}")
     }
@@ -217,12 +255,12 @@ private suspend fun <T> ApplicationCall.respondJson(
     serializer: KSerializer<T>,
     value: T,
 ) {
-    respondText(json.encodeToString(serializer, value), jsonContentType, status)
+    respondText(wireJson.encodeToString(serializer, value), jsonContentType, status)
 }
 
 private suspend fun ApplicationCall.respondError(status: HttpStatusCode, message: String?) {
     respondText(
-        json.encodeToString(ErrorResponse.serializer(), ErrorResponse(message ?: "error")),
+        wireJson.encodeToString(ErrorResponse.serializer(), ErrorResponse(message ?: "error")),
         jsonContentType,
         status,
     )

smart-account-demo/coordination-server/src/test/kotlin/com/soneso/smartdemo/coordination/HttpTest.kt

@@ -31,7 +31,6 @@ import kotlinx.serialization.json.putJsonArray
 import kotlin.test.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertNotEquals
-import kotlin.test.assertNull
 import kotlin.test.assertTrue
 
 private const val TOKEN = "test-token-123"
@@ -215,6 +214,14 @@ class HttpTest {
         assertEquals(HttpStatusCode.BadRequest, response.status)
     }
 
+    @Test
+    fun returns413WhenTheRequestBodyExceedsTheSizeLimit() = httpTest {
+        // A body well past the server's 256 KiB cap must be rejected with 413
+        // before any JSON parsing is attempted.
+        val oversized = createBody(targetFn = "x".repeat(512 * 1024)).toString()
+        assertEquals(HttpStatusCode.PayloadTooLarge, post("/requests", oversized).status)
+    }
+
     // MARK: - GET /requests
 
     @Test

smart-account-demo/reference-agent/src/main/kotlin/com/soneso/smartdemo/agent/AgentConfig.kt

@@ -1,6 +1,8 @@
 package com.soneso.smartdemo.agent
 
 import com.soneso.stellar.sdk.StrKey
+import com.soneso.stellar.sdk.smartaccount.core.ValidationException
+import com.soneso.stellar.sdk.smartaccount.oz.OZTransactionOperations
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.JsonPrimitive
@@ -140,9 +142,9 @@ data class AgentConfig(
         if (seed.isNullOrEmpty()) {
             throw AgentConfigException("agentSecretSeed is required.")
         }
-        if (seed.length != 64 || !Hex.isHexString(seed)) {
+        if (!isValidHexSeed(seed)) {
             throw AgentConfigException(
-                "agentSecretSeed is not a valid 64-character hex Ed25519 seed."
+                "agentSecretSeed is not a valid $AGENT_HEX_KEY_LENGTH-character hex Ed25519 seed."
             )
         }
 
@@ -172,6 +174,40 @@ data class AgentConfig(
         if (coordinationToken.isEmpty()) {
             throw AgentConfigException("coordinationToken is required.")
         }
+
+        if (tokenDecimals !in 0..OZTransactionOperations.MAX_TOKEN_DECIMALS) {
+            throw AgentConfigException(
+                "tokenDecimals must be between 0 and " +
+                    "${OZTransactionOperations.MAX_TOKEN_DECIMALS}, got: $tokenDecimals."
+            )
+        }
+        // The transfer call converts amount to base units with the SDK's
+        // amountToBaseUnits at this token scale. Run the same conversion here so
+        // the validator rejects exactly what run() would reject: amounts that are
+        // not strictly positive and fractions with more digits than tokenDecimals
+        // allows. This fails fast, before any network or identity work.
+        try {
+            OZTransactionOperations.amountToBaseUnits(amount, tokenDecimals)
+        } catch (e: ValidationException) {
+            throw AgentConfigException(
+                "amount is not a valid transfer amount at $tokenDecimals token decimals: " +
+                    (e.message ?: amount)
+            )
+        }
+
+        // The poll budget must do at least one bounded iteration: a non-positive
+        // interval would busy-loop the network, and fewer than one attempt would
+        // create the escalation and immediately abandon it.
+        if (pollIntervalSeconds <= 0) {
+            throw AgentConfigException(
+                "pollIntervalSeconds must be greater than zero, got: $pollIntervalSeconds."
+            )
+        }
+        if (pollMaxAttempts < 1) {
+            throw AgentConfigException(
+                "pollMaxAttempts must be at least one, got: $pollMaxAttempts."
+            )
+        }
     }
 
     /** Redacts the agent seed and bearer token so the config is safe to log. */

smart-account-demo/reference-agent/src/main/kotlin/com/soneso/smartdemo/agent/AgentEd25519Adapter.kt

@@ -41,8 +41,16 @@ class AgentEd25519Adapter : OZExternalEd25519SignerAdapter {
         registry[slot] = seedBytes.copyOf()
     }
 
-    /** Removes every registered seed. */
+    /**
+     * Removes every registered seed, zeroing each stored copy first so the seed
+     * bytes do not linger in the heap after the reference is dropped. The stored
+     * arrays are private copies (see [add]); zeroing them does not affect the
+     * caller's seed array.
+     */
     fun clearAll() {
+        for (seed in registry.values) {
+            seed.fill(0)
+        }
         registry.clear()
     }