@dvai-bridge/android 4.0.0

package/android/src/main/java/co/deepvoiceai/bridge/ReactiveState.kt

@@ -0,0 +1,60 @@
+package co.deepvoiceai.bridge
+
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+
+/**
+ * Compose- / Lifecycle-friendly reactive view of the running bridge state.
+ * Mirrors iOS `DVAIBridgeReactiveState` (which uses `@Observable` /
+ * `ObservableObject`).
+ *
+ * Each property is a [StateFlow] you can `collect` from in a Compose
+ * `LaunchedEffect` or wire to a ViewModel:
+ *
+ * ```kotlin
+ * @Composable
+ * fun BridgeStatus() {
+ *     val isReady by DVAIBridge.reactive.isReady.collectAsState()
+ *     val baseUrl by DVAIBridge.reactive.baseUrl.collectAsState()
+ *     Text(if (isReady) "Ready: $baseUrl" else "Not running")
+ * }
+ * ```
+ *
+ * The state is updated internally on every successful [DVAIBridge.start] and
+ * [DVAIBridge.stop]; consumers never write directly.
+ */
+class DVAIBridgeReactiveState internal constructor() {
+    private val _isReady = MutableStateFlow(false)
+    val isReady: StateFlow<Boolean> = _isReady.asStateFlow()
+
+    private val _baseUrl = MutableStateFlow<String?>(null)
+    val baseUrl: StateFlow<String?> = _baseUrl.asStateFlow()
+
+    private val _port = MutableStateFlow<Int?>(null)
+    val port: StateFlow<Int?> = _port.asStateFlow()
+
+    private val _backend = MutableStateFlow<BackendKind?>(null)
+    val backend: StateFlow<BackendKind?> = _backend.asStateFlow()
+
+    private val _modelId = MutableStateFlow<String?>(null)
+    val modelId: StateFlow<String?> = _modelId.asStateFlow()
+
+    /** Internal setter, invoked by [DVAIBridge] on start. */
+    internal fun onStarted(server: BoundServer) {
+        _baseUrl.value = server.baseUrl
+        _port.value = server.port
+        _backend.value = server.backend
+        _modelId.value = server.modelId
+        _isReady.value = true
+    }
+
+    /** Internal setter, invoked by [DVAIBridge] on stop. */
+    internal fun onStopped() {
+        _isReady.value = false
+        _baseUrl.value = null
+        _port.value = null
+        _backend.value = null
+        _modelId.value = null
+    }
+}

package/android/src/main/java/co/deepvoiceai/bridge/license/Audience.kt

@@ -0,0 +1,134 @@
+package co.deepvoiceai.bridge.license
+
+import android.content.Context
+import android.content.pm.ApplicationInfo
+
+/**
+ * Runtime audience + platform + dev-mode detection for the Android SDK.
+ *
+ * Kotlin port of `packages/dvai-bridge-core/src/license/audience.ts`.
+ * The semantics are identical to the JS side but the platform APIs
+ * differ — audience is read from [Context.getPackageName] rather than
+ * `window.location.hostname`, and dev-mode is detected via
+ * `BuildConfig.DEBUG` + `ApplicationInfo.FLAG_DEBUGGABLE` rather than
+ * hostname heuristics.
+ *
+ * "Audience" on Android = the host app's package name (e.g.
+ * `"com.acme.app"`). License JWTs bind to package names exactly like
+ * iOS bundle ids; subdomain-style `*.acme.com` wildcards work for
+ * domain-tail matching too.
+ *
+ * "Dev mode" detection bypasses license enforcement entirely so
+ * developers don't need a license to run the SDK on a debug build.
+ * This matches the JS-side `detectDevMode()` behaviour.
+ */
+
+/** Detect the current SDK platform identifier. Always [DvaiPlatform.ANDROID]. */
+fun detectPlatform(): DvaiPlatform = DvaiPlatform.ANDROID
+
+/**
+ * Detect the current audience string the license must bind. Returns
+ * the host app's package name from [Context.getPackageName].
+ *
+ * Returns null only if [context] is null — in practice this never
+ * happens because [LicenseValidator] requires a non-null context at
+ * construction.
+ */
+fun detectAudience(context: Context?): String? = context?.packageName
+
+/**
+ * Detect whether the SDK is running in a developer environment where
+ * license enforcement should be bypassed. The bypass list is
+ * intentionally generous: blocking a developer mid-`./gradlew installDebug`
+ * with a license-not-found error would be hostile.
+ *
+ * Precedence (highest first):
+ *   1. `DVAI_FORCE_PROD=1` env var — production mode forced, overrides DEBUG.
+ *   2. `DVAI_FORCE_DEV=1` env var — dev mode forced.
+ *   3. [hostBuildConfigDebug] (a `BuildConfig.DEBUG` value passed in by the
+ *      host app via [co.deepvoiceai.bridge.StartOptions]) — dev mode.
+ *   4. [ApplicationInfo.FLAG_DEBUGGABLE] on the host app — dev mode.
+ *   5. Otherwise production, license required.
+ *
+ * @param context              Application context — used to read
+ *                             `ApplicationInfo.FLAG_DEBUGGABLE`.
+ * @param hostBuildConfigDebug The host app's `BuildConfig.DEBUG`, passed in
+ *                             explicitly because the validator lives in a
+ *                             library module whose own `BuildConfig.DEBUG`
+ *                             never reflects the host app's state. Pass null
+ *                             to skip this check.
+ */
+fun detectDevMode(
+    context: Context?,
+    hostBuildConfigDebug: Boolean? = null,
+): DevModeResult {
+    // 1. Explicit env-var overrides win — these mirror the JS side so the
+    //    same DVAI_FORCE_PROD / DVAI_FORCE_DEV semantics work in CI/test
+    //    contexts on any platform.
+    val forceProd = System.getenv("DVAI_FORCE_PROD")
+    if (forceProd == "1" || forceProd == "true") {
+        return DevModeResult(isDev = false, reason = "DVAI_FORCE_PROD set")
+    }
+    val forceDev = System.getenv("DVAI_FORCE_DEV")
+    if (forceDev == "1" || forceDev == "true") {
+        return DevModeResult(isDev = true, reason = "DVAI_FORCE_DEV set")
+    }
+
+    // 2. Host app's BuildConfig.DEBUG (explicit, preferred). When the host
+    //    passes a non-null value we treat it as authoritative — the host
+    //    knows whether they're a debug build better than we do. When null,
+    //    we fall through to the manifest-flag heuristic.
+    when (hostBuildConfigDebug) {
+        true -> return DevModeResult(isDev = true, reason = "BuildConfig.DEBUG=true")
+        false -> return DevModeResult(isDev = false, reason = "BuildConfig.DEBUG=false (host-supplied)")
+        null -> { /* fall through */ }
+    }
+
+    // 3. ApplicationInfo.FLAG_DEBUGGABLE — set on debug builds and on apps
+    //    with `android:debuggable="true"` in the manifest. Fallback when the
+    //    host hasn't wired their BuildConfig.DEBUG through to StartOptions.
+    if (context != null) {
+        val flags = context.applicationInfo.flags
+        if ((flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0) {
+            return DevModeResult(isDev = true, reason = "ApplicationInfo.FLAG_DEBUGGABLE set")
+        }
+    }
+
+    return DevModeResult(isDev = false, reason = "production-class environment")
+}
+
+/** Outcome of [detectDevMode]. */
+data class DevModeResult(val isDev: Boolean, val reason: String)
+
+/**
+ * Decide whether a license-payload `aud` entry matches the current
+ * runtime audience. Supports exact match and `*.example.com` wildcard
+ * matching for subdomain binding. Returns the matched `aud` pattern
+ * on success so it can be recorded for audit, or null on miss.
+ *
+ * Match rules (identical to the JS side):
+ *   - `"foo"` matches `"foo"` exactly
+ *   - `"*.example.com"` matches `"example.com"` AND any `"<sub>.example.com"`
+ *   - `"*"` matches any non-empty audience (intentionally permissive; use
+ *     for trial/site licenses that span all of a customer's deployments)
+ *
+ * Runtime audience of `null` matches `"*"` only.
+ */
+fun matchAudience(runtimeAudience: String?, audClaim: List<String>): String? {
+    if (runtimeAudience == null) {
+        return if (audClaim.contains("*")) "*" else null
+    }
+    val runtime = runtimeAudience.lowercase()
+    for (pattern in audClaim) {
+        val p = pattern.lowercase()
+        if (p == "*") return pattern // permissive wildcard
+        if (p == runtime) return pattern // exact match
+        if (p.startsWith("*.")) {
+            val suffix = p.substring(2)
+            if (runtime == suffix || runtime.endsWith(".$suffix")) {
+                return pattern
+            }
+        }
+    }
+    return null
+}

package/android/src/main/java/co/deepvoiceai/bridge/license/Discovery.kt

@@ -0,0 +1,146 @@
+package co.deepvoiceai.bridge.license
+
+import android.content.Context
+import java.io.File
+
+/**
+ * License-file discovery for the Android SDK.
+ *
+ * Kotlin port of `packages/dvai-bridge-core/src/license/discovery.ts`.
+ * The discovery priority order mirrors the JS side but the platform-
+ * default locations are Android-specific:
+ *
+ *   1. An explicit string literal passed via [LicenseDiscoveryOptions.token]
+ *      — useful for CI / test contexts where reading a file isn't practical.
+ *   2. A path passed via [LicenseDiscoveryOptions.path] — the developer
+ *      points the SDK at a file they've placed somewhere non-default.
+ *   3. The `DVAI_LICENSE_PATH` env var — same as (2) but driven by
+ *      process environment, helpful for emulator-based testing.
+ *   4. The `DVAI_LICENSE_TOKEN` env var — inline JWT as an alternative
+ *      to a file path.
+ *   5. The bundled asset `assets/dvai-license.jwt` — the conventional
+ *      ship-with-the-APK location. Auto-discovered.
+ *   6. The bundled raw resource `R.raw.dvai_license` — alternative
+ *      asset location for apps that already use the res/raw/ folder.
+ *      Looked up reflectively against the host app's R.raw class.
+ *   7. Internal storage `context.filesDir/dvai-license.jwt` — for
+ *      apps that drop the license at runtime (e.g. fetched from
+ *      a self-hosted endpoint after first launch).
+ *
+ * Returning `null` means "no license file found"; the validator treats
+ * that as the free-prod case, which on Android escalates to a throw via
+ * [LicenseValidator.validateAndAssert].
+ */
+
+/** Default filename the SDK looks for at every file location. */
+const val DEFAULT_LICENSE_FILENAME: String = "dvai-license.jwt"
+
+/** Default raw-resource name (without the `R.raw.` prefix). */
+const val DEFAULT_LICENSE_RAW_RESOURCE_NAME: String = "dvai_license"
+
+data class LicenseDiscoveryOptions(
+    /** Pre-loaded JWT string (skips all filesystem / asset lookups). */
+    val token: String? = null,
+    /** Explicit path to load from. Overrides auto-discovery. */
+    val path: String? = null,
+)
+
+/** Result of a successful discovery; identifies the source for audit logging. */
+data class DiscoveredToken(val token: String, val source: String)
+
+/**
+ * Best-effort load of a license JWT. Returns the raw token string on
+ * success or null on miss. Errors during loading (file not found, asset
+ * not present) collapse to null — the validator's responsibility is to
+ * handle the no-license case gracefully, not the discovery layer's.
+ *
+ * Side-effect-free in the sense of "no network calls"; reads from the
+ * filesystem and the APK's assets directory only.
+ */
+fun discoverLicenseToken(
+    context: Context,
+    opts: LicenseDiscoveryOptions = LicenseDiscoveryOptions(),
+): DiscoveredToken? {
+    // 1. Explicit token wins.
+    if (!opts.token.isNullOrEmpty()) {
+        return DiscoveredToken(opts.token.trim(), "config.licenseToken")
+    }
+
+    // 2. Explicit path (config option). An explicit path that doesn't load
+    //    is a real miss, not a silent fallthrough — matches JS behaviour.
+    if (!opts.path.isNullOrEmpty()) {
+        val loaded = tryLoadFromPath(opts.path)
+        return loaded?.let { DiscoveredToken(it, opts.path) }
+    }
+
+    // 3. Env-var path.
+    val envPath = System.getenv("DVAI_LICENSE_PATH")
+    if (!envPath.isNullOrEmpty()) {
+        val loaded = tryLoadFromPath(envPath)
+        if (loaded != null) return DiscoveredToken(loaded, "DVAI_LICENSE_PATH=$envPath")
+    }
+
+    // 4. Env-var inline token (alternative to file).
+    val envToken = System.getenv("DVAI_LICENSE_TOKEN")
+    if (!envToken.isNullOrEmpty()) {
+        return DiscoveredToken(envToken.trim(), "DVAI_LICENSE_TOKEN env var")
+    }
+
+    // 5. Bundled asset: assets/dvai-license.jwt.
+    val asset = tryLoadFromAsset(context, DEFAULT_LICENSE_FILENAME)
+    if (asset != null) return DiscoveredToken(asset, "assets/$DEFAULT_LICENSE_FILENAME")
+
+    // 6. Bundled raw resource: R.raw.dvai_license (looked up reflectively
+    //    against the host app's R class because we can't reference its
+    //    R from a library module).
+    val raw = tryLoadFromRawResource(context, DEFAULT_LICENSE_RAW_RESOURCE_NAME)
+    if (raw != null) return DiscoveredToken(raw, "res/raw/$DEFAULT_LICENSE_RAW_RESOURCE_NAME")
+
+    // 7. Internal storage: filesDir/dvai-license.jwt.
+    val internalFile = File(context.filesDir, DEFAULT_LICENSE_FILENAME)
+    val internal = tryLoadFromFile(internalFile)
+    if (internal != null) return DiscoveredToken(internal, internalFile.absolutePath)
+
+    return null
+}
+
+private fun tryLoadFromPath(path: String): String? = tryLoadFromFile(File(path))
+
+private fun tryLoadFromFile(file: File): String? {
+    return try {
+        if (!file.exists() || !file.isFile) return null
+        val text = file.readText(Charsets.UTF_8).trim()
+        text.ifEmpty { null }
+    } catch (_: Throwable) {
+        null
+    }
+}
+
+private fun tryLoadFromAsset(context: Context, name: String): String? {
+    return try {
+        context.assets.open(name).use { input ->
+            val text = input.readBytes().toString(Charsets.UTF_8).trim()
+            text.ifEmpty { null }
+        }
+    } catch (_: Throwable) {
+        null
+    }
+}
+
+private fun tryLoadFromRawResource(context: Context, name: String): String? {
+    return try {
+        // Resource ids are dynamic — the library module has no compile-time
+        // reference to the host app's R.raw, so look it up by name via
+        // Resources.getIdentifier(). Returns 0 if the host app doesn't
+        // ship a `res/raw/dvai_license.*` resource, which we treat as a
+        // clean miss.
+        val resId = context.resources.getIdentifier(name, "raw", context.packageName)
+        if (resId == 0) return null
+        context.resources.openRawResource(resId).use { input ->
+            val text = input.readBytes().toString(Charsets.UTF_8).trim()
+            text.ifEmpty { null }
+        }
+    } catch (_: Throwable) {
+        null
+    }
+}

package/android/src/main/java/co/deepvoiceai/bridge/license/LicenseTypes.kt

@@ -0,0 +1,158 @@
+package co.deepvoiceai.bridge.license
+
+/**
+ * Type surface for the DVAI-Bridge offline JWT license system.
+ *
+ * Kotlin port of `packages/dvai-bridge-core/src/license/types.ts`. The
+ * sealed [LicenseStatus] hierarchy mirrors the JS discriminated-union;
+ * each case carries the same fields. Android-native consumers dispatch
+ * on `when (status)` exhaustively, matching the JS `switch(status.kind)`.
+ *
+ * The whole license flow is deliberately small:
+ *   1. A signed JWT (produced server-side by your license generator) is
+ *      either dropped at a platform-default path, pointed at via the
+ *      [co.deepvoiceai.bridge.StartOptions.licenseKeyPath] config option,
+ *      or pasted directly into [co.deepvoiceai.bridge.StartOptions.licenseToken].
+ *   2. The SDK reads it, verifies the ECDSA P-256 signature against the
+ *      key registry in [DvaiPublicKeys], and checks four runtime claims:
+ *      - signature must verify against a known kid
+ *      - `exp` must be in the future
+ *      - `aud` must include the current audience (package name)
+ *      - `platforms` must include "android"
+ *   3. The outcome is summarised in a [LicenseStatus] value that the
+ *      rest of the SDK can dispatch on.
+ *
+ * Nothing in this file makes network calls. The entire flow is offline.
+ */
+
+/** Platform identifiers the SDK recognises in license `platforms` claims. */
+enum class DvaiPlatform(val wire: String) {
+    WEB("web"),
+    NODE("node"),
+    IOS("ios"),
+    ANDROID("android"),
+    DOTNET("dotnet"),
+    FLUTTER("flutter"),
+    REACT_NATIVE("react-native"),
+    CAPACITOR("capacitor");
+
+    companion object {
+        fun fromWire(s: String): DvaiPlatform? = values().firstOrNull { it.wire == s }
+    }
+}
+
+/**
+ * Payload shape we issue (subset; extra claims tolerated). Mirrors the
+ * JS-side `DvaiLicensePayload`.
+ *
+ * @property iss        Standard JWT issuer claim. Must be `"DVAI-Bridge"`.
+ * @property sub        Standard subject — internal license id. Surfaced in audit logs.
+ * @property aud        Audience binding — list of domains and/or bundle ids permitted
+ *                      to activate this license. Each entry is either an exact string
+ *                      match (e.g. `"com.acme.app"`) or a wildcard subdomain
+ *                      pattern (e.g. `"*.acme.com"` matches both `acme.com` and
+ *                      `app.acme.com`), or `"*"` for any-audience licenses.
+ * @property tier       Tier the license grants. `"commercial"` and `"trial"` are
+ *                      the live tiers; the validator never produces `"free-*"` here
+ *                      (those are computed at validation time).
+ * @property platforms  Which DVAI-Bridge SDK platforms this license activates.
+ *                      The current runtime platform must appear here for the
+ *                      license to apply.
+ * @property licensee   Display name of the licensee, for audit logs + user-facing messaging.
+ * @property iat        Standard JWT issued-at (seconds since Unix epoch).
+ * @property exp        Standard JWT expiry (seconds since Unix epoch).
+ */
+data class DvaiLicensePayload(
+    val iss: String,
+    val sub: String,
+    val aud: List<String>,
+    val tier: String, // "commercial" | "trial"
+    val platforms: List<String>,
+    val licensee: String,
+    val iat: Long,
+    val exp: Long,
+)
+
+/**
+ * Result of license validation. Sealed class so the consumer's decision
+ * tree is exhaustive (`Commercial` or `Trial` → premium; everything else
+ * → free).
+ *
+ * Note: on Android the validator NEVER produces a [FreeProd] status that
+ * the SDK then runs in free tier — production Android without a license
+ * throws via [LicenseRequiredError]. The status case exists so that
+ * `validate()` (the non-throwing variant) can describe the failure for
+ * host-app dashboards / logging, but [LicenseValidator.validateAndAssert]
+ * (called from `DVAIBridge.start`) converts it to a throw.
+ */
+sealed class LicenseStatus {
+    /** Paid commercial license — premium tier. */
+    data class Commercial(
+        val licensee: String,
+        val expiresAt: Long,
+        val platform: DvaiPlatform,
+        val audienceMatched: String,
+    ) : LicenseStatus()
+
+    /** Paid trial license — premium tier, time-limited. */
+    data class Trial(
+        val licensee: String,
+        val expiresAt: Long,
+        val platform: DvaiPlatform,
+        val audienceMatched: String,
+    ) : LicenseStatus()
+
+    /**
+     * Debug build / dev-mode bypass. License enforcement skipped.
+     * @property reason Why dev mode was detected (for logging / dashboard surfacing).
+     */
+    data class FreeDev(val reason: String) : LicenseStatus()
+
+    /**
+     * Production deploy with no valid license. On Android,
+     * `validateAndAssert()` throws [LicenseRequiredError] for this case
+     * rather than allowing free-tier operation — unlike the JS SDK which
+     * runs with a watermark in free-prod.
+     *
+     * @property reason Specific failure mode (no token, signature failed,
+     *                  audience mismatch, etc.) — verbose by design so the
+     *                  developer can self-debug without a support ticket.
+     */
+    data class FreeProd(val reason: String) : LicenseStatus()
+
+    /**
+     * Had a valid license but `exp` is in the past. On Android,
+     * `validateAndAssert()` throws [LicenseRequiredError] for this case.
+     */
+    data class FreeExpired(
+        val licensee: String,
+        val expiredAt: Long,
+    ) : LicenseStatus()
+}
+
+/** Returns true iff `status` represents a paid / unwatermarked tier. */
+fun isPaidTier(status: LicenseStatus): Boolean =
+    status is LicenseStatus.Commercial || status is LicenseStatus.Trial
+
+/**
+ * Thrown by [LicenseValidator.validateAndAssert] (and propagated from
+ * `DVAIBridge.start(...)`) when an SDK consumer attempts to run the
+ * library in a production / release context without a valid commercial
+ * or trial license.
+ *
+ * The error message is intentionally verbose: it tells the developer
+ * exactly which check failed (missing file, expired, audience mismatch,
+ * etc.), how to resolve it, and where to put the license file once
+ * they have one. This is the front line of the BSL 1.1 commercial
+ * enforcement story — surface it clearly enough that a developer can
+ * unblock themselves without a support ticket.
+ *
+ * The `status` field carries the underlying [LicenseStatus] so
+ * programmatic callers can dispatch on `err.status` if they want to
+ * handle "expired" differently from "missing".
+ */
+class LicenseRequiredError(
+    message: String,
+    /** The underlying validator status that triggered the throw. */
+    val status: LicenseStatus,
+) : Exception(message)