Process Flows

Client sends credentials — the mobile app POSTs { email, password } plus the Castle device fingerprint (x-castle-request-token) to POST /oauth/token on auth.floatme.io. Handler: login.ts.

Pre-login Castle filter — login.ts calls POST /v1/filter on Castle with the device fingerprint and IP. Castle returns a policy.action:

Auth0 password-realm grant — the worker forwards the credentials plus client_id, client_secret, audience, realm, scope, and the client IP via auth0-forwarded-for to POST /oauth/token on Auth0.

MFA branch — if Auth0 returns mfa_required, the error is passed through transparently to the client (403 with an mfa_token). The client must then call either MFA Enrollment (first-time) or the OOB challenge sub-flow (returning user).

Successful login — on a successful Auth0 response the worker calls POST /v1/risk on Castle (authenticated risk scoring including the user ID). The full token set (access_token, refresh_token, id_token) is returned to the client with 200 OK.

Acquire an MFA token — the client calls POST /mfa/token with the user’s email and password. Handler: get-mfa-token.ts. The worker performs a password-realm grant against Auth0 using the MFA audience (AUTH0_MFA_AUDIENCE). Auth0 returns a short-lived mfa_token scoped to enroll read:authenticators only.

First enrollment — the client calls POST /mfa/first-enroll (or the alias POST /mfa/associate) with { email, oob_channel, mfa_token }. Handler: enroll-first-mfa-authenticator.ts. +

List authenticators (optional) — the client may call GET /mfa/authenticators with the MFA token in the Authorization header. Handler: get-mfa-authenticators.ts. The worker proxies to GET /mfa/authenticators on Auth0, then filters the response to OOB authenticators only and returns a normalized array of { id, name, active, oob_channel }.

Challenge — the client calls POST /mfa/challenge with { authenticator_id, mfa_token }. Handler: challenge-mfa-oob-authenticator.ts. The worker forwards to POST /mfa/challenge on Auth0 with challenge_type=oob, injecting client_id and client_secret. Auth0 delivers a new OOB code to the registered channel. Response: { oob_code }. + NOTE: Auth0 rate-limits OOB delivery. The error Too many SMS sent by the user is normalized to { error: "too_many_sms" }.

Submit challenge — the client calls POST /mfa/confirm with { oob_code, binding_code, mfa_token }. Handler: submit-mfa-oob-challenge.ts. The worker forwards to POST /oauth/token with grant_type=http://auth0.com/oauth/grant-type/mfa-oob. On success, a post-challenge Castle risk call (POST /v1/risk) is made with the authenticated user context. If Castle blocks the request, 401 { error: "unauthorized" } is returned. Otherwise the full token set (access_token, refresh_token, id_token) is returned to the client. + NOTE: If Auth0 omits refresh_token in the response (edge case), the worker substitutes a placeholder value to prevent null-reference errors in downstream clients. This is a known bug — the handler should surface a hard failure rather than returning an invalid token.

Client sends signup data — the mobile app POSTs { email, password, username, given_name, family_name } plus the Castle device fingerprint to POST /signup. Handler: signup.ts.

Pre-signup Castle filter — the worker calls POST /v1/filter on Castle with the email, username, phone (in E.164 format), and device fingerprint. If Castle returns deny and ENABLE_CASTLE_BLOCKING=true, the handler returns 401 { error: "unauthorized", message: "blocked by security policy" } immediately.

Auth0 user creation — the worker calls POST /dbconnections/signup on Auth0 with the user data. verify_email is always set to false; Auth0 will not send a verification email automatically. Verification email delivery is triggered separately by the client via POST /email/verify. + On success, Auth0 returns { _id, email }. + On failure, the error is normalized: user_exists becomes { error: "invalid_signup" } (400); other coded errors pass through with their original status.

Post-signup Castle risk — after successful Auth0 user creation the worker calls POST /v1/risk on Castle, now including the Auth0-assigned user ID and the full address fields from the signup request. If Castle blocks post-signup (and blocking is enabled), 401 { error: "unauthorized", message: "blocked by security policy" } is returned even though the Auth0 record was already created. + WARNING: This leaves an orphaned Auth0 user record. There is currently no automatic cleanup for these orphaned records. A user hitting this path will encounter a "user already exists" error on retry. Resolution requires manual Auth0 user deletion or support intervention. This is a known gap; a recommended fix is to move the Castle check before Auth0 user creation, or add a compensating delete on Castle block.

Response to client — on success, 200 { id, email } is returned. The mobile app then drives email verification (POST /email/verify) and user-service account provisioning as subsequent steps in the onboarding funnel.

Initiate social signin — the mobile app calls GET /social/signin. Handler: social-signin.ts. The worker builds an Auth0 /authorize URL with connection=google-oauth2, full scope (openid email profile offline_access), the configured audience, and a redirect_uri pointing back to /social/complete on the same worker domain (prod or test). The response is a 302 redirect to that Auth0 URL; the mobile browser or in-app browser follows it.

Google authentication — Auth0 redirects the browser to Google’s OAuth2 consent screen. The user authenticates with their Google account. Google returns an authorization code to Auth0’s callback, and Auth0 then redirects to the worker’s /social/complete endpoint with a code query parameter.

Callback token exchange — Auth0 redirects to GET /social/complete?code=…​. Handler: social-callback.ts. The worker extracts the code from the query string and calls POST /oauth/token on Auth0 with grant_type=authorization_code, injecting client_id, client_secret, and the same redirect_uri. Auth0 returns { access_token, refresh_token, id_token }.

ID token validation — the worker validates the id_token against Auth0’s JWKs (via services/auth0/token-validator.ts). If validation fails, the handler returns 401 Unauthorized. The email claim is extracted from the validated token.

User existence check — using the extracted email, the worker calls POST /users-by-email on the user-service (IAM-signed). A 404 response means the FloatMe account does not yet exist; the worker sets signup=true in the redirect parameters. A 200 response means the account exists; signup=false.

Deeplink redirect — the worker issues a 302 redirect to floatme://links.floatme.io/social?access_token=…​&refresh_token=…​&id_token=…​&signup=true|false. The mobile OS intercepts this custom-scheme URL and opens the FloatMe app, which consumes the tokens and (if signup=true) continues through account setup. + WARNING: Passing tokens as URL query parameters is a known security risk — tokens can appear in URL logs, browser history, and referrer headers. The recommended migration is to Authorization Code + PKCE, where the app exchanges a short-lived code for tokens via a secure backend endpoint rather than receiving them directly in the URL.

Domain verification (one-time) — when the FloatMe app is installed (or periodically refreshed), iOS downloads /.well-known/apple-app-site-association and Android downloads /.well-known/assetlinks.json from links.floatme.io. Handler: index.ts → wellknown.ts. The worker serves the correct static payload for the environment (WORKER_ENV=prod or test). + The AASA declares applinks for path patterns /link/* and /login/\*, plus webcredentials for AutoFill. The assetlinks.json declares delegate_permission/common.handle_all_urls for the same domain. + Once verified, the OS registers links.floatme.io as a trusted domain for the app.

User taps a deeplink — a user taps a URL of the form https://links.floatme.io/link/... or https://links.floatme.io/login/... (for example, in an email, SMS, or shared referral link).

OS intercepts navigation — because the domain was previously verified, the OS intercepts the tap before making any network request to the worker. If the FloatMe app is installed, the OS opens it directly and passes the full URL. No HTTP request reaches the links worker during normal operation.

App-not-installed fallback — if the app is not installed, the OS allows the browser to navigate to the URL. The links worker returns 200 OK with an empty body for all non-.well-known paths, so the browser renders a blank page. + NOTE: A future improvement noted in the links worker would redirect unarmed deeplinks (app not installed) to the App Store or Play Store.

Social callback deeplink — the social login flow (see Social Login) issues a redirect to floatme://links.floatme.io/social?…​. This uses the floatme:// custom scheme directly, not the https:// Universal Link path. Custom scheme URLs bypass the .well-known mechanism; the OS routes them directly to the registered app handler.