@tinkerlandai/indiana-react-native 0.9.2 → 0.9.5

package/native-sdk/android/java/ai/tinkerland/indiana/CustomerSemantics.kt

@@ -0,0 +1,120 @@
+package ai.tinkerland.indiana
+
+import org.json.JSONArray
+import org.json.JSONObject
+import java.math.BigDecimal
+import java.math.MathContext
+import java.math.RoundingMode
+
+/** Current Customer Zod refinements/transforms not representable in JSON Schema. */
+internal object IndianaCustomerSemantics {
+    fun preflight(operation: String, value: JSONObject) {
+        if (operation == "evaluateFeatures") value.optJSONObject("attributes")?.let { if (it.length() > 128) throw IndianaClientException("invalid_request"); jsonBudget(it) }
+        if (operation == "trackEvents") value.optJSONArray("events")?.let { events -> for (n in 0 until events.length()) events.optJSONObject(n)?.optJSONObject("properties")?.let { properties -> for (key in properties.keys()) jsonBudget(properties.get(key)) } }
+    }
+    fun defaults(operation: String, input: JSONObject): JSONObject {
+        val value = JSONObject(input.toString())
+        if (operation in listOf("previewAttach", "previewUpdate")) value.optJSONObject("invoiceMode")?.let {
+            if (!it.has("enable_plan_immediately")) it.put("enable_plan_immediately", false)
+            if (!it.has("finalize")) it.put("finalize", true)
+        }
+        if (operation == "trackEvents") value.optJSONArray("events")?.let { events ->
+            for (n in 0 until events.length()) events.optJSONObject(n)?.let { if (!it.has("properties")) it.put("properties", JSONObject()) }
+        }
+        return value
+    }
+    fun request(operation: String, value: JSONObject): JSONObject {
+        fun require(allowed: Boolean) { if (!allowed) throw IndianaClientException("invalid_request") }
+        if (operation == "previewAttach") {
+            val plans = objects(value.getJSONArray("plans")); val provider = value.getString("provider")
+            require(plans.map { it.getString("productVersionId") }.distinct().size == plans.size)
+            require(plans.all { (it.optJSONObject("featureQuantities")?.length() ?: 0) <= 100 })
+            require(!value.has("offerId") || !value.has("billingSubscriptionId") && (provider == "stripe" || value.has("nativeOffer")))
+            require(!value.has("nativeOffer") || provider != "stripe" && plans.size == 1)
+            require(!value.has("newBillingSubscription") || provider == "stripe" && !value.has("billingSubscriptionId"))
+            require(value.optJSONObject("invoiceMode")?.optBoolean("enabled") != true || provider == "stripe" && !value.has("entityId"))
+            value.optJSONObject("nativeOffer")?.let { offer ->
+                require(offer.getString("offerKind") != "none" || offer.isNull("offerId") && offer.getInt("discountMinor") == 0 && offer.isNull("trialDays"))
+                require(offer.isNull("trialDays") || offer.getInt("discountMinor") == 0)
+            }
+        }
+        if (operation == "previewUpdate") {
+            val change = value.getJSONObject("change"); val type = change.getString("type"); val timing = value.getString("timing")
+            require(timing != "store" || type == "plan")
+            require(type != "billing_cycle" || timing == if (change.opt("billingCycleAnchor") == "now") "immediate" else "renewal")
+            value.optJSONArray("membershipIds")?.let { group -> val ids = strings(group); require(type in listOf("cancel", "uncancel") && value.getString("membershipId") in ids && ids.distinct().size == ids.size) }
+            require(!value.has("carryOverBalances") && !value.has("carryOverUsages") || type == "plan" && timing == "immediate")
+            require(!value.has("prorationBehavior") || type == "quantity")
+            for (field in listOf("carryOverBalances", "carryOverUsages")) value.optJSONObject(field)?.optJSONArray("featureIds")?.let { val ids = strings(it); require(ids.distinct().size == ids.size) }
+        }
+        if (operation == "setBillingCoupons") { val ids = strings(value.getJSONArray("grantIds")); require(ids.distinct().size == ids.size) }
+        if (operation == "prepareBillingAuthorization" && value.getString("kind") == "auto_topup") {
+            require(decimal(value, "quantity") >= BigDecimal.ONE); normalize(value, "quantity"); normalize(value, "threshold")
+        }
+        if (operation in listOf("checkEntitlement", "resolvePaywall", "resolveOffering")) value.optJSONObject("requirement")?.let {
+            require(decimal(it, "quantity") > BigDecimal.ZERO); normalize(it, "quantity"); properties(it.getJSONObject("properties"))
+        }
+        if (operation == "quoteBalance") value.getJSONObject("command").let {
+            require(decimal(it, "quantity") > BigDecimal.ZERO); normalize(it, "quantity"); properties(it.getJSONObject("properties"))
+        }
+        if (operation == "readLedger") value.getJSONObject("query").let { if (!it.isNull("from") && !it.isNull("to")) require(it.getString("from") <= it.getString("to")) }
+        if (operation == "readCreditStatement") {
+            val elapsed = utcMillis(value.getString("to")) - utcMillis(value.getString("from"))
+            require(elapsed > 0 && elapsed <= 366L * 86400000L); require(value.isNull("after") || !value.isNull("snapshotAt"))
+        }
+        return value
+    }
+    fun response(operation: String, value: JSONObject) {
+        fun require(allowed: Boolean) { if (!allowed) throw IndianaClientException("invalid_response") }
+        val checks = listOfNotNull(
+            value.optJSONObject("check"),
+            if (operation == "resolvePaywall") value.optJSONObject("paywall")?.optJSONObject("check") else null,
+        )
+        for (check in checks) {
+            require(check.getBoolean("allowed") == check.isNull("reason")); require(!check.getBoolean("allowed") || check.isNull("preview"))
+            val candidates = check.optJSONObject("preview")?.optJSONArray("candidates")?.let(::objects) ?: emptyList()
+            require(candidates.map { it.getString("productVersionId") }.distinct().size == candidates.size)
+            require(candidates.all { (it.getString("action") == "upgrade") == !it.isNull("membershipId") })
+        }
+        if (operation == "quoteBalance") value.getJSONObject("quote").let { quote ->
+            require(if (quote.getBoolean("allowed")) quote.isNull("reason") else !quote.isNull("reason") && quote.getJSONArray("allocations").length() == 0)
+            if (!quote.has("overageBehavior")) require(!quote.has("requestedQuantity") && decimal(quote, "quantity") > BigDecimal.ZERO)
+            else require(quote.has("requestedQuantity") && decimal(quote, "requestedQuantity") >= decimal(quote, "quantity") && (quote.getString("overageBehavior") == "cap" || quote.getString("requestedQuantity") == quote.getString("quantity")))
+        }
+    }
+    private fun objects(value: JSONArray) = (0 until value.length()).map { value.getJSONObject(it) }
+    private fun strings(value: JSONArray) = (0 until value.length()).map { value.getString(it) }
+    private fun decimal(value: JSONObject, key: String) = value.getString(key).toBigDecimal()
+    private fun normalize(value: JSONObject, key: String) { value.put(key, value.getString(key).toBigDecimal().stripTrailingZeros().toPlainString()) }
+    private fun properties(value: JSONObject) {
+        if (value.length() > 16) throw IndianaClientException("invalid_request")
+        for (key in value.keys()) {
+            val item = value.get(key)
+            value.put(key, if (item is Number) {
+                val number = item.toDouble(); if (number == 0.0) "0" else {
+                    // ECMAScript selects the closest shortest decimal that round-trips.
+                    // JDK 17's Double.toString alone differs for e.g. 5e-324 and 1e18+128.
+                    val exact = BigDecimal(number)
+                    val decimal = (1..17).asSequence().map { exact.round(MathContext(it, RoundingMode.HALF_EVEN)) }.first { it.toDouble() == number }.stripTrailingZeros()
+                    if (kotlin.math.abs(number) >= 1e-6 && kotlin.math.abs(number) < 1e21) decimal.toPlainString()
+                    else decimal.toString().lowercase().replace(Regex("e([+-]?)0+(\\d+)"), "e$1$2")
+                }
+            } else item.toString())
+        }
+    }
+    private fun jsonBudget(value: Any?) {
+        var count = 0
+        fun visit(value: Any?, depth: Int) {
+            if (++count > 10000 || depth > 20) throw IndianaClientException("invalid_request")
+            fun text(value: String) { if ('\u0000' in value || value.indices.any { (Character.isHighSurrogate(value[it]) && (it + 1 >= value.length || !Character.isLowSurrogate(value[it + 1]))) || (Character.isLowSurrogate(value[it]) && (it == 0 || !Character.isHighSurrogate(value[it - 1]))) }) throw IndianaClientException("invalid_request") }
+            when (value) {
+                is String -> text(value)
+                is JSONArray -> for (n in 0 until value.length()) visit(value.opt(n), depth + 1)
+                is JSONObject -> for (key in value.keys()) { text(key); if (key in listOf("__proto__", "constructor", "prototype")) throw IndianaClientException("invalid_request"); visit(value.opt(key), depth + 1) }
+            }
+        }
+        visit(value, 0)
+        val encoded = if (value is JSONObject || value is JSONArray) value.toString() else JSONArray().put(value).toString().drop(1).dropLast(1)
+        if (encoded.toByteArray(Charsets.UTF_8).size > 65536) throw IndianaClientException("invalid_request")
+    }
+}

package/native-sdk/android/java/ai/tinkerland/indiana/CustomerSession.kt

@@ -0,0 +1,106 @@
+package ai.tinkerland.indiana
+
+import java.time.Instant
+import java.util.UUID
+import java.util.concurrent.atomic.AtomicReference
+import kotlinx.coroutines.CompletableDeferred
+import org.json.JSONObject
+
+/** Server-issued credentials. This SDK keeps the pair in memory only. */
+data class IndianaCustomerSession(val customerId: UUID, val sessionId: UUID, val accessToken: String, val refreshToken: String, val expiresAt: Instant, val refreshExpiresAt: Instant) {
+    internal fun validate(fresh: Boolean = false) {
+        if (!accessToken.matches(Regex("gg_ct_[A-Za-z0-9_-]{43}")) || !refreshToken.matches(Regex("gg_rt_[A-Za-z0-9_-]{43}")) || refreshExpiresAt < expiresAt || refreshExpiresAt <= Instant.now() || (fresh && expiresAt <= Instant.now())) throw IndianaClientException("invalid_response")
+    }
+    companion object {
+        @JvmStatic fun fromJSON(value: JSONObject): IndianaCustomerSession = safe { IndianaCustomerSession(UUID.fromString(value.getString("customerId")), UUID.fromString(value.getString("sessionId")), value.getString("accessToken"), value.getString("refreshToken"), Instant.parse(value.getString("expiresAt")), Instant.parse(value.getString("refreshExpiresAt"))) }.also { it.validate() }
+    }
+}
+internal class IndianaSessionTransport(private val upstream: IndianaHTTP, private val expectedScope: IndianaScope, private val now: () -> Instant = Instant::now): IndianaHTTP {
+    private data class State(val original: String?, val pair: IndianaCustomerSession?, val epoch: UUID, val onInvalidated: (() -> Unit)? = null)
+    private val state = AtomicReference(State(null, null, UUID.randomUUID()))
+    private data class Flight(val state: State, val result: CompletableDeferred<IndianaCustomerSession>)
+    private val rotation = Any()
+    private var pending: Flight? = null
+    @Volatile private var accessProvider: (suspend () -> String)? = null
+    fun setAccessTokenProvider(provider: (suspend () -> String)?) { accessProvider = provider }
+    fun identify(access: String?, onInvalidated: (() -> Unit)? = null) { state.set(State(access, null, UUID.randomUUID(), onInvalidated)) }
+    fun identify(pair: IndianaCustomerSession, onInvalidated: (() -> Unit)? = null) { pair.validate(); state.set(State(pair.accessToken, pair, UUID.randomUUID(), onInvalidated)) }
+    private fun invalidate(current: State) {
+        if (state.compareAndSet(current, State(null, null, UUID.randomUUID()))) current.onInvalidated?.invoke()
+    }
+    suspend fun refresh(force: Boolean = true): IndianaCustomerSession {
+        if (accessProvider != null) throw IndianaClientException("unsupported_capability")
+        val observed = state.get()
+        var owner = false
+        val flight = synchronized(rotation) {
+            val current = state.get()
+            if (current.epoch != observed.epoch) throw IndianaClientException("identity_changed")
+            val pair = current.pair ?: throw IndianaClientException("unauthenticated")
+            if (current.pair != observed.pair || (!force && pair.expiresAt > now().plusSeconds(30))) return pair
+            if (pair.refreshExpiresAt <= now()) {
+                invalidate(current)
+                throw IndianaClientException("unauthenticated")
+            }
+            pending?.takeIf { it.state.epoch == current.epoch } ?: Flight(current, CompletableDeferred()).also { pending = it; owner = true }
+        }
+        if (!owner) {
+            try {
+                val next = flight.result.await()
+                if (state.get().epoch != flight.state.epoch) throw IndianaClientException("identity_changed")
+                return next
+            } catch (error: Exception) {
+                if (state.get().epoch != flight.state.epoch) throw IndianaClientException("identity_changed")
+                throw error
+            }
+        }
+        val current = flight.state
+        val pair = current.pair ?: throw IndianaClientException("unauthenticated")
+        try {
+            val result = upstream.send("customer-sessions/refresh", "POST", pair.refreshToken, JSONObject())
+            if (safe { scope(result.getJSONObject("scope")) } != expectedScope) throw IndianaClientException("scope_mismatch")
+            val next = IndianaCustomerSession.fromJSON(result); next.validate(true)
+            if (next.customerId != pair.customerId || next.sessionId != pair.sessionId) throw IndianaClientException("scope_mismatch")
+            if (!state.compareAndSet(current, current.copy(pair = next))) throw IndianaClientException("identity_changed")
+            flight.result.complete(next); return next
+        } catch (cause: Exception) {
+            val error = if (state.get().epoch != current.epoch) IndianaClientException("identity_changed") else cause
+            if (error is IndianaClientException && error.code == "request_failed_401") invalidate(current)
+            flight.result.completeExceptionally(error); throw error
+        } finally { synchronized(rotation) { if (pending === flight) pending = null } }
+    }
+    suspend fun access(): String {
+        val current = state.get()
+        accessProvider?.let { provider ->
+            if (current.original == null) throw IndianaClientException("unauthenticated")
+            val token = provider()
+            if (state.get().epoch != current.epoch) throw IndianaClientException("identity_changed")
+            if (!token.matches(Regex("gg_ct_[A-Za-z0-9_-]{43}"))) throw IndianaClientException("invalid_response")
+            return token
+        }
+        if (current.pair != null && current.pair.expiresAt <= now().plusSeconds(30)) refresh(false)
+        val active = state.get()
+        if (current.epoch != active.epoch) throw IndianaClientException("identity_changed")
+        return active.pair?.accessToken ?: active.original ?: throw IndianaClientException("unauthenticated")
+    }
+    override suspend fun send(path: String, method: String, authorization: String, body: JSONObject?): JSONObject {
+        val actor = state.get()
+        val proof = body?.optString("customerToken")
+        if (path.startsWith("push/") && body?.has("credentialDigest") == true) {
+            if (actor.original == null) throw IndianaClientException("unauthenticated")
+            val result = upstream.send(path, method, authorization, body)
+            if (state.get().epoch != actor.epoch) throw IndianaClientException("identity_changed")
+            return result
+        }
+        if (actor.original == null && (authorization.startsWith("gg_ct_") || proof?.startsWith("gg_ct_") == true)) throw IndianaClientException("unauthenticated")
+        val customer = actor.original != null && (authorization == actor.original || proof == actor.original)
+        if (!customer) return upstream.send(path, method, authorization, body)
+        val token = access()
+        val active = state.get()
+        if (active.epoch != actor.epoch) throw IndianaClientException("identity_changed")
+        val payload = body?.let { JSONObject(it.toString()) }
+        if (proof == actor.original) payload?.put("customerToken", token)
+        val result = upstream.send(path, method, if (authorization == actor.original) token else authorization, payload)
+        if (state.get().epoch != actor.epoch) throw IndianaClientException("identity_changed")
+        return result
+    }
+}

package/native-sdk/android/java/ai/tinkerland/indiana/FeatureClient.kt

@@ -0,0 +1,65 @@
+package ai.tinkerland.indiana
+
+import android.app.Activity
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.withContext
+import kotlinx.coroutines.withTimeout
+import org.json.JSONObject
+import java.util.UUID
+
+/** Customer-scoped GB evaluator using the packaged official engine, without JS credentials. */
+class IndianaFeatureClient internal constructor(private val activity: Activity, private val configuration: IndianaConfiguration, attributes: JSONObject, private val operation: suspend (IndianaCustomerOperation, JSONObject) -> JSONObject) {
+    private val attributes = JSONObject(attributes.toString())
+    private val work = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
+    private val readiness = CompletableDeferred<Unit>()
+    private val pending = mutableMapOf<UUID, CompletableDeferred<Any?>>()
+    var onError: ((Exception) -> Unit)? = null
+    private var stopped = false
+    private val host = IndianaBundledWebView(activity, "Indiana Feature evaluator", work, ::dispatch) { error -> if (!readiness.isCompleted) close() else onError?.invoke(error) }
+    init { host.start() }
+    suspend fun evalFeature(key: String): JSONObject {
+        val result = call(JSONObject().put("method", "evalFeature").put("key", key)) as? JSONObject ?: throw IndianaClientException("invalid_response")
+        IndianaSchema.validate("nativeFeatureResult", result); return JSONObject(result.toString())
+    }
+    suspend fun isOn(key: String): Boolean = evalFeature(key).getBoolean("on")
+    suspend fun isOff(key: String): Boolean = evalFeature(key).getBoolean("off")
+    suspend fun getFeatureValue(key: String, fallback: Any? = JSONObject.NULL): Any? = call(JSONObject().put("method", "getFeatureValue").put("key", key).put("fallback", fallback ?: JSONObject.NULL))
+    suspend fun setAttributes(attributes: JSONObject) { call(JSONObject().put("method", "setAttributes").put("attributes", JSONObject(attributes.toString()))) }
+    suspend fun refresh() { call(JSONObject().put("method", "refresh")) }
+    suspend fun flush() { call(JSONObject().put("method", "flush")) }
+    fun close() { activity.runOnUiThread {
+        if (!stopped) {
+            stopped = true; host.destroy()
+            val error = IndianaClientException("identity_changed")
+            readiness.completeExceptionally(error); pending.values.forEach { it.completeExceptionally(error) }; pending.clear(); work.cancel()
+        }
+    } }
+    private suspend fun call(input: JSONObject): Any? = withContext(Dispatchers.Main.immediate) {
+        if (stopped) throw IndianaClientException("identity_changed")
+        withTimeout(45_000) { readiness.await() }
+        if (stopped) throw IndianaClientException("identity_changed")
+        val id = UUID.randomUUID(); val result = CompletableDeferred<Any?>(); pending[id] = result
+        try { host.send(JSONObject().put("event", "feature_call").put("id", id.toString()).put("input", input)); withTimeout(45_000) { result.await() } }
+        finally { pending.remove(id) }
+    }
+    private suspend fun dispatch(method: String, raw: Any?): Any? = when (method) {
+        "ready" -> { host.send(JSONObject().put("event", "init").put("surface", "features").put("scope", JSONObject().put("projectId", configuration.scope.projectId.toString()).put("environment", configuration.scope.environment.value)).put("apiOrigin", configuration.apiOrigin).put("attributes", attributes)); null }
+        "featureOperation" -> {
+            val value = raw as? JSONObject ?: throw IndianaClientException("invalid_command")
+            val name = value.getString("operation")
+            if (stopped || name !in setOf("getFeatures", "evaluateFeatures", "trackEvents")) throw IndianaClientException("invalid_command")
+            operation(IndianaCustomerOperation.valueOf(name), value.getJSONObject("input"))
+        }
+        "featuresReady" -> { if (stopped) throw IndianaClientException("identity_changed"); readiness.complete(Unit); null }
+        "featureResult" -> {
+            val value = raw as? JSONObject ?: throw IndianaClientException("invalid_command")
+            val response = pending.remove(UUID.fromString(value.getString("id")))
+            if (value.has("error")) response?.completeExceptionally(IndianaClientException("invalid_response")) else response?.complete(value.opt("result")); null
+        }
+        else -> throw IndianaClientException("invalid_command")
+    }
+}

package/native-sdk/android/java/ai/tinkerland/indiana/FunnelCommandStorage.kt

@@ -0,0 +1,163 @@
+package ai.tinkerland.indiana
+
+import android.content.Context
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import android.util.AtomicFile
+import android.util.Base64
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import org.json.JSONObject
+import java.io.File
+import java.io.RandomAccessFile
+import java.security.KeyStore
+import java.security.MessageDigest
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+data class IndianaFunnelStorageSnapshot(val revision: Long, val entry: String?)
+/** One original Run per adapter; revision CAS must be atomic across hosts. */
+interface IndianaFunnelCommandStorage {
+    fun read(): IndianaFunnelStorageSnapshot
+    fun write(expectedRevision: Long, entry: String?): Long?
+}
+
+/** Encrypted, atomic, excluded from backup. Stores no Run/Customer credential. */
+internal class IndianaFunnelCommandKeystore(context: Context, configuration: IndianaConfiguration, runToken: String): IndianaFunnelCommandStorage {
+    private val namespace = "${context.packageName}:${configuration.baseUrl}:${configuration.scope.projectId}:${configuration.scope.environment.value}:$runToken"
+    private val hash = MessageDigest.getInstance("SHA-256").digest(namespace.toByteArray()).joinToString("") { "%02x".format(it) }
+    private val directory = File(context.noBackupFilesDir, "indiana-funnel-commands-$hash")
+    private val file = AtomicFile(File(directory, "snapshot"))
+    private val alias = "indiana.funnel.commands.v1.$hash"
+    private fun exists() = file.baseFile.exists() || File(file.baseFile.path + ".bak").exists()
+    companion object { private val lock = Any() }
+    private fun <T> locked(action: () -> T): T = synchronized(lock) {
+        try {
+            if (!directory.exists() && !directory.mkdirs()) throw IndianaClientException("protected_storage_unavailable")
+            RandomAccessFile(File(directory,"lock"), "rw").use { handle -> handle.channel.lock().use { action() } }
+        } catch (error: IndianaClientException) { throw error }
+        catch (_: Exception) { throw IndianaClientException("protected_storage_unavailable") }
+    }
+    private fun key(create: Boolean): SecretKey {
+        val store = KeyStore.getInstance("AndroidKeyStore").apply { load(null) }
+        (store.getKey(alias, null) as? SecretKey)?.let { return it }
+        if (!create || exists()) throw IndianaClientException("protected_storage_unavailable")
+        val spec = KeyGenParameterSpec.Builder(alias, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT).setKeySize(256).setBlockModes(KeyProperties.BLOCK_MODE_GCM).setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE).setRandomizedEncryptionRequired(true).build()
+        return KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES,"AndroidKeyStore").apply { init(spec) }.generateKey()
+    }
+    private fun stored(): IndianaFunnelStorageSnapshot {
+        if (!exists()) return IndianaFunnelStorageSnapshot(0, null)
+        val bytes = file.openRead().use { input ->
+            val output = java.io.ByteArrayOutputStream(); val buffer = ByteArray(8192)
+            while (true) { val n = input.read(buffer); if (n < 0) break; if (output.size()+n > 1_048_576) throw IndianaClientException("protected_storage_unavailable"); output.write(buffer,0,n) }; output.toByteArray()
+        }
+        val encrypted = JSONObject(bytes.toString(Charsets.UTF_8))
+        if (encrypted.keys().asSequence().toSet() != setOf("format","nonce","ciphertext") || encrypted.getString("format") != "indiana_funnel_commands_v1") throw IndianaClientException("protected_storage_unavailable")
+        val nonce = Base64.decode(encrypted.getString("nonce"),Base64.NO_WRAP)
+        if (nonce.size != 12) throw IndianaClientException("protected_storage_unavailable")
+        val cipher = Cipher.getInstance("AES/GCM/NoPadding"); cipher.init(Cipher.DECRYPT_MODE,key(false),GCMParameterSpec(128,nonce)); cipher.updateAAD(hash.toByteArray())
+        val plain = cipher.doFinal(Base64.decode(encrypted.getString("ciphertext"),Base64.NO_WRAP))
+        try {
+            val value = JSONObject(plain.toString(Charsets.UTF_8)); val revision = value.getLong("revision")
+            if (revision < 0 || value.keys().asSequence().toSet() != setOf("revision","entry") || !value.isNull("entry") && value.optJSONObject("entry") == null) throw IndianaClientException("protected_storage_unavailable")
+            return IndianaFunnelStorageSnapshot(revision, value.optJSONObject("entry")?.toString())
+        } finally { plain.fill(0) }
+    }
+    override fun read(): IndianaFunnelStorageSnapshot = locked { stored() }
+    override fun write(expectedRevision: Long, entry: String?): Long? = locked {
+        if (stored().revision != expectedRevision) return@locked null
+        if (expectedRevision == Long.MAX_VALUE || (entry?.toByteArray()?.size ?: 0) > 600_000) throw IndianaClientException("protected_storage_unavailable")
+        val plain = JSONObject().put("revision",expectedRevision+1).put("entry",entry?.let { JSONObject(it) } ?: JSONObject.NULL).toString().toByteArray()
+        val cipher = Cipher.getInstance("AES/GCM/NoPadding"); cipher.init(Cipher.ENCRYPT_MODE,key(true)); cipher.updateAAD(hash.toByteArray())
+        try {
+            val bytes = JSONObject().put("format","indiana_funnel_commands_v1").put("nonce",Base64.encodeToString(cipher.iv,Base64.NO_WRAP)).put("ciphertext",Base64.encodeToString(cipher.doFinal(plain),Base64.NO_WRAP)).toString().toByteArray()
+            val stream = file.startWrite()
+            try { stream.write(bytes); file.finishWrite(stream) } catch (error: Exception) { file.failWrite(stream); throw error }
+        } finally { plain.fill(0) }
+        expectedRevision+1
+    }
+}
+
+internal class IndianaFunnelCommandJournal(private val storage: IndianaFunnelCommandStorage, private val scope: IndianaScope) {
+    private val updates = Mutex()
+    @Volatile private var revision = 0L
+    @Volatile private var binding: JSONObject? = null
+    private fun same(a: JSONObject, b: JSONObject) = IndianaSchema.equal(a,b)
+    private fun matches(entry: JSONObject, run: JSONObject): Boolean = entry.getString("runId") == run.getString("id") && entry.getString("funnelId") == run.getJSONObject("source").getString("id") && entry.getString("versionId") == run.getJSONObject("source").getString("versionId")
+    private fun read(): Pair<Long,JSONObject?> {
+        val saved = storage.read()
+        if (saved.revision < 0 || (saved.entry?.toByteArray()?.size ?: 0) > 600_000) throw IndianaClientException("invalid_command_storage")
+        val value = saved.entry?.let { JSONObject(it) } ?: return saved.revision to null
+        val allowed = setOf("schemaVersion","scope","runId","funnelId","versionId","command","closeCommand","purchase","closed")
+        if (value.keys().asSequence().any { it !in allowed } || value.getInt("schemaVersion") != 1 || value.getJSONObject("scope").getString("projectId") != scope.projectId.toString() || value.getJSONObject("scope").getString("environment") != scope.environment.value || value.optJSONObject("command") == null && value.optJSONObject("purchase") == null) throw IndianaClientException("invalid_command_storage")
+        for (field in listOf("runId","funnelId","versionId")) java.util.UUID.fromString(value.getString(field))
+        for (field in listOf("command","closeCommand")) value.optJSONObject(field)?.let { command ->
+            if (command.has("customerToken") || command.optString("operation") in setOf("start","get","review")) throw IndianaClientException("invalid_command_storage")
+            IndianaSchema.validate("command",command)
+        }
+        value.optJSONObject("closeCommand")?.let { close -> val command = value.optJSONObject("command") ?: throw IndianaClientException("invalid_command_storage"); if (close.optString("operation") != "close" || command.optString("operation") == "close" || close.getString("requestId") == command.getString("requestId")) throw IndianaClientException("invalid_command_storage") }
+        value.optJSONObject("purchase")?.let { purchase ->
+            if (purchase.keys().asSequence().toSet() != setOf("receiptId","operationId","generation") || purchase.getLong("generation") < 0) throw IndianaClientException("invalid_command_storage")
+            java.util.UUID.fromString(purchase.getString("receiptId")); java.util.UUID.fromString(purchase.getString("operationId"))
+        }
+        return saved.revision to value
+    }
+    suspend fun load(): JSONObject? = updates.withLock { withContext(Dispatchers.IO) { val saved = read(); revision = saved.first; binding = saved.second; saved.second?.let { JSONObject(it.toString()) } } }
+    fun bind(run: JSONObject) { binding?.let { if (!matches(it,run)) throw IndianaClientException("invalid_response") } }
+    private suspend fun update(change: (JSONObject?,Long) -> JSONObject?) = updates.withLock { withContext(Dispatchers.IO) {
+        var written = false
+        for (attempt in 0..3) {
+            val (currentRevision,saved) = read()
+            binding?.let { original -> if (saved != null && (original.getString("runId") != saved.getString("runId") || original.getString("funnelId") != saved.getString("funnelId") || original.getString("versionId") != saved.getString("versionId"))) throw IndianaClientException("command_storage_conflict") }
+            val original = saved?.let { JSONObject(it.toString()) }
+            val next = change(saved,currentRevision)
+            if (next == null && original == null || next != null && original != null && same(next,original)) { revision = currentRevision; written = true; break }
+            val nextRevision = storage.write(currentRevision,next?.toString()) ?: continue
+            revision = nextRevision; binding = next ?: binding; written = true; break
+        }
+        if (!written) throw IndianaClientException("command_storage_conflict")
+    } }
+    private fun fresh(run: JSONObject) = JSONObject().put("schemaVersion",1).put("scope",JSONObject().put("projectId",scope.projectId.toString()).put("environment",scope.environment.value)).put("runId",run.getString("id")).put("funnelId",run.getJSONObject("source").getString("id")).put("versionId",run.getJSONObject("source").getString("versionId")).put("closed",false)
+    suspend fun retain(command: JSONObject, run: JSONObject) {
+        if (command.has("customerToken") || command.toString().toByteArray().size > 262144 || command.optString("operation") in setOf("start","get","review")) throw IndianaClientException("invalid_command")
+        IndianaSchema.validate("command",command)
+        bind(run); val known = revision
+        update { saved,currentRevision ->
+            val value = saved ?: fresh(run); val original = value.optJSONObject("command")
+            if (!matches(value,run) || saved == null && currentRevision != known && command.optString("operation") != "close") throw IndianaClientException("command_storage_conflict")
+            if (command.optString("operation") == "close") {
+                value.put("closed",true)
+                if (original != null && original.optString("operation") != "close") {
+                    val previous = value.optJSONObject("closeCommand")
+                    if (original.getString("requestId") == command.getString("requestId") || previous != null && !same(previous,command)) throw IndianaClientException("command_storage_conflict")
+                    value.put("closeCommand",JSONObject(command.toString()))
+                } else { if (original != null && !same(original,command)) throw IndianaClientException("command_storage_conflict"); value.put("command",JSONObject(command.toString())) }
+            } else { if (original != null && !same(original,command)) throw IndianaClientException("command_storage_conflict"); value.put("command",JSONObject(command.toString())) }
+            value
+        }
+    }
+    suspend fun purchase(purchase: JSONObject, terminal: Boolean, run: JSONObject) {
+        bind(run); val known = revision
+        update { saved,currentRevision ->
+            if (saved == null && currentRevision != known) throw IndianaClientException("command_storage_conflict")
+            val value = saved ?: fresh(run); val previous = value.optJSONObject("purchase")
+            if (previous != null) {
+                if (previous.getLong("generation") > purchase.getLong("generation")) return@update saved
+                if (previous.getLong("generation") == purchase.getLong("generation") && previous.getString("operationId") != purchase.getString("operationId")) throw IndianaClientException("command_storage_conflict")
+            }
+            if (terminal) { if (previous?.getString("operationId") == purchase.getString("operationId")) value.remove("purchase") }
+            else value.put("purchase",JSONObject(purchase.toString()))
+            if (value.optJSONObject("command") == null && value.optJSONObject("purchase") == null) null else value
+        }
+    }
+    suspend fun settle(id: String) = update { saved,_ ->
+        if (saved == null) return@update null
+        if (saved.optJSONObject("command")?.optString("requestId") == id) { val close = saved.optJSONObject("closeCommand"); if (close == null) saved.remove("command") else saved.put("command",close); saved.remove("closeCommand") }
+        else if (saved.optJSONObject("closeCommand")?.optString("requestId") == id) saved.remove("closeCommand")
+        if (saved.optJSONObject("command") == null && saved.optJSONObject("purchase") == null) null else saved
+    }
+}

package/native-sdk/android/java/ai/tinkerland/indiana/FunnelConfigurationRelay.kt

@@ -0,0 +1,50 @@
+package ai.tinkerland.indiana
+
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import org.json.JSONObject
+import java.io.ByteArrayOutputStream
+import java.net.HttpURLConnection
+import java.net.URI
+import java.nio.ByteBuffer
+import java.nio.charset.CodingErrorAction
+
+/** The Funnel shell has no network access (connect-src 'none'). For Local rules it asks the native host for public
+ * configuration: one exact GET, without credentials, cookies or redirects. */
+internal class IndianaFunnelConfigurationRelay(private val configuration: IndianaConfiguration, loopbackFixtureOrigin: URI? = null) {
+    // Internal test seam: the public configuration remains HTTPS-only.
+    private val origin = loopbackFixtureOrigin?.also { require(it.scheme == "http" && it.host == "127.0.0.1" && it.port > 1024 && it.rawUserInfo == null && it.rawQuery == null && it.rawFragment == null && it.rawPath.isNullOrEmpty()) } ?: URI(configuration.baseUrl)
+    suspend fun read(payload: Any?): JSONObject {
+        val request = payload as? JSONObject
+        val path = request?.opt("path") as? String
+        if (request == null || request.length() != 1 || path == null || !PATH.matches(path)) throw IndianaClientException("invalid_command")
+        return withContext(Dispatchers.IO) {
+            val connection = origin.resolve(path).toURL().openConnection() as HttpURLConnection
+            try {
+                connection.requestMethod = "GET"; connection.instanceFollowRedirects = false; connection.useCaches = path.contains("/artifacts/")
+                connection.connectTimeout = configuration.timeoutMs; connection.readTimeout = configuration.timeoutMs
+                val status = connection.responseCode
+                val headers = JSONObject()
+                for ((key, values) in connection.headerFields) {
+                    val name = key?.lowercase() ?: continue
+                    if (name in HEADERS && values.isNotEmpty()) headers.put(name, values.joinToString(", "))
+                }
+                // The shell reports other statuses (including 429 Retry-After) by status alone.
+                val body = if (status in 200..299) {
+                    if ((connection.getHeaderField("Content-Length")?.toLongOrNull() ?: 0) > MAX_BYTES) throw IndianaClientException("invalid_response")
+                    val output = ByteArrayOutputStream()
+                    connection.inputStream.use { input -> val buffer = ByteArray(8192); while (true) { val size = input.read(buffer); if (size < 0) break; if (output.size() + size > MAX_BYTES) throw IndianaClientException("invalid_response"); output.write(buffer, 0, size) } }
+                    try { Charsets.UTF_8.newDecoder().onMalformedInput(CodingErrorAction.REPORT).onUnmappableCharacter(CodingErrorAction.REPORT).decode(ByteBuffer.wrap(output.toByteArray())).toString() }
+                    catch (_: Exception) { throw IndianaClientException("invalid_response") }
+                } else ""
+                JSONObject().put("status", status).put("headers", headers).put("body", body)
+            } catch (e: IndianaClientException) { throw e } catch (_: Exception) { throw IndianaClientException("temporary_unavailable") }
+            finally { connection.disconnect() }
+        }
+    }
+    companion object {
+        const val MAX_BYTES = 1_048_576
+        private val PATH = Regex("/api/v1/configuration/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(/artifacts/[a-f0-9]{64})?")
+        private val HEADERS = setOf("age", "content-type", "date", "etag", "retry-after", "x-indiana-config-valid-until", "x-indiana-config-validated-at")
+    }
+}