chore: update version number to 0.1.38

VERSION

@@ -1 +1 @@
-0.1.35
+0.1.38

app.config.js

@@ -20,6 +20,7 @@ module.exports = {
   expo: {
     name: 'Bulwark Mobile',
     slug: 'bulwark-mobile',
+    scheme: 'bulwarkmobile',
     version: VERSION,
     orientation: 'portrait',
     icon: './assets/icon.png',

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bulwark-mobile",
-  "version": "0.1.35",
+  "version": "0.1.38",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bulwark-mobile",
-      "version": "0.1.35",
+      "version": "0.1.38",
       "license": "AGPL-3.0-only",
       "dependencies": {
         "@react-native-async-storage/async-storage": "2.2.0",
@@ -25,6 +25,7 @@
         "expo-secure-store": "~15.0.8",
         "expo-sharing": "~14.0.8",
         "expo-status-bar": "~3.0.9",
+        "expo-web-browser": "~15.0.8",
         "lucide-react-native": "^1.7.0",
         "react": "19.1.0",
         "react-native": "0.81.5",
@@ -5418,6 +5419,16 @@
         "react-native": "*"
       }
     },
+    "node_modules/expo-web-browser": {
+      "version": "15.0.11",
+      "resolved": "https://registry.npmjs.org/expo-web-browser/-/expo-web-browser-15.0.11.tgz",
+      "integrity": "sha512-r2LS4Ro6DgUPZkcaEfgt8mp9eJuoA93x11Jh7S6utFe0FEzvUNn2yFhxg8XVwESaaHGt2k5V8LuK36rsp0BeIw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "expo": "*",
+        "react-native": "*"
+      }
+    },
     "node_modules/expo/node_modules/@babel/code-frame": {
       "version": "7.29.0",
       "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.0.tgz",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulwark-mobile",
-  "version": "0.1.35",
+  "version": "0.1.38",
   "license": "AGPL-3.0-only",
   "main": "index.ts",
   "scripts": {
@@ -31,6 +31,7 @@
     "expo-secure-store": "~15.0.8",
     "expo-sharing": "~14.0.8",
     "expo-status-bar": "~3.0.9",
+    "expo-web-browser": "~15.0.8",
     "lucide-react-native": "^1.7.0",
     "react": "19.1.0",
     "react-native": "0.81.5",

src/api/jmap-client.ts

@@ -8,6 +8,11 @@ import type {
 import { CAPABILITIES } from './types';
 import { generateAccountId } from '../lib/account-utils';
 import { secureFetch } from '../lib/client-cert';
+import { refreshOAuthAccessToken, type OAuthTokens } from '../lib/oauth';
+
+// Refresh OAuth access tokens this many ms before they actually expire so
+// in-flight requests don't race the expiry window.
+const TOKEN_REFRESH_LEEWAY_MS = 60_000;
 
 const LEGACY_CREDENTIALS_KEY = 'jmap_credentials';
 const CREDENTIALS_PREFIX = 'jmap_credentials__';
@@ -22,6 +27,13 @@ export interface StoredCredentials {
   username: string;
   password: string;
   accessToken?: string;
+  // OAuth-only — present when credentials came in via the webmail handoff
+  // OAuth path rather than password auth. The token endpoint and client id
+  // are needed for refresh; without them the access token would just expire.
+  refreshToken?: string;
+  expiresAt?: number;
+  tokenEndpoint?: string;
+  clientId?: string;
 }
 
 export class JMAPClient {
@@ -93,6 +105,113 @@ export class JMAPClient {
     return this.session;
   }
 
+  // OAuth login via webmail handoff. The webmail did the OAuth dance against
+  // Stalwart and handed us a complete token bundle. We persist the bundle
+  // so subsequent launches can refresh without prompting the user again.
+  async connectWithOAuth(
+    serverUrl: string,
+    tokens: OAuthTokens,
+  ): Promise<{ session: JMAPSession; username: string; accountId: string }> {
+    const baseUrl = serverUrl.replace(/\/+$/, '');
+    this.credentials = {
+      serverUrl: baseUrl,
+      username: '',
+      password: '',
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken,
+      expiresAt: tokens.expiresAt,
+      tokenEndpoint: tokens.tokenEndpoint,
+      clientId: tokens.clientId,
+    };
+
+    this.session = this.rewriteSessionUrls(await this.fetchSession(baseUrl), baseUrl);
+    this._accountId = this.resolveAccountId(this.session);
+
+    // The JMAP session document carries the authenticated user's identifier
+    // — use it as the username so per-account storage keys are stable across
+    // restarts and OAuth re-logins.
+    const username = this.session.username || tokens.accessToken.slice(0, 8);
+    this.credentials.username = username;
+
+    const accountId = generateAccountId(username, baseUrl);
+    await SecureStore.setItemAsync(
+      credentialsKey(accountId),
+      JSON.stringify(this.credentials),
+    );
+
+    return { session: this.session, username, accountId };
+  }
+
+  private async persistRefreshedTokens(next: OAuthTokens): Promise<void> {
+    if (!this.credentials) return;
+    this.credentials = {
+      ...this.credentials,
+      accessToken: next.accessToken,
+      // Some IdPs rotate refresh tokens; others reuse. Fall back to the
+      // existing one when the response omits it.
+      refreshToken: next.refreshToken ?? this.credentials.refreshToken,
+      expiresAt: next.expiresAt,
+      tokenEndpoint: next.tokenEndpoint,
+      clientId: next.clientId,
+    };
+    const accountId = generateAccountId(
+      this.credentials.username,
+      this.credentials.serverUrl,
+    );
+    await SecureStore.setItemAsync(
+      credentialsKey(accountId),
+      JSON.stringify(this.credentials),
+    );
+  }
+
+  private currentOAuthTokens(): OAuthTokens | null {
+    if (
+      !this.credentials?.accessToken ||
+      !this.credentials.refreshToken ||
+      !this.credentials.tokenEndpoint ||
+      !this.credentials.clientId
+    ) {
+      return null;
+    }
+    return {
+      accessToken: this.credentials.accessToken,
+      refreshToken: this.credentials.refreshToken,
+      expiresAt: this.credentials.expiresAt,
+      tokenEndpoint: this.credentials.tokenEndpoint,
+      clientId: this.credentials.clientId,
+    };
+  }
+
+  // Proactive refresh: when the access token is about to expire, swap it for
+  // a fresh one. Quiet no-op for password credentials.
+  private async ensureFreshToken(): Promise<void> {
+    const tokens = this.currentOAuthTokens();
+    if (!tokens) return;
+    if (tokens.expiresAt == null) return;
+    if (tokens.expiresAt - Date.now() > TOKEN_REFRESH_LEEWAY_MS) return;
+    try {
+      const next = await refreshOAuthAccessToken(tokens);
+      await this.persistRefreshedTokens(next);
+    } catch {
+      // Surface as AuthenticationError on the next 401; refresh may be
+      // temporarily failing (network) and the reactive retry path catches it.
+    }
+  }
+
+  // Reactive refresh after a 401. Returns true if a fresh token was obtained
+  // so the caller can retry the original request.
+  private async forceRefreshToken(): Promise<boolean> {
+    const tokens = this.currentOAuthTokens();
+    if (!tokens) return false;
+    try {
+      const next = await refreshOAuthAccessToken(tokens);
+      await this.persistRefreshedTokens(next);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   // Legacy single-slot restore - kept for backward-compat tests. New code
   // should use loadAccount(accountId) driven by the account registry.
   async restoreSession(): Promise<boolean> {
@@ -235,12 +354,18 @@ export class JMAPClient {
 
   private async fetchSession(baseUrl: string): Promise<JMAPSession> {
     const url = `${baseUrl}/.well-known/jmap`;
-    const response = await secureFetch(url, {
-      headers: {
-        Authorization: this.authHeader,
-        Accept: 'application/json',
-      },
-    });
+    await this.ensureFreshToken();
+    const doFetch = () =>
+      secureFetch(url, {
+        headers: {
+          Authorization: this.authHeader,
+          Accept: 'application/json',
+        },
+      });
+    let response = await doFetch();
+    if (response.status === 401 && (await this.forceRefreshToken())) {
+      response = await doFetch();
+    }
 
     if (response.status === 401) {
       throw new AuthenticationError('Invalid credentials');
@@ -280,14 +405,21 @@ export class JMAPClient {
       methodCalls,
     };
 
-    const response = await secureFetch(this.session.apiUrl, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: this.authHeader,
-      },
-      body: JSON.stringify(body),
-    });
+    await this.ensureFreshToken();
+    const doFetch = () =>
+      secureFetch(this.session!.apiUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: this.authHeader,
+        },
+        body: JSON.stringify(body),
+      });
+
+    let response = await doFetch();
+    if (response.status === 401 && (await this.forceRefreshToken())) {
+      response = await doFetch();
+    }
 
     if (response.status === 401) {
       throw new AuthenticationError('Session expired');
@@ -335,9 +467,12 @@ export class JMAPClient {
 
   async fetchBlobArrayBuffer(blobId: string, name?: string, type?: string): Promise<ArrayBuffer> {
     const url = this.getBlobDownloadUrl(blobId, name, type);
-    const response = await secureFetch(url, {
-      headers: { Authorization: this.authHeader },
-    });
+    await this.ensureFreshToken();
+    const doFetch = () => secureFetch(url, { headers: { Authorization: this.authHeader } });
+    let response = await doFetch();
+    if (response.status === 401 && (await this.forceRefreshToken())) {
+      response = await doFetch();
+    }
     if (response.status === 401) throw new AuthenticationError('Session expired');
     if (!response.ok) throw new Error(`Failed to fetch blob: ${response.status}`);
     return response.arrayBuffer();

src/api/types.ts

@@ -9,6 +9,10 @@ export interface JMAPSession {
   accounts: Record<string, JMAPAccountInfo>;
   capabilities: Record<string, unknown>;
   state: string;
+  // RFC 8620 §2 — authenticated user identifier. Optional because not all
+  // servers populate it; OAuth login uses it as the account label when
+  // there's no password username to fall back on.
+  username?: string;
 }
 
 export interface JMAPAccountInfo {

src/lib/oauth.ts

@@ -0,0 +1,166 @@
+import * as WebBrowser from 'expo-web-browser';
+import { secureFetch } from './client-cert';
+
+// Webmail-mediated login. The app opens the webmail's normal login page with
+// extra `mobile_redirect_uri` and `mobile_state` query params. The webmail
+// uses its existing password and OAuth flows, and once the user is signed
+// in, redirects back to the app's custom scheme with credentials packed into
+// the URL fragment. Fragments aren't sent to the server, so password and
+// token material don't appear in HTTP access logs along the way.
+
+export const HANDOFF_REDIRECT_URI = 'bulwarkmobile://auth/callback';
+
+export interface OAuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number; // epoch ms
+  tokenEndpoint: string;
+  clientId: string;
+}
+
+export type HandoffResult =
+  | {
+      flow: 'password';
+      serverUrl: string;
+      username: string;
+      password: string;
+    }
+  | {
+      flow: 'oauth';
+      serverUrl: string;
+      tokens: OAuthTokens;
+    };
+
+export class HandoffError extends Error {}
+export class HandoffCancelledError extends HandoffError {
+  constructor() {
+    super('Sign-in cancelled');
+  }
+}
+
+function randomState(): string {
+  const bytes = new Uint8Array(16);
+  for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  let s = '';
+  for (const b of bytes) s += b.toString(16).padStart(2, '0');
+  return s;
+}
+
+function buildHandoffUrl(webmailUrl: string, state: string): string {
+  const base = webmailUrl.replace(/\/+$/, '');
+  const params = new URLSearchParams({
+    mobile_redirect_uri: HANDOFF_REDIRECT_URI,
+    mobile_state: state,
+  });
+  return `${base}/login?${params.toString()}`;
+}
+
+function parseFragment(url: string): URLSearchParams {
+  const hashIdx = url.indexOf('#');
+  if (hashIdx === -1) return new URLSearchParams();
+  return new URLSearchParams(url.slice(hashIdx + 1));
+}
+
+export async function runWebmailHandoff(webmailUrl: string): Promise<HandoffResult> {
+  const state = randomState();
+  const handoffUrl = buildHandoffUrl(webmailUrl, state);
+
+  const result = await WebBrowser.openAuthSessionAsync(handoffUrl, HANDOFF_REDIRECT_URI);
+
+  if (result.type === 'cancel' || result.type === 'dismiss') {
+    throw new HandoffCancelledError();
+  }
+  if (result.type !== 'success' || !result.url) {
+    throw new HandoffError(`Sign-in failed: ${result.type}`);
+  }
+
+  const params = parseFragment(result.url);
+  const err = params.get('error');
+  if (err) throw new HandoffError(err);
+
+  // CSRF guard: the state we generated must round-trip through the webmail
+  // unchanged. A mismatch means the redirect didn't come from the flow we
+  // started, and the rest of the fragment shouldn't be trusted.
+  if (params.get('state') !== state) {
+    throw new HandoffError('State mismatch');
+  }
+
+  const flow = params.get('flow');
+  const serverUrl = params.get('server_url');
+  if (!serverUrl) throw new HandoffError('Sign-in response missing server URL');
+
+  if (flow === 'password') {
+    const username = params.get('username');
+    const password = params.get('password');
+    if (!username || !password) {
+      throw new HandoffError('Sign-in response missing credentials');
+    }
+    return { flow: 'password', serverUrl, username, password };
+  }
+
+  if (flow === 'oauth') {
+    const accessToken = params.get('access_token');
+    const tokenEndpoint = params.get('token_endpoint');
+    const clientId = params.get('client_id');
+    if (!accessToken || !tokenEndpoint || !clientId) {
+      throw new HandoffError('Sign-in response missing OAuth tokens');
+    }
+    const refreshToken = params.get('refresh_token') ?? undefined;
+    const expiresIn = params.get('expires_in');
+    return {
+      flow: 'oauth',
+      serverUrl,
+      tokens: {
+        accessToken,
+        refreshToken,
+        expiresAt: expiresIn ? Date.now() + parseInt(expiresIn, 10) * 1000 : undefined,
+        tokenEndpoint,
+        clientId,
+      },
+    };
+  }
+
+  throw new HandoffError(`Unknown sign-in flow: ${flow ?? 'missing'}`);
+}
+
+// OAuth refresh — exchanges the refresh token at the original token endpoint
+// for a new access token. Returns the updated bundle so the caller can
+// persist it.
+export async function refreshOAuthAccessToken(tokens: OAuthTokens): Promise<OAuthTokens> {
+  if (!tokens.refreshToken) {
+    throw new HandoffError('No refresh token available');
+  }
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: tokens.refreshToken,
+    client_id: tokens.clientId,
+  });
+  const response = await secureFetch(tokens.tokenEndpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body: body.toString(),
+  });
+  if (!response.ok) {
+    throw new HandoffError(`Token refresh failed: ${response.status}`);
+  }
+  const data = (await response.json()) as {
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+  };
+  if (!data.access_token) {
+    throw new HandoffError('Token refresh response missing access_token');
+  }
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token ?? tokens.refreshToken,
+    expiresAt: data.expires_in ? Date.now() + data.expires_in * 1000 : undefined,
+    tokenEndpoint: tokens.tokenEndpoint,
+    clientId: tokens.clientId,
+  };
+}
+
+WebBrowser.maybeCompleteAuthSession();

src/screens/LoginScreen.tsx

@@ -20,6 +20,7 @@ export default function LoginScreen({ onLogin, isAddMode, onCancel }: LoginScree
   const c = useColors();
   const styles = React.useMemo(() => makeStyles(c), [c]);
   const login = useAuthStore((state) => state.login);
+  const loginViaWebmail = useAuthStore((state) => state.loginViaWebmail);
   const isLoading = useAuthStore((state) => state.isLoading);
   const error = useAuthStore((state) => state.error);
   const clearError = useAuthStore((state) => state.clearError);
@@ -30,6 +31,7 @@ export default function LoginScreen({ onLogin, isAddMode, onCancel }: LoginScree
   const [showPassword, setShowPassword] = React.useState(false);
 
   const canSubmit = Boolean(serverUrl.trim() && email.trim() && password);
+  const canHandoff = Boolean(serverUrl.trim());
 
   const handleLogin = async () => {
     if (!canSubmit) {
@@ -44,6 +46,25 @@ export default function LoginScreen({ onLogin, isAddMode, onCancel }: LoginScree
     }
   };
 
+  const handleWebmailHandoff = async () => {
+    if (!canHandoff) return;
+    try {
+      const before = useAuthStore.getState().isAuthenticated;
+      await loginViaWebmail(serverUrl.trim(), { addAccount: isAddMode });
+      // loginViaWebmail swallows the "user cancelled the browser" case
+      // silently — only fire the navigation hook when authentication
+      // actually completed.
+      const after = useAuthStore.getState().isAuthenticated;
+      if (after && !before) {
+        onLogin?.();
+      } else if (isAddMode && after) {
+        onLogin?.();
+      }
+    } catch {
+      // Store state already contains the user-facing error.
+    }
+  };
+
   const updateField = React.useCallback(
     (setter: React.Dispatch<React.SetStateAction<string>>) => (value: string) => {
       if (useAuthStore.getState().error) {
@@ -149,10 +170,17 @@ export default function LoginScreen({ onLogin, isAddMode, onCancel }: LoginScree
               <View style={styles.dividerLine} />
             </View>
 
-            {/* OAuth buttons */}
+            {/* Webmail-mediated login */}
             <View style={styles.oauthRow}>
-              <Button variant="outline" size="md" disabled>
-                SSO Provider
+              <Button
+                variant="outline"
+                size="md"
+                onPress={() => {
+                  void handleWebmailHandoff();
+                }}
+                disabled={!canHandoff || isLoading}
+              >
+                Sign in via webmail
               </Button>
             </View>
           </View>

src/stores/auth-store.ts

@@ -6,6 +6,7 @@ import { useEmailStore } from './email-store';
 import { useContactsStore } from './contacts-store';
 import { useCalendarStore } from './calendar-store';
 import { generateAccountId } from '../lib/account-utils';
+import { runWebmailHandoff, HandoffCancelledError } from '../lib/oauth';
 import {
   teardownPushNotifications,
   teardownPushNotificationsForAccount,
@@ -38,6 +39,7 @@ export interface AuthState {
   client: typeof jmapClient | null;
 
   login: (serverUrl: string, username: string, password: string, opts?: { addAccount?: boolean }) => Promise<void>;
+  loginViaWebmail: (webmailUrl: string, opts?: { addAccount?: boolean }) => Promise<void>;
   logout: () => Promise<void>;
   logoutAll: () => Promise<void>;
   switchAccount: (accountId: string) => Promise<void>;
@@ -167,6 +169,71 @@ export const useAuthStore = create<AuthState>((set, get) => ({
     }
   },
 
+  loginViaWebmail: async (webmailUrl, opts) => {
+    set({ isLoading: true, error: null });
+    let result;
+    try {
+      result = await runWebmailHandoff(webmailUrl);
+    } catch (err) {
+      if (err instanceof HandoffCancelledError) {
+        // User closed the browser tab — quiet exit, no error banner.
+        set({ isLoading: false, error: null });
+        return;
+      }
+      const message = err instanceof Error ? err.message : 'Sign-in failed';
+      set({ isLoading: false, error: message });
+      throw err;
+    }
+
+    if (result.flow === 'password') {
+      // Hand the credentials to the existing password login path so account
+      // registration + feature-store wiring all behave identically to a
+      // manual sign-in.
+      await get().login(result.serverUrl, result.username, result.password, opts);
+      return;
+    }
+
+    // OAuth — the webmail did the dance against Stalwart and handed us a
+    // token bundle. Bootstrap the JMAP session with Bearer auth and let
+    // ensure/forceRefreshToken keep it alive going forward.
+    try {
+      if (opts?.addAccount && get().isAuthenticated) {
+        jmapClient.reset();
+        useContactsStore.getState().reset();
+        useCalendarStore.getState().reset();
+      }
+
+      const { session, username, accountId } = await jmapClient.connectWithOAuth(
+        result.serverUrl,
+        result.tokens,
+      );
+
+      const accountStore = useAccountStore.getState();
+      accountStore.addAccount({
+        serverUrl: result.serverUrl.replace(/\/+$/, ''),
+        username,
+        displayName: username,
+        email: username,
+        lastLoginAt: Date.now(),
+        isConnected: true,
+        hasError: false,
+      });
+      accountStore.setActiveAccount(accountId);
+      useEmailStore.getState().setActiveAccount(accountId);
+
+      applyConnectedState(set, session, result.serverUrl.replace(/\/+$/, ''), username, accountId);
+    } catch (err) {
+      const message =
+        err instanceof AuthenticationError
+          ? 'Authentication rejected by server'
+          : err instanceof Error
+            ? err.message
+            : 'OAuth sign-in failed';
+      set({ isLoading: false, error: message });
+      throw err;
+    }
+  },
+
   logout: async () => {
     const accountStore = useAccountStore.getState();
     const currentId = get().activeAccountId;

src/test-setup.ts

@@ -64,3 +64,11 @@ vi.mock('expo-secure-store', () => ({
   getItemAsync: vi.fn(async () => null),
   deleteItemAsync: vi.fn(async () => undefined),
 }));
+
+// expo-web-browser transitively pulls in expo-modules-core, which evaluates
+// RN-only globals at module load. The unit tests don't exercise the real
+// browser handoff flow, so stubbing the surface is enough.
+vi.mock('expo-web-browser', () => ({
+  openAuthSessionAsync: vi.fn(async () => ({ type: 'cancel' as const })),
+  maybeCompleteAuthSession: vi.fn(),
+}));