ruby_everywhere 0.3.0 → 0.4.0

data/support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/bridge/BiometricsComponent.kt

@@ -0,0 +1,535 @@
+package com.rubyeverywhere.shell.bridge
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.content.pm.PackageManager
+import android.os.Build
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyPermanentlyInvalidatedException
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import android.util.Log
+import androidx.biometric.BiometricManager
+import androidx.biometric.BiometricManager.Authenticators.BIOMETRIC_STRONG
+import androidx.biometric.BiometricManager.Authenticators.DEVICE_CREDENTIAL
+import androidx.biometric.BiometricPrompt
+import androidx.core.content.ContextCompat
+import androidx.fragment.app.Fragment
+import androidx.security.crypto.EncryptedSharedPreferences
+import androidx.security.crypto.MasterKey
+import com.rubyeverywhere.shell.EverywhereConfig
+import dev.hotwire.core.bridge.BridgeComponent
+import dev.hotwire.core.bridge.BridgeDelegate
+import dev.hotwire.core.bridge.Message
+import dev.hotwire.navigation.destinations.HotwireDestination
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * Bridge component backing `everywhere--biometrics`. Handles `query`
+ * (availability + biometry type), `authenticate` (the biometric prompt,
+ * optionally falling back to the device credential), and the `credential*`
+ * events (a biometric-protected secret powering "sign in with Face ID"),
+ * replying `{available, biometry, status}`, `{authenticated, error?}` and
+ * `{stored|token|enrolled|cleared, error?}` — the same events, keys and status
+ * vocabulary as iOS's BiometricsComponent.swift.
+ *
+ * Biometrics must be declared in everywhere.yml, and undeclared use
+ * short-circuits before any system API. On iOS that gate stops a crash; here it
+ * keeps one everywhere.yml meaning one thing on both platforms.
+ *
+ * This proves presence to the PAGE only (gate a screen, confirm an action); it
+ * is not authentication the server can trust.
+ *
+ * ### Vocabulary
+ *
+ * `biometry` reports iOS's names — faceID / touchID / opticID / none — for
+ * Android's face / fingerprint / iris hardware. Deliberately: the value exists
+ * so a page can label its own button, and a page that switches on it would
+ * otherwise need two vocabularies to say the same three things. The label
+ * "Face ID" on an Android face-unlock device is the wrong brand; a value the
+ * page has never heard of is a blank button.
+ *
+ * ### The credential
+ *
+ * iOS stores the token in the keychain under `SecAccessControl(.biometryCurrentSet)`:
+ * reading it *is* the prompt, and iOS invalidates the item whenever biometric
+ * enrollment changes. The Android equivalent is an AES/GCM key in the
+ * AndroidKeyStore with `setUserAuthenticationRequired(true)` and
+ * `setInvalidatedByBiometricEnrollment(true)`, used through a `CryptoObject` —
+ * so the hardware, not this code, enforces both properties, and a new face or
+ * finger raises `KeyPermanentlyInvalidatedException`, which becomes the same
+ * `notEnrolled` iOS reports.
+ *
+ * The sealed bytes then go into EncryptedSharedPreferences. That is belt and
+ * braces rather than the actual protection — the value is already AES-GCM
+ * ciphertext under a hardware key — which is what makes it safe to fall back to
+ * plain SharedPreferences if `androidx.security-crypto` (still alpha, and known
+ * to fail to initialise on a handful of devices) throws at startup. The failure
+ * mode of that fallback is a re-enrollment, not an exposed token.
+ */
+class BiometricsComponent(
+    name: String,
+    private val delegate: BridgeDelegate<HotwireDestination>
+) : BridgeComponent<HotwireDestination>(name, delegate) {
+
+    private val fragment: Fragment
+        get() = delegate.destination.fragment
+
+    override fun onReceive(message: Message) {
+        val declared = EverywhereConfig.shared.declaresPermission("biometrics")
+
+        when (message.event) {
+            "query" ->
+                if (declared) query(message)
+                else reply(message, QueryReply(available = false, biometry = "none", status = "undeclared"))
+
+            "authenticate" ->
+                if (declared) authenticate(message)
+                else reply(message, AuthReply(authenticated = false, error = "undeclared"))
+
+            "credentialStore", "credentialGet", "credentialStatus", "credentialClear" ->
+                if (declared) credential(message)
+                else reply(message, CredentialReply(error = "undeclared"))
+
+            else -> Log.w(TAG, "Unknown event for message: $message")
+        }
+    }
+
+    // MARK: Availability
+
+    private fun query(message: Message) {
+        val context = fragment.context ?: return reply(
+            message, QueryReply(available = false, biometry = "none", status = "notAvailable")
+        )
+
+        val code = BiometricManager.from(context).canAuthenticate(BIOMETRIC_STRONG)
+        reply(
+            message,
+            QueryReply(
+                available = code == BiometricManager.BIOMETRIC_SUCCESS,
+                biometry = biometryName(context),
+                status = if (code == BiometricManager.BIOMETRIC_SUCCESS) "available"
+                else describeAvailability(code)
+            )
+        )
+    }
+
+    /**
+     * The hardware this device actually has. A device with more than one kind
+     * gets the most prominent — iOS reports a single type too, and the page is
+     * choosing one label.
+     */
+    private fun biometryName(context: Context): String {
+        val packages = context.packageManager
+        return when {
+            packages.hasSystemFeature(PackageManager.FEATURE_FACE) -> "faceID"
+            packages.hasSystemFeature(PackageManager.FEATURE_FINGERPRINT) -> "touchID"
+            packages.hasSystemFeature(PackageManager.FEATURE_IRIS) -> "opticID"
+            else -> "none"
+        }
+    }
+
+    /**
+     * `canAuthenticate` codes → the JS status vocabulary. Note the gap:
+     * Android surfaces a temporary lockout only from an authentication attempt
+     * (`ERROR_LOCKOUT`), never from this call, where it is indistinguishable
+     * from genuinely absent hardware. Calling that `lockout` here would tell the
+     * declarative gate to keep prompting a device with no sensor.
+     */
+    private fun describeAvailability(code: Int): String = when (code) {
+        BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED -> "notEnrolled"
+        BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE,
+        BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE,
+        BiometricManager.BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED,
+        BiometricManager.BIOMETRIC_ERROR_UNSUPPORTED -> "notAvailable"
+        else -> "notAvailable"
+    }
+
+    /**
+     * `BiometricPrompt` error codes → the same vocabulary. The negative button
+     * is ours and it says Cancel, so it is a cancel, not iOS's `fallback` (which
+     * is its "Enter Passcode" button — a thing `allowPasscode` handles here by
+     * putting the credential *inside* the same prompt).
+     */
+    private fun describeError(errorCode: Int): String = when (errorCode) {
+        BiometricPrompt.ERROR_USER_CANCELED,
+        BiometricPrompt.ERROR_CANCELED,
+        BiometricPrompt.ERROR_NEGATIVE_BUTTON -> "canceled"
+        BiometricPrompt.ERROR_LOCKOUT, BiometricPrompt.ERROR_LOCKOUT_PERMANENT -> "lockout"
+        BiometricPrompt.ERROR_NO_BIOMETRICS -> "notEnrolled"
+        BiometricPrompt.ERROR_HW_NOT_PRESENT, BiometricPrompt.ERROR_HW_UNAVAILABLE -> "notAvailable"
+        BiometricPrompt.ERROR_NO_DEVICE_CREDENTIAL -> "passcodeNotSet"
+        else -> "failed"
+    }
+
+    // MARK: Authenticate
+
+    private fun authenticate(message: Message) {
+        val data = message.data<Payload>()
+        val reason = data?.reason?.trim().takeUnless { it.isNullOrEmpty() } ?: "Confirm it's you."
+
+        prompt(reason, allowPasscode = data?.allowPasscode == true, crypto = null,
+            onError = { reply(message, AuthReply(authenticated = false, error = it)) },
+            onSuccess = { reply(message, AuthReply(authenticated = true)) })
+    }
+
+    // MARK: Credential
+
+    private fun credential(message: Message) {
+        val context = fragment.context ?: return reply(message, CredentialReply(error = "notAvailable"))
+        val data = message.data<Payload>()
+
+        when (message.event) {
+            "credentialStore" -> storeCredential(context, message, data)
+            "credentialGet" -> readCredential(context, message, data)
+            "credentialStatus" -> reply(
+                message,
+                CredentialReply(enrolled = readBlob(context) != null && keyExists())
+            )
+            else -> { // credentialClear
+                clearCredential(context)
+                reply(message, CredentialReply(cleared = true))
+            }
+        }
+    }
+
+    /**
+     * Storing runs the prompt too: writing doesn't need the key's ACL satisfied
+     * on every platform, but enabling a sign-in credential is a security change
+     * — confirm it's the owner. Same call, same reason, as iOS.
+     *
+     * The key is recreated from scratch on every store, mirroring iOS's
+     * delete-then-add: a store is a fresh enrollment, and it should be bound to
+     * the biometrics enrolled right now.
+     */
+    private fun storeCredential(context: Context, message: Message, data: Payload?) {
+        val token = data?.token
+        if (token.isNullOrEmpty()) {
+            return reply(message, CredentialReply(stored = false, error = "failed"))
+        }
+
+        deleteKey()
+        val cipher = try {
+            Cipher.getInstance(TRANSFORMATION).apply { init(Cipher.ENCRYPT_MODE, createKey()) }
+        } catch (e: Exception) {
+            Log.w(TAG, "credentialStore: could not prepare the key", e)
+            return reply(message, CredentialReply(stored = false, error = "notAvailable"))
+        }
+
+        prompt(
+            reason = data.reason?.trim().takeUnless { it.isNullOrEmpty() } ?: "Enable biometric sign-in",
+            allowPasscode = false,
+            crypto = BiometricPrompt.CryptoObject(cipher),
+            onError = { reply(message, CredentialReply(stored = false, error = it)) },
+            onSuccess = { result ->
+                val sealed = result?.cryptoObject?.cipher
+                val payload = try {
+                    requireNotNull(sealed)
+                    val bytes = sealed.doFinal(token.toByteArray(Charsets.UTF_8))
+                    writeBlob(context, encode(sealed.iv, bytes))
+                    CredentialReply(stored = true)
+                } catch (e: Exception) {
+                    Log.w(TAG, "credentialStore: failed", e)
+                    CredentialReply(stored = false, error = "failed")
+                }
+                reply(message, payload)
+            }
+        )
+    }
+
+    private fun readCredential(context: Context, message: Message, data: Payload?) {
+        val blob = readBlob(context)?.let(::decode)
+        val key = if (blob == null) null else loadKey()
+        if (blob == null || key == null) {
+            // Nothing stored, or the key is gone from under it. iOS answers the
+            // missing-item case `notEnrolled`, which the page reads as "offer
+            // password sign-in" — the right thing here too.
+            return reply(message, CredentialReply(error = "notEnrolled"))
+        }
+
+        val cipher = try {
+            Cipher.getInstance(TRANSFORMATION)
+                .apply { init(Cipher.DECRYPT_MODE, key, GCMParameterSpec(GCM_TAG_BITS, blob.first)) }
+        } catch (e: KeyPermanentlyInvalidatedException) {
+            // Biometric enrollment changed — the exact case iOS's
+            // .biometryCurrentSet flag covers. The stored bytes can never be
+            // read again, so clear them rather than leaving a permanent error.
+            Log.i(TAG, "credentialGet: invalidated by a biometric enrollment change")
+            clearCredential(context)
+            return reply(message, CredentialReply(error = "notEnrolled"))
+        } catch (e: Exception) {
+            Log.w(TAG, "credentialGet: could not prepare the cipher", e)
+            return reply(message, CredentialReply(error = "failed"))
+        }
+
+        prompt(
+            reason = data?.reason?.trim().takeUnless { it.isNullOrEmpty() } ?: "Sign in",
+            allowPasscode = false,
+            crypto = BiometricPrompt.CryptoObject(cipher),
+            onError = { reply(message, CredentialReply(error = it)) },
+            onSuccess = { result ->
+                val opened = result?.cryptoObject?.cipher
+                val payload = try {
+                    requireNotNull(opened)
+                    CredentialReply(token = String(opened.doFinal(blob.second), Charsets.UTF_8))
+                } catch (e: Exception) {
+                    Log.w(TAG, "credentialGet: failed", e)
+                    CredentialReply(error = "failed")
+                }
+                reply(message, payload)
+            }
+        )
+    }
+
+    private fun clearCredential(context: Context) {
+        deleteKey()
+        credentialPrefs(context)?.edit()?.remove(BLOB_KEY)?.apply()
+    }
+
+    // MARK: Prompt
+
+    /**
+     * One prompt for all four callers. `BiometricPrompt` must be built on the
+     * main thread and from a Fragment or FragmentActivity — which is exactly
+     * what a bridge component has, and why (unlike iOS, whose keychain calls
+     * block) nothing here needs a background queue.
+     *
+     * `onAuthenticationFailed` — a finger the sensor didn't recognise — is
+     * deliberately not an outcome: the prompt stays up and the user tries again,
+     * and answering the web there would settle a promise the user is still
+     * working on.
+     */
+    private fun prompt(
+        reason: String,
+        allowPasscode: Boolean,
+        crypto: BiometricPrompt.CryptoObject?,
+        onError: (String) -> Unit,
+        onSuccess: (BiometricPrompt.AuthenticationResult?) -> Unit
+    ) {
+        val context = fragment.context ?: return onError("notAvailable")
+
+        val builder = BiometricPrompt.PromptInfo.Builder()
+            // iOS's localizedReason is the prompt's own sentence, and the title
+            // is the most prominent text Android gives us for it.
+            .setTitle(reason)
+            .setConfirmationRequired(false)
+
+        // BIOMETRIC_STRONG or DEVICE_CREDENTIAL is unsupported below API 30, and
+        // the pre-30 API for it (setDeviceCredentialAllowed) is long deprecated.
+        // So on 28/29 allowPasscode degrades to biometrics-only rather than
+        // risking a prompt the framework refuses to show at all.
+        if (allowPasscode && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            builder.setAllowedAuthenticators(BIOMETRIC_STRONG or DEVICE_CREDENTIAL)
+        } else {
+            builder.setAllowedAuthenticators(BIOMETRIC_STRONG)
+            // Mandatory whenever a device credential isn't allowed, and it must
+            // not be set when one is.
+            builder.setNegativeButtonText("Cancel")
+        }
+
+        val prompt = BiometricPrompt(
+            fragment,
+            ContextCompat.getMainExecutor(context),
+            object : BiometricPrompt.AuthenticationCallback() {
+                override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
+                    onError(describeError(errorCode))
+                }
+
+                override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+                    onSuccess(result)
+                }
+            }
+        )
+
+        try {
+            if (crypto != null) prompt.authenticate(builder.build(), crypto)
+            else prompt.authenticate(builder.build())
+        } catch (e: Exception) {
+            Log.w(TAG, "biometric prompt could not be shown", e)
+            onError("notAvailable")
+        }
+    }
+
+    // MARK: Keystore
+
+    private fun keyAlias(): String =
+        (fragment.context?.packageName ?: "com.rubyeverywhere.app") + KEY_SUFFIX
+
+    private fun keyStore(): KeyStore? = try {
+        KeyStore.getInstance(KEYSTORE).apply { load(null) }
+    } catch (e: Exception) {
+        Log.w(TAG, "AndroidKeyStore unavailable", e)
+        null
+    }
+
+    private fun keyExists(): Boolean = try {
+        keyStore()?.containsAlias(keyAlias()) == true
+    } catch (e: Exception) {
+        false
+    }
+
+    private fun loadKey(): SecretKey? = try {
+        keyStore()?.getKey(keyAlias(), null) as? SecretKey
+    } catch (e: Exception) {
+        Log.w(TAG, "could not load the credential key", e)
+        null
+    }
+
+    private fun deleteKey() {
+        try {
+            keyStore()?.deleteEntry(keyAlias())
+        } catch (e: Exception) {
+            Log.w(TAG, "could not delete the credential key", e)
+        }
+    }
+
+    /**
+     * The two flags are the whole security model, and they are the direct
+     * translation of iOS's SecAccessControl: authentication required for every
+     * single use, and permanent invalidation when biometric enrollment changes.
+     */
+    private fun createKey(): SecretKey {
+        val builder = KeyGenParameterSpec.Builder(
+            keyAlias(),
+            KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
+        )
+            .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+            .setKeySize(256)
+            .setUserAuthenticationRequired(true)
+            .setInvalidatedByBiometricEnrollment(true)
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            // 0 seconds = every use needs a fresh authentication.
+            builder.setUserAuthenticationParameters(0, KeyProperties.AUTH_BIOMETRIC_STRONG)
+        } else {
+            @Suppress("DEPRECATION")
+            builder.setUserAuthenticationValidityDurationSeconds(-1) // the pre-30 spelling of the same thing
+        }
+
+        val generator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, KEYSTORE)
+        generator.init(builder.build())
+        return generator.generateKey()
+    }
+
+    // MARK: Sealed-blob storage
+
+    /**
+     * EncryptedSharedPreferences when it initialises, plain SharedPreferences
+     * when it doesn't. See the class comment: what is stored here is already
+     * AES-GCM ciphertext under a hardware-backed, biometric-gated key, so the
+     * encrypted file is defence in depth and the fallback costs a re-enrollment
+     * at worst — which is a far better outcome than a shell that crashes at
+     * launch on the devices where the alpha library misbehaves.
+     */
+    private fun credentialPrefs(context: Context): SharedPreferences? {
+        val app = context.applicationContext
+        cachedPrefs?.let { return it }
+
+        val prefs = try {
+            EncryptedSharedPreferences.create(
+                app,
+                ENCRYPTED_PREFS,
+                MasterKey.Builder(app).setKeyScheme(MasterKey.KeyScheme.AES256_GCM).build(),
+                EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+                EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+            )
+        } catch (e: Exception) {
+            Log.w(TAG, "EncryptedSharedPreferences unavailable; falling back to plain preferences", e)
+            app.getSharedPreferences(PLAIN_PREFS, Context.MODE_PRIVATE)
+        }
+
+        cachedPrefs = prefs
+        return prefs
+    }
+
+    private fun readBlob(context: Context): String? = credentialPrefs(context)?.getString(BLOB_KEY, null)
+
+    private fun writeBlob(context: Context, blob: String) {
+        credentialPrefs(context)?.edit()?.putString(BLOB_KEY, blob)?.apply()
+    }
+
+    private fun encode(iv: ByteArray, ciphertext: ByteArray): String =
+        Base64.encodeToString(iv, Base64.NO_WRAP) + "." + Base64.encodeToString(ciphertext, Base64.NO_WRAP)
+
+    private fun decode(blob: String): Pair<ByteArray, ByteArray>? = try {
+        val (iv, ciphertext) = blob.split(".", limit = 2)
+        Base64.decode(iv, Base64.NO_WRAP) to Base64.decode(ciphertext, Base64.NO_WRAP)
+    } catch (e: Exception) {
+        Log.w(TAG, "stored credential is unreadable", e)
+        null
+    }
+
+    /**
+     * Replies on the exact message that asked (same reasoning as
+     * PermissionsComponent: concurrent messages for one event make
+     * `replyTo(event)` target only the last-received message).
+     *
+     * Three concrete overloads rather than one `inline fun <reified T>`: wrapping
+     * `Message.replacing` — itself inline and reified — inside another inline
+     * function crashes the Kotlin 2.3 JVM backend while inlining the default
+     * argument. Passing `event` explicitly, and not nesting the inlines, keeps
+     * every call on the path the compiler can actually generate.
+     */
+    private fun reply(message: Message, payload: QueryReply) {
+        replyWith(message.replacing(event = message.event, data = payload))
+    }
+
+    private fun reply(message: Message, payload: AuthReply) {
+        replyWith(message.replacing(event = message.event, data = payload))
+    }
+
+    private fun reply(message: Message, payload: CredentialReply) {
+        replyWith(message.replacing(event = message.event, data = payload))
+    }
+
+    @Serializable
+    data class Payload(
+        @SerialName("reason") val reason: String? = null,
+        @SerialName("allowPasscode") val allowPasscode: Boolean? = null,
+        @SerialName("token") val token: String? = null
+    )
+
+    @Serializable
+    data class QueryReply(
+        @SerialName("available") val available: Boolean,
+        @SerialName("biometry") val biometry: String,
+        @SerialName("status") val status: String
+    )
+
+    @Serializable
+    data class AuthReply(
+        @SerialName("authenticated") val authenticated: Boolean,
+        @SerialName("error") val error: String? = null
+    )
+
+    @Serializable
+    data class CredentialReply(
+        @SerialName("stored") val stored: Boolean? = null,
+        @SerialName("token") val token: String? = null,
+        @SerialName("enrolled") val enrolled: Boolean? = null,
+        @SerialName("cleared") val cleared: Boolean? = null,
+        @SerialName("error") val error: String? = null
+    )
+
+    private companion object {
+        const val TAG = "EverywhereBiometrics"
+        const val KEYSTORE = "AndroidKeyStore"
+        const val KEY_SUFFIX = ".biometric-login"
+        const val TRANSFORMATION = "AES/GCM/NoPadding"
+        const val GCM_TAG_BITS = 128
+        const val ENCRYPTED_PREFS = "everywhere.credential"
+        const val PLAIN_PREFS = "everywhere.credential.plain"
+        const val BLOB_KEY = "login"
+
+        /** Building EncryptedSharedPreferences is expensive; the file is one per app. */
+        @Volatile
+        var cachedPrefs: SharedPreferences? = null
+    }
+}

data/support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/bridge/HapticsComponent.kt

@@ -0,0 +1,141 @@
+package com.rubyeverywhere.shell.bridge
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import android.os.VibrationEffect
+import android.os.Vibrator
+import android.os.VibratorManager
+import android.util.Log
+import android.view.HapticFeedbackConstants
+import android.view.View
+import androidx.core.content.ContextCompat
+import dev.hotwire.core.bridge.BridgeComponent
+import dev.hotwire.core.bridge.BridgeDelegate
+import dev.hotwire.core.bridge.Message
+import dev.hotwire.navigation.destinations.HotwireDestination
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ * Bridge component backing `everywhere--haptics`: plays impact, notification and
+ * selection feedback for `Everywhere.haptics.*` calls from the page. Three
+ * events — `impact` `{style}`, `notification` `{type}`, `selection` `{}` — and
+ * no reply at all, exactly like iOS's HapticsComponent.swift.
+ *
+ * Impact and selection go through `View.performHapticFeedback`, which is the
+ * closest thing Android has to `UIImpactFeedbackGenerator`: the system picks the
+ * waveform, respects the user's haptics setting, and — the practical part — it
+ * needs **no VIBRATE permission**. The shell's manifest only declares the
+ * permissions everywhere.yml asked for, so anything that assumed VIBRATE would
+ * throw in most apps.
+ *
+ * Notification feedback has no `performHapticFeedback` analogue below API 30
+ * and no three-way one above it, so those three get real waveforms — but only
+ * when VIBRATE happens to be granted. `checkSelfPermission` on a normal
+ * permission is exactly a manifest check, which makes this a clean feature
+ * detect rather than a gamble; without it we fall back to the nearest constant.
+ * The patterns mirror the Vibration-API fallback in bridge.js, so a page feels
+ * the same shape of buzz in an Android browser and in the shell.
+ */
+class HapticsComponent(
+    name: String,
+    private val delegate: BridgeDelegate<HotwireDestination>
+) : BridgeComponent<HotwireDestination>(name, delegate) {
+
+    private val view: View?
+        get() = delegate.destination.fragment.view
+
+    override fun onReceive(message: Message) {
+        when (message.event) {
+            "impact" -> impact(message.data<Payload>()?.style)
+            "notification" -> notification(message.data<Payload>()?.type)
+            "selection" -> perform(HapticFeedbackConstants.CLOCK_TICK)
+            else -> Log.w(TAG, "Unknown event for message: $message")
+        }
+    }
+
+    private fun impact(style: String?) {
+        perform(
+            when (style) {
+                // CLOCK_TICK is Android's lightest standard tick; LONG_PRESS is
+                // its heaviest. "soft"/"rigid" differ on iOS in sharpness rather
+                // than strength, which Android's constants don't express, so
+                // they map onto the nearest light and medium.
+                "light", "soft" -> HapticFeedbackConstants.CLOCK_TICK
+                "heavy" -> HapticFeedbackConstants.LONG_PRESS
+                "rigid" -> HapticFeedbackConstants.CONTEXT_CLICK
+                else -> HapticFeedbackConstants.VIRTUAL_KEY // medium
+            }
+        )
+    }
+
+    private fun notification(type: String?) {
+        val pattern = when (type) {
+            "error" -> longArrayOf(0, 30, 60, 30)
+            "warning" -> longArrayOf(0, 20, 40, 20)
+            else -> longArrayOf(0, 10, 30, 10) // success
+        }
+
+        if (vibrate(pattern)) return
+
+        // No VIBRATE: API 30 has purpose-built confirm/reject constants, and
+        // below that a plain key click is the most honest approximation.
+        perform(
+            when {
+                Build.VERSION.SDK_INT < Build.VERSION_CODES.R -> HapticFeedbackConstants.VIRTUAL_KEY
+                type == "error" -> HapticFeedbackConstants.REJECT
+                type == "warning" -> HapticFeedbackConstants.LONG_PRESS
+                else -> HapticFeedbackConstants.CONFIRM
+            }
+        )
+    }
+
+    private fun perform(constant: Int) {
+        view?.performHapticFeedback(constant)
+    }
+
+    /** @return false when there is no vibrator or no VIBRATE permission. */
+    private fun vibrate(pattern: LongArray): Boolean {
+        val context = view?.context ?: return false
+        if (ContextCompat.checkSelfPermission(context, Manifest.permission.VIBRATE)
+            != PackageManager.PERMISSION_GRANTED
+        ) {
+            return false
+        }
+
+        val vibrator = vibrator(context) ?: return false
+        if (!vibrator.hasVibrator()) return false
+
+        return try {
+            vibrator.vibrate(VibrationEffect.createWaveform(pattern, -1))
+            true
+        } catch (e: Exception) {
+            Log.w(TAG, "vibrate failed", e)
+            false
+        }
+    }
+
+    @Suppress("DEPRECATION")
+    private fun vibrator(context: Context): Vibrator? =
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            context.getSystemService(VibratorManager::class.java)?.defaultVibrator
+        } else {
+            context.getSystemService(Context.VIBRATOR_SERVICE) as? Vibrator
+        }
+
+    /**
+     * One payload for all three events, matching iOS: `impact` sends `{style}`,
+     * `notification` sends `{type}`, `selection` sends `{}`.
+     */
+    @Serializable
+    data class Payload(
+        @SerialName("style") val style: String? = null,
+        @SerialName("type") val type: String? = null
+    )
+
+    private companion object {
+        const val TAG = "EverywhereHaptics"
+    }
+}