Authentication on Device

A server keeps its secrets in an environment you control: a machine in a data centre, behind a network you configured, with access you granted. A mobile app keeps its secrets on a device that travels in a coat pocket, gets left on a van seat, and is occasionally handed to a colleague to show them something.

That changes what you store and how. The field app needs to stay signed in — asking an engineer to type a password at every site would get the app abandoned by Wednesday — so something that grants access to the employees API lives on that device for weeks. Where it lives is the subject of this lesson.

The framing throughout is defensive: how to build so that a lost device is a contained problem rather than an open door. Two facts shape every decision. Anything shipped inside your app is shipped to everybody who installs it, so the app cannot hold a secret of its own. And the platform provides storage specifically designed to protect credentials, backed on modern devices by dedicated hardware, which ordinary preference stores and plain files are not.

{
  "token_type": "Bearer",
  "access_token": "<short-lived access token>",
  "expires_in": 900,
  "refresh_token": "<refresh token>",
  "scope": "employees.read visits.write"
}

• The field names follow the usual conventions for token endpoints, so a response from your identity provider will look close to this even though the details differ.
• expires_in is a duration in seconds, not an instant. Nine hundred seconds is fifteen minutes. Convert it to an absolute expiry as soon as the response arrives, because by the time you use the token you no longer know when it was issued.
• Refresh a little before expiry rather than at it. A minute of headroom absorbs clock differences between the device and the server, and avoids a race where a request leaves with a token that expires in transit.
• A device clock can be wrong, sometimes by hours, and users do change it. So treat your own expiry calculation as an optimisation, not a guarantee, and always handle a 401 from the API by refreshing once and retrying — that is the check that actually holds.
• The scope names what the app may do. Requesting only what the app needs limits the damage if a token escapes, and it is one of the few security improvements that costs nothing to implement.
• This whole response is sensitive. It does not belong in a log line, a crash report, an analytics event, or a debugging screenshot. Redaction has to happen before the value reaches any of those, not afterwards.

interface SecureStore {
  get(key: string): Promise<string | null>;
  set(key: string, value: string): Promise<void>;
  remove(key: string): Promise<void>;
}

interface Tokens {
  accessToken: string;
  refreshToken: string;
  expiresAt: number;
}

export class SignedOutError extends Error {}

const TOKEN_KEY = "auth.tokens";
const EARLY_REFRESH_MS = 60000;

let inFlight: Promise<Tokens> | null = null;

export async function accessToken(
  store: SecureStore,
  now: number,
): Promise<string> {
  const stored = await store.get(TOKEN_KEY);
  if (stored === null) throw new SignedOutError();

  const tokens = JSON.parse(stored) as Tokens;
  if (now < tokens.expiresAt - EARLY_REFRESH_MS) {
    return tokens.accessToken;
  }

  // One refresh at a time. Four screens waking together must not
  // each spend the refresh token.
  inFlight ??= refreshTokens(store, tokens.refreshToken).finally(() => {
    inFlight = null;
  });

  return (await inFlight).accessToken;
}

• SecureStore is deliberately a three-method interface. Your platform's secure storage API is nothing like this, and that is fine — wrapping it behind a small interface is what lets the rest of your app stay unaware of the difference, and lets tests run without a device.
• Every request goes through this function, which is the point. A token read directly from storage at a call site is a token nobody refreshed, and it will start returning 401s at the least convenient moment.
• The single-flight guard on inFlight matters more than it looks. When the app returns to the foreground, several screens often refresh at once. Without the guard, each fires its own refresh; with rotating refresh tokens, where each use issues a new one and invalidates the old, the concurrent attempts invalidate each other and the user is signed out for no reason. This is a genuinely common production bug and hard to reproduce on a fast connection.
• The finally clause clears inFlight whether the refresh succeeded or failed. Leave a rejected promise in that variable and every later call gets the same old failure forever, which presents as an app that can never sign in again until it is restarted.
• The module-level variable is the simplest thing that works here and it assumes one signed-in user per app instance, which is true for the field app. If your app supports switching accounts, the guard needs to be per account, otherwise one user's refresh can be handed to another.