Imported from LaunchPadLab/ai-bank (claude/skills/hotwire-native-auth/SKILL.md). Install upstream with npx skills add LaunchPadLab/ai-bank --skill hotwire-native-auth. Copyright stays with the author.

Hotwire Native: Web-Based Authentication

Overview

Web-based authentication reuses your existing Rails authentication screens and logic for Hotwire Native iOS and Android apps. Instead of building native login UI with SwiftUI/Jetpack Compose and JSON API endpoints, the native app renders the same /session/new HTML form and submits it via the web view.

Benefits over native authentication:

Zero additional native UI code for login screens
Zero additional API endpoints
Reuses existing server-side authentication logic
Single source of truth: the Rails server

Architecture

┌─────────────────────────────────────────────────────┐
│                    Rails Server                      │
│  ┌─────────────┐  ┌──────────┐  ┌────────────────┐ │
│  │ Auth Concern │  │ Sessions │  │ Layout <meta>  │ │
│  │ (permanent   │  │Controller│  │ data-bridge-   │ │
│  │  cookie)     │  │          │  │ authenticated  │ │
│  └─────────────┘  └──────────┘  └───────┬────────┘ │
└─────────────────────────────────────────┼───────────┘
                                          │
              ┌───────────────────────────┼──────┐
              │  JS Bridge Component      │      │
              │  (Stimulus controller)    ▼      │
              │  sends signIn/signOut message    │
              └──────────┬──────────────────────┘
                         │
            ┌────────────┼────────────┐
            ▼                         ▼
   ┌─────────────────┐    ┌─────────────────────┐
   │  iOS Bridge      │    │  Android Bridge      │
   │  Component       │    │  Component           │
   │  → SceneDelegate │    │  → MainActivity      │
   │  → Toggle tabs   │    │  → Toggle bottom nav │
   └─────────────────┘    └─────────────────────┘

Implementation Steps

Step 1: Generate a Long-Lived Cookie

Use cookies.signed.permanent so the session persists even after the native app is closed.

Rolling your own auth (or Rails 8 authentication generator):

Keep this cookie shape aligned with the web authentication concern and Action Cable connection. This skill standardizes on a signed, permanent session_token cookie whose value is session.token.

# app/controllers/concerns/authentication.rb
def start_new_session_for(user)
  session = user.sessions.create!(
    ip_address: request.remote_ip,
    user_agent: request.user_agent
  )
  Current.session = session
  cookies.signed.permanent[:session_token] = {
    value: session.token, httponly: true, same_site: :lax
  }
end

If using Devise, always remember the user on native:

<%= form_with url: session_path do |form| %>
  <% if hotwire_native_app? %>
    <%= form.hidden_field :remember_me, value: true %>
  <% else %>
    <%= form.check_box :remember_me %>
    <%= form.label :remember_me %>
  <% end %>
<% end %>

Step 2: Surface the Authentication Status

Add a <meta> tag in your application layout that exposes auth state on every page:

<%# app/views/layouts/application.html.erb %>
<html>
  <body>
    <meta data-controller="bridge--authentication"
      data-bridge-authenticated="<%= authenticated? %>">
    <%# ... %>
  </body>
</html>

Create the bridge Stimulus controller:

bin/rails generate stimulus bridge/authentication

// app/javascript/controllers/bridge/authentication_controller.js
import { BridgeComponent } from "@hotwired/hotwire-native-bridge"

export default class extends BridgeComponent {
  static component = "authentication"

  connect() {
    const authenticated = this.bridgeElement
      .bridgeAttribute("authenticated") === "true"

    if (authenticated) {
      this.send("signIn")
    } else {
      this.send("signOut")
    }
  }
}

Gotcha: bridgeAttribute() returns a string, not a boolean. Both "true" and "false" are truthy in JavaScript. You MUST compare with === "true".

Pin the bridge package in your importmap:

# config/importmap.rb
pin "@hotwired/hotwire-native-bridge", to: "@hotwired--hotwire-native-bridge.js"

Step 3: Create Native Bridge Components

iOS Bridge Component

// App/Components/AuthenticationComponent.swift
import HotwireNative

class AuthenticationComponent: BridgeComponent {
    override nonisolated class var name: String { "authentication" }

    override func onReceive(message: Message) {
        switch message.event {
        case "signIn": sceneDelegate?.signIn()
        case "signOut": sceneDelegate?.signOut()
        default: print("AuthenticationComponent", "Unknown event: \(message)")
        }
    }

    private var viewController: UIViewController? {
        delegate?.destination as? UIViewController
    }

    private var sceneDelegate: SceneDelegate? {
        viewController?.view.window?
            .windowScene?.delegate as? SceneDelegate
    }
}

Hotwire.registerBridgeComponents([
    AuthenticationComponent.self
])

Android Bridge Component

// AuthenticationComponent.kt
class AuthenticationComponent(
    name: String,
    private val delegate: BridgeDelegate<HotwireDestination>
) : BridgeComponent<HotwireDestination>(name, delegate) {
    private val fragment: Fragment
        get() = delegate.destination.fragment

    private val mainActivity: MainActivity
        get() = fragment.activity as MainActivity

    override fun onReceive(message: Message) {
        when (message.event) {
            "signIn" -> mainActivity.signIn()
            "signOut" -> mainActivity.signOut()
        }
    }
}

Hotwire.registerBridgeComponents(
    BridgeComponentFactory("authentication", ::AuthenticationComponent)
)

Step 4: Toggle the Tab Bar

iOS SceneDelegate

func signIn() {
    if tabBarController.viewControllers?.count != Tab.all.count {
        tabBarController.setTabBarHidden(false, animated: true)
        tabBarController.load(Tab.all)
    }
}

func signOut() {
    if tabBarController.viewControllers?.count != 1 {
        tabBarController.setTabBarHidden(true, animated: true)
        tabBarController.load(Tab.unauthenticated)
    }
}

Android MainActivity

fun signIn() {
    if (bottomNavigationController?.tabs?.size != tabs.size) {
        bottomNavigationController?.visibility = Visibility.DEFAULT
        bottomNavigationController?.load(tabs)
        delegate.resetNavigators()
    }
}

fun signOut() {
    if (bottomNavigationController?.tabs?.size != unauthenticatedTabs.size) {
        bottomNavigationController?.visibility = Visibility.HIDDEN
        bottomNavigationController?.load(unauthenticatedTabs)
        delegate.resetNavigators()
    }
}

Gotcha - Infinite loop: The bridge component fires on every page load. Without the idempotency guard (if ... count != ...), signing in calls signIn() for each tab, which reloads tabs, which triggers signIn() again - infinite loop.

Android-specific: You must call delegate.resetNavigators() after load() because on Android, load() only sets up UI and callbacks - it doesn't trigger network requests.

Supporting Rails Setup

Native-Only CSS

Conditionally load a stylesheet that hides web-only elements from native apps:

<%# app/views/layouts/application.html.erb %>
<% if hotwire_native_app? %>
  <%= stylesheet_link_tag "native" %>
<% end %>

/* app/assets/stylesheets/native.css */
.d-hotwire-native-none {
  display: none;
}

Apply to elements like page headers that are redundant in native apps:

<header class="d-hotwire-native-none">
  <%= link_to "Home", root_path %>
</header>

Path Configuration Controller

Serve path configuration JSON so native apps know which URLs should be modals:

# app/controllers/configurations_controller.rb
class ConfigurationsController < ApplicationController
  allow_unauthenticated_access

  def ios
    render json: {
      settings: {},
      rules: [
        { patterns: ["/new$", "/edit$"], properties: { context: "modal" } },
        { patterns: ["/session/new"], properties: { context: "default" } }
      ]
    }
  end

  def android
    render json: {
      settings: {},
      rules: [
        { patterns: [".*"], properties: { context: "default", pull_to_refresh_enabled: true } },
        { patterns: ["/new$", "/edit$"], properties: { context: "modal" } },
        { patterns: ["/session/new"], properties: { context: "default" } }
      ]
    }
  end
end

# config/routes.rb
resource :configuration, only: [], constraints: { format: :json } do
  get :ios, on: :member
  get :android, on: :member
end

Important: /session/new must be context: "default" (not modal) so the sign-in screen displays as a full page, and place it after the modal rules so it takes precedence.

Sign-In View for Native

Hide the page header on native since navigation is handled natively:

<%# app/views/sessions/new.html.erb %>
<header class="d-hotwire-native-none">
  <h1>Sign In</h1>
</header>

<%= form_with url: session_path, data: { turbo_action: "replace" } do |form| %>
  <%= form.email_field :email_address %>
  <%= form.password_field :password %>
  <%= form.submit "Sign in" %>
<% end %>

Use data: { turbo_action: "replace" } on the form so Turbo replaces the page instead of pushing to the navigation stack after sign-in.

Workflow Checklist

Hotwire Native Auth Implementation:

Rails:
- [ ] Authentication uses cookies.signed.permanent (not session-only cookies)
- [ ] <meta> tag with data-bridge-authenticated in application layout
- [ ] Bridge Stimulus controller at bridge/authentication_controller.js
- [ ] @hotwired/hotwire-native-bridge pinned in importmap
- [ ] native.css loaded conditionally for hotwire_native_app?
- [ ] .d-hotwire-native-none hides web headers in native
- [ ] Path configuration endpoints (iOS + Android)
- [ ] /session/new set to default context (not modal)
- [ ] Sign-in form uses data-turbo-action="replace"

iOS:
- [ ] AuthenticationComponent registered in AppDelegate
- [ ] SceneDelegate has signIn()/signOut() with idempotency guards
- [ ] Tab definitions for authenticated and unauthenticated states
- [ ] Path configuration loaded from server
- [ ] App starts in unauthenticated state

Android:
- [ ] AuthenticationComponent registered in Application subclass
- [ ] MainActivity has signIn()/signOut() with idempotency guards
- [ ] delegate.resetNavigators() called after loading tabs
- [ ] Tab definitions for authenticated and unauthenticated states
- [ ] activity_main.xml has FragmentContainerViews + BottomNavigationView
- [ ] Path configuration loaded from server
- [ ] App starts in unauthenticated state

Common Gotchas

Issue	Cause	Fix
Bridge never fires	Missing `@hotwired/hotwire-native-bridge` pin	Add to importmap.rb
Auth always truthy in JS	`bridgeAttribute()` returns string	Compare with `=== "true"`
Infinite loop on sign in	`signIn()` reloads tabs, triggers bridge again	Add idempotency check on tab count
Tab bar flashes on cold start	App starts with all tabs visible	Start in unauthenticated state
Android tabs don't load content	`load()` doesn't trigger requests	Call `delegate.resetNavigators()`
Sign-in opens as modal	Path config matches `/new$`	Add `/session/new` rule with `context: "default"` after modal rules
Native app loses session	Cookie not permanent	Use `cookies.signed.permanent`

References

See rails-setup.md for complete Rails-side code
See ios-setup.md for complete iOS code
See android-setup.md for complete Android code

hotwire-native-auth

About