feat: add native passkey authentication for mobile app via expo-better-auth-passkey

Medformatik · Medformatik · commit 37ee9ad238ac · 2026-03-30T02:57:26.000+02:00
Replace browser-only passkeyClient() with expo-better-auth-passkey on native, enabling passkey registration and sign-in on iOS (ASAuthorizationController) and Android (Credential Manager). The core auth client now accepts a passkeyPlugin override so each platform can supply its own implementation.

- Add expo-better-auth-passkey dependency and wire expoPasskeyClient() into mobile config
- Add "Sign in with passkey" button to mobile AuthDialog (mirrors web)
- Support multi-origin PASSKEY_ORIGIN (comma-separated) for web + mobile
- Add .well-known static server (nginx) to Docker Compose for apple-app-site-association and assetlinks.json
- Register well-known service in manage.sh (app profile, service resolution)
- Add iOS associatedDomains (webcredentials) to app.config.ts
- Change bundle ID to org.openmapx.app (iOS + Android)
- Add apps/mobile/.env.example with all EXPO_PUBLIC_* env vars
diff --git a/apps/api/.env.example b/apps/api/.env.example
@@ -109,7 +109,10 @@ OSM_CLIENT_SECRET=
 # Passkeys / WebAuthn
 # RP ID must match the domain users access the app from
 PASSKEY_RP_ID=127.0.0.1
-PASSKEY_ORIGIN=http://127.0.0.1:3000
+# Comma-separated list of allowed origins (web + mobile)
+# For Android: add android:apk-key-hash:<BASE64_SHA256> for each signing certificate
+# For iOS: the RP ID domain must have a .well-known/apple-app-site-association file
+PASSKEY_ORIGIN=http://127.0.0.1:3000,openmapx://
 
 # SMTP (for verification emails, 2FA codes, email change)
 # Any SMTP provider works (e.g. Mailgun, Postmark, Amazon SES, self-hosted)
diff --git a/apps/api/src/auth.ts b/apps/api/src/auth.ts
@@ -211,7 +211,9 @@ export const auth = betterAuth({
     passkey({
       rpID: process.env.PASSKEY_RP_ID ?? "localhost",
       rpName: "OpenMapX",
-      origin: process.env.PASSKEY_ORIGIN ?? "http://localhost:3000",
+      origin: process.env.PASSKEY_ORIGIN
+        ? process.env.PASSKEY_ORIGIN.split(",").map((o) => o.trim())
+        : ["http://localhost:3000"],
     }),
     genericOAuth({
       config: [
diff --git a/apps/mobile/.env.example b/apps/mobile/.env.example
@@ -0,0 +1,20 @@
+# URL of the API server (apps/api)
+EXPO_PUBLIC_API_URL=http://localhost:3001
+
+# URL of the web app (used for legal pages WebView)
+# EXPO_PUBLIC_WEB_URL=https://openmapx.com
+
+# MapTiler Cloud API key — get yours at https://cloud.maptiler.com
+# Required for map tiles, transit overlay, and cycling overlay
+EXPO_PUBLIC_MAPTILER_KEY=your_maptiler_key_here
+
+# Mapillary access token for street-level imagery
+# Get yours at https://www.mapillary.com/dashboard/developers
+EXPO_PUBLIC_MAPILLARY_TOKEN=your_mapillary_token_here
+
+# Passkeys / WebAuthn
+# Must match PASSKEY_RP_ID on the API server (the domain hosting .well-known files)
+# EXPO_PUBLIC_PASSKEY_RP_ID=localhost
+
+# Optional: override CyclOSM tile URL template
+# EXPO_PUBLIC_CYCLOSM_TILE_URL_TEMPLATE=https://{s}.tile-cyclosm.openstreetmap.fr/cyclosm/{z}/{x}/{y}.png
diff --git a/apps/mobile/app.config.ts b/apps/mobile/app.config.ts
@@ -13,19 +13,21 @@ export default ({ config }: ConfigContext): ExpoConfig => ({
   userInterfaceStyle: "automatic",
   ios: {
     supportsTablet: true,
-    bundleIdentifier: "com.openmapx.app",
+    bundleIdentifier: "org.openmapx.app",
+    associatedDomains: [`webcredentials:${process.env.EXPO_PUBLIC_PASSKEY_RP_ID ?? "localhost"}`],
   },
   android: {
     adaptiveIcon: {
       backgroundColor: "#ffffff",
       foregroundImage: "./assets/images/icon.png",
     },
-    package: "com.openmapx.app",
+    package: "org.openmapx.app",
   },
   plugins: [
     "expo-router",
     "expo-localization",
     "expo-secure-store",
+    "expo-better-auth-passkey",
     "@maplibre/maplibre-react-native",
     [
       "expo-location",
diff --git a/apps/mobile/package.json b/apps/mobile/package.json
@@ -27,6 +27,7 @@
     "@turf/helpers": "^7.3.4",
     "@turf/length": "^7.3.4",
     "expo": "~55.0.0",
+    "expo-better-auth-passkey": "^1.4.1",
     "expo-clipboard": "~55.0.9",
     "expo-constants": "~55.0.9",
     "expo-dev-client": "~55.0.18",
diff --git a/apps/mobile/src/components/auth/AuthDialog.tsx b/apps/mobile/src/components/auth/AuthDialog.tsx
@@ -1,4 +1,4 @@
-import { MaterialIcons } from "@expo/vector-icons";
+import { MaterialCommunityIcons, MaterialIcons } from "@expo/vector-icons";
 import { authClient, oauthProviders } from "@openmapx/core";
 import { useCallback, useState } from "react";
 import { useTranslation } from "react-i18next";
@@ -184,6 +184,25 @@ export function AuthDialog({ visible, onDismiss }: AuthDialogProps) {
     }
   }, [email, resetOtp, newPassword, resetForm, t]);
 
+  const handlePasskeySignIn = useCallback(async () => {
+    Keyboard.dismiss();
+    setLoading(true);
+    setError(null);
+    try {
+      const { error: passkeyError } = await authClient.signIn.passkey();
+      if (passkeyError) {
+        if ("code" in passkeyError && passkeyError.code === "AUTH_CANCELLED") return;
+        setError(String(passkeyError.message ?? t("auth.passkeySignInFailed")));
+        return;
+      }
+      handleClose();
+    } catch {
+      setError(t("auth.passkeyAuthFailed"));
+    } finally {
+      setLoading(false);
+    }
+  }, [handleClose, t]);
+
   const handleOAuthSignIn = useCallback(
     async (providerId: string, providerName: string) => {
       setLoading(true);
@@ -456,6 +475,22 @@ export function AuthDialog({ visible, onDismiss }: AuthDialogProps) {
 
               <Divider style={styles.divider} />
 
+              {/* Passkey sign-in */}
+              {mode === "sign-in" && (
+                <Button
+                  mode="outlined"
+                  onPress={handlePasskeySignIn}
+                  disabled={loading}
+                  icon={({ size, color }) => (
+                    <MaterialCommunityIcons name="key-variant" size={size} color={color} />
+                  )}
+                  style={styles.oauthButton}
+                  labelStyle={{ color: theme.colors.onSurface }}
+                >
+                  {t("auth.signInWithPasskey")}
+                </Button>
+              )}
+
               {/* OAuth providers */}
               {oauthProviders.map((provider) => (
                 <Button
diff --git a/apps/mobile/src/lib/config.ts b/apps/mobile/src/lib/config.ts
@@ -1,5 +1,6 @@
 import { expoClient } from "@better-auth/expo/client";
 import { authClient, configureApiClient, configureStorage, initAuth } from "@openmapx/core";
+import { expoPasskeyClient } from "expo-better-auth-passkey";
 import * as SecureStore from "expo-secure-store";
 import { mmkvStorageAdapter } from "./storage";
 
@@ -12,6 +13,7 @@ export function initPlatform(): void {
   // the header interceptor can call authClient.getCookie().
   initAuth({
     baseURL: API_URL,
+    passkeyPlugin: expoPasskeyClient(),
     platformPlugins: [
       expoClient({
         scheme: "openmapx",
diff --git a/infra/docker/docker-compose.yml b/infra/docker/docker-compose.yml
@@ -7,7 +7,7 @@
 # Profiles:
 #   (none)    Core: postgis, redis
 #   proxy     Traefik reverse proxy (TLS termination, path-based routing)
-#   app       API + Web (Fastify + Next.js, built from repo)
+#   app       API + Web + .well-known (Fastify + Next.js + passkey domain files)
 #   routing   Valhalla + OSRM (Valhalla handles planet, OSRM region-only)
 #   transit   MOTIS + OTP (MOTIS handles planet, OTP region-only)
 #   pelias    Elasticsearch + Pelias (self-hosted geocoding)
@@ -88,7 +88,7 @@ services:
       CORS_ORIGIN: https://${DOMAIN:-localhost},http://localhost:3000
       BETTER_AUTH_URL: https://${DOMAIN:-localhost}
       PASSKEY_RP_ID: ${DOMAIN:-localhost}
-      PASSKEY_ORIGIN: https://${DOMAIN:-localhost}
+      PASSKEY_ORIGIN: https://${DOMAIN:-localhost},openmapx://
     depends_on:
       postgis:
         condition: service_healthy
@@ -144,6 +144,25 @@ services:
         limits:
           memory: 512m
 
+  well-known:
+    image: nginx:alpine
+    profiles: [app]
+    volumes:
+      - ./well-known:/usr/share/nginx/html/.well-known:ro
+      - ./well-known/nginx.conf:/etc/nginx/conf.d/default.conf:ro
+    labels:
+      traefik.enable: "true"
+      traefik.http.routers.well-known.rule: Host(`${DOMAIN:-localhost}`) && PathPrefix(`/.well-known`)
+      traefik.http.routers.well-known.entrypoints: websecure
+      traefik.http.routers.well-known.tls.certresolver: letsencrypt
+      traefik.http.services.well-known.loadbalancer.server.port: "80"
+    networks: [openmapx]
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 32m
+
   # Core Infrastructure
 
   postgis:
diff --git a/infra/docker/manage.sh b/infra/docker/manage.sh
@@ -104,7 +104,7 @@ profile_to_services() {
   case "$1" in
     core)       echo "postgis redis" ;;
     proxy)      echo "traefik" ;;
-    app)        echo "api web" ;;
+    app)        echo "api web well-known" ;;
     routing)    echo "valhalla osrm" ;;
     transit)    echo "motis otp" ;;
     pelias)     echo "elasticsearch pelias-api pelias-placeholder pelias-pip" ;;
@@ -126,7 +126,7 @@ is_profile() {
 
 is_service() {
   case "$1" in
-    postgis|redis|traefik|api|web|valhalla|osrm|motis|otp) return 0 ;;
+    postgis|redis|traefik|api|web|well-known|valhalla|osrm|motis|otp) return 0 ;;
     elasticsearch|pelias-api|pelias-placeholder|pelias-pip) return 0 ;;
     nominatim|photon|overpass|tileserver|martin)            return 0 ;;
     *) return 1 ;;
diff --git a/infra/docker/well-known/apple-app-site-association b/infra/docker/well-known/apple-app-site-association
@@ -0,0 +1,7 @@
+{
+  "webcredentials": {
+    "apps": [
+      "TEAM_ID.org.openmapx.app"
+    ]
+  }
+}
diff --git a/infra/docker/well-known/assetlinks.json b/infra/docker/well-known/assetlinks.json
@@ -0,0 +1,13 @@
+[
+  {
+    "relation": [
+      "delegate_permission/common.get_login_creds",
+      "delegate_permission/common.handle_all_urls"
+    ],
+    "target": {
+      "namespace": "android_app",
+      "package_name": "org.openmapx.app",
+      "sha256_cert_fingerprints": ["REPLACE_WITH_SHA256_FINGERPRINT"]
+    }
+  }
+]
diff --git a/infra/docker/well-known/nginx.conf b/infra/docker/well-known/nginx.conf
@@ -0,0 +1,12 @@
+server {
+    listen 80;
+    root /usr/share/nginx/html;
+
+    location /.well-known/apple-app-site-association {
+        default_type application/json;
+    }
+
+    location /.well-known/assetlinks.json {
+        default_type application/json;
+    }
+}
diff --git a/packages/core/src/auth/client.ts b/packages/core/src/auth/client.ts
@@ -5,6 +5,8 @@ import { createAuthClient } from "better-auth/react";
 export interface AuthConfig {
   baseURL: string;
   platformPlugins?: unknown[];
+  /** Override the default passkeyClient() — e.g. with expoPasskeyClient() on native. */
+  passkeyPlugin?: unknown;
 }
 
 /** Helper used only for its return type — captures the full plugin-augmented shape. */
@@ -25,7 +27,7 @@ export function initAuth(config: AuthConfig): void {
     baseURL: config.baseURL,
     basePath: "/api/auth",
     plugins: [
-      passkeyClient(),
+      (config.passkeyPlugin ?? passkeyClient()) as ReturnType<typeof passkeyClient>,
       genericOAuthClient(),
       twoFactorClient(),
       emailOTPClient(),
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
