@layers/amba-react-native 4.0.11 → 4.0.14

package/dist/index.cjs

@@ -88,6 +88,8 @@ var AmbaApiError = class extends Error {
 //#region src/http-client.ts
 /** Default amba API endpoint. */
 const DEFAULT_BASE_URL = "https://api.amba.dev";
+/** Server codes for a session token the server no longer accepts. */
+const SESSION_REFUSED_CODES = new Set(["SESSION_REVOKED", "INVALID_SESSION_TOKEN"]);
 var AmbaHttpClient = class {
 	apiKey;
 	baseUrl;
@@ -96,6 +98,7 @@ var AmbaHttpClient = class {
 	identity;
 	fetchImpl;
 	ensureSession;
+	onSessionRefused;
 	constructor(opts) {
 		this.apiKey = opts.apiKey;
 		this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
@@ -103,6 +106,7 @@ var AmbaHttpClient = class {
 		this.sdkVersionHeader = opts.sdkVersionHeader;
 		this.identity = opts.identity;
 		this.ensureSession = opts.ensureSession;
+		this.onSessionRefused = opts.onSessionRefused;
 		this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
 	}
 	/** Build the absolute URL for an API path, optionally with a query string. */
@@ -148,11 +152,13 @@ var AmbaHttpClient = class {
 	async delete(path) {
 		return this.request("DELETE", path);
 	}
-	async request(method, path, body, query, sessionToken) {
+	async request(method, path, body, query, sessionToken, resent = false) {
 		if (this.ensureSession && !sessionToken && !this.identity.getSessionToken()) await this.ensureSession(path);
 		const url = this.url(path, query);
 		const headers = this.buildHeaders();
 		if (sessionToken) headers.Authorization = `Bearer ${sessionToken}`;
+		const storedToken = sessionToken ? null : this.identity.getSessionToken();
+		const storedUserId = storedToken ? this.identity.getAppUserId() : null;
 		const init = {
 			method,
 			headers,
@@ -164,7 +170,20 @@ var AmbaHttpClient = class {
 		} catch (err) {
 			throw new AmbaApiError("NETWORK_ERROR", `Network error: ${err instanceof Error ? err.message : typeof err === "string" ? err : "fetch failed"}`, err);
 		}
-		return parseResponse(response);
+		try {
+			return await parseResponse(response);
+		} catch (err) {
+			if (!resent && storedToken && this.onSessionRefused && !path.startsWith("/v1/client/auth/") && err instanceof AmbaApiError && SESSION_REFUSED_CODES.has(err.code) && await this.recoverSession(storedToken, storedUserId)) return this.request(method, path, body, query, void 0, true);
+			throw err;
+		}
+	}
+	/** Run the `onSessionRefused` hook; a hook that throws counts as false. */
+	async recoverSession(usedToken, usedUserId) {
+		try {
+			return await this.onSessionRefused?.(usedToken, usedUserId) === true;
+		} catch {
+			return false;
+		}
 	}
 };
 async function parseResponse(response) {
@@ -221,13 +240,31 @@ function mapHttpError(response, rawBody, isJson) {
 
 //#endregion
 //#region src/uuid.ts
+/** Thrown when the runtime has no `crypto.getRandomValues`. */
+var SecureRandomUnavailableError = class extends Error {
+	code = "SECURE_RANDOM_UNAVAILABLE";
+	constructor() {
+		super("Amba needs crypto.getRandomValues to generate identifiers, and this runtime does not provide it. Install react-native-get-random-values and import it on the first line of your app's entry file, before any Amba import: import 'react-native-get-random-values';");
+		this.name = "SecureRandomUnavailableError";
+	}
+};
+function secureGetRandomValues() {
+	const crypto = globalThis.crypto;
+	const grv = crypto?.getRandomValues;
+	if (!crypto || typeof grv !== "function") throw new SecureRandomUnavailableError();
+	return grv.bind(crypto);
+}
+/**
+* Throws `SecureRandomUnavailableError` when the runtime cannot generate
+* secure identifiers. `IdentityStore.create` calls it so a missing polyfill
+* surfaces at `configure()`, before any identifier is needed.
+*/
+function assertSecureRandomAvailable() {
+	secureGetRandomValues();
+}
 function getRandomBytes(n) {
 	const bytes = new Uint8Array(n);
-	if (typeof globalThis.crypto?.getRandomValues === "function") {
-		globalThis.crypto.getRandomValues(bytes);
-		return bytes;
-	}
-	for (let i = 0; i < n; i++) bytes[i] = Math.floor(Math.random() * 256);
+	secureGetRandomValues()(bytes);
 	return bytes;
 }
 /**
@@ -246,6 +283,30 @@ function uuidv4() {
 //#region src/identity.ts
 /** Storage key under the configured prefix. Bumped when shape changes. */
 const IDENTITY_KEY = "identity_v1";
+/**
+* Whether a vault entry belongs to this install's record. An entry another
+* install wrote (`install_id`) never does. Each flush writes the vault and
+* then the record, both stamped with the flush's sequence number. An entry
+* of this install newer than the record comes from a flush that stopped
+* between the two writes, so it holds the latest session. Otherwise the
+* entry belongs only when the record vouches for it (`vault_seq`), which a
+* sign-in or sign-out that couldn't write the vault withdraws. An entry
+* written before 4.0.14 belongs while a record from then vouches for it and
+* carries the same anonymous id and user.
+*/
+function entryBelongs(entry, anonymousId, appUserId, installId, recordSeq, vaultSeq) {
+	const entrySeq = typeof entry.write_seq === "number" ? entry.write_seq : 0;
+	if (entrySeq === 0 || entry.install_id == null) {
+		const sameUser = entry.app_user_id == null || appUserId === null || entry.app_user_id === appUserId;
+		return vaultSeq === 0 && entry.anonymous_id === anonymousId && sameUser;
+	}
+	if (installId === null || entry.install_id !== installId) return false;
+	if (entrySeq > recordSeq) return true;
+	return entrySeq === vaultSeq;
+}
+function seqOf(value) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
 function isExpired(expiresAt) {
 	if (!expiresAt) return false;
 	const t = Date.parse(expiresAt);
@@ -263,6 +324,7 @@ var IdentityStore = class IdentityStore {
 	sessionToken = null;
 	refreshToken = null;
 	expiresAt = null;
+	anonymousSession = null;
 	/**
 	* Credentials an earlier SDK version left in the AsyncStorage record, with
 	* the user they belong to. They stay on disk until the vault holds the
@@ -275,16 +337,44 @@ var IdentityStore = class IdentityStore {
 	* succeeds, so a session this launch never loaded is not overwritten.
 	*/
 	vaultUnreadable;
-	constructor(persistence, seed, vault, plaintext, vaultUnreadable) {
+	/** Highest flush sequence number seen or used. */
+	seq;
+	/** `write_seq` of the stored record. */
+	recordSeq;
+	/** `vault_seq` of the stored record (see `PersistedIdentity`). */
+	vaultSeq;
+	/**
+	* The session the vouched vault entry holds, by refresh token and user. A
+	* failed or held vault write withdraws the vouch only when the session
+	* changed from it, so a link that only moves the anonymous id keeps it.
+	*/
+	vaultHolds;
+	/** Serializes flushes, so the vault and the record stay in write order. */
+	flushChain = Promise.resolve();
+	/** This install's id (see `PersistedIdentity.install_id`). */
+	installId;
+	/** Whether the stored record carries `installId`. */
+	installIdStored;
+	constructor(persistence, seed, vault, plaintext, vaultUnreadable, seq) {
 		this.persistence = persistence;
 		this.vault = vault;
 		this.plaintext = plaintext;
 		this.vaultUnreadable = vaultUnreadable;
+		this.seq = seq;
+		this.installId = seed.install_id ?? uuidv4();
+		this.installIdStored = seed.install_id !== null;
+		this.recordSeq = seed.write_seq;
+		this.vaultSeq = seed.vault_seq;
+		this.vaultHolds = {
+			refreshToken: seed.refresh_token,
+			appUserId: seed.app_user_id
+		};
 		this.anonymousId = seed.anonymous_id;
 		this.appUserId = seed.app_user_id;
 		this.sessionToken = seed.session_token;
 		this.refreshToken = seed.refresh_token;
 		this.expiresAt = seed.expires_at;
+		this.anonymousSession = seed.anonymous_session;
 	}
 	/**
 	* Build a store, hydrating any prior identity from AsyncStorage and the
@@ -296,8 +386,13 @@ var IdentityStore = class IdentityStore {
 	* AsyncStorage record are used for this launch and moved into the vault;
 	* the AsyncStorage copy is removed once the vault write succeeds. A vault
 	* holding its own credentials wins over them.
+	*
+	* Throws `SecureRandomUnavailableError` when the runtime has no
+	* `crypto.getRandomValues`: every anonymous id the store mints must come
+	* from a secure generator.
 	*/
 	static async create(persistence, vault = null) {
+		assertSecureRandomAvailable();
 		const raw = await persistence.read(IDENTITY_KEY);
 		let recordPresent = false;
 		let seed;
@@ -308,7 +403,11 @@ var IdentityStore = class IdentityStore {
 				app_user_id: parsed.app_user_id ?? null,
 				session_token: parsed.session_token ?? null,
 				refresh_token: parsed.refresh_token ?? null,
-				expires_at: parsed.expires_at ?? null
+				expires_at: parsed.expires_at ?? null,
+				anonymous_session: typeof parsed.anonymous_session === "boolean" ? parsed.anonymous_session : null,
+				write_seq: seqOf(parsed.write_seq) ?? 0,
+				vault_seq: parsed.vault_seq === void 0 ? 0 : seqOf(parsed.vault_seq),
+				install_id: typeof parsed.install_id === "string" ? parsed.install_id : null
 			};
 			recordPresent = typeof parsed.anonymous_id === "string";
 		} catch {
@@ -324,6 +423,7 @@ var IdentityStore = class IdentityStore {
 			}
 		} : null;
 		let vaultReadable = true;
+		let seq = seed.write_seq;
 		if (vault) {
 			let fromVault = null;
 			try {
@@ -331,20 +431,28 @@ var IdentityStore = class IdentityStore {
 			} catch {
 				vaultReadable = false;
 			}
-			const belongs = fromVault !== null && recordPresent && fromVault.anonymous_id === seed.anonymous_id;
+			if (fromVault) seq = Math.max(seq, seqOf(fromVault.write_seq) ?? 0);
+			const belongs = fromVault !== null && recordPresent && entryBelongs(fromVault, seed.anonymous_id, seed.app_user_id, seed.install_id, seed.write_seq, seed.vault_seq);
 			if (fromVault && belongs) {
 				seed.session_token = fromVault.session_token;
 				seed.refresh_token = fromVault.refresh_token;
 				seed.expires_at = fromVault.expires_at;
 				if (fromVault.app_user_id != null) seed.app_user_id = fromVault.app_user_id;
+			} else if (fromVault) {
+				seed.write_seq = Math.max(seed.write_seq, seqOf(fromVault.write_seq) ?? 0);
+				seed.vault_seq = null;
 			}
 		}
-		if (vaultReadable && seed.session_token === null && seed.refresh_token === null) seed.app_user_id = null;
+		if (vaultReadable && seed.session_token === null && seed.refresh_token === null) {
+			if (seed.app_user_id !== null && seed.anonymous_session === false) seed.anonymous_id = uuidv4();
+			seed.app_user_id = null;
+			seed.anonymous_session = null;
+		}
 		if (isExpired(seed.expires_at)) {
 			seed.session_token = null;
 			seed.expires_at = null;
 		}
-		const store = new IdentityStore(persistence, seed, vault, plaintext, !vaultReadable);
+		const store = new IdentityStore(persistence, seed, vault, plaintext, !vaultReadable, seq);
 		await store.flush({ hydrating: true });
 		return store;
 	}
@@ -354,7 +462,43 @@ var IdentityStore = class IdentityStore {
 			appUserId: this.appUserId,
 			sessionToken: this.sessionToken,
 			refreshToken: this.refreshToken,
-			expiresAt: this.expiresAt
+			expiresAt: this.expiresAt,
+			anonymousSession: this.anonymousSession
+		};
+	}
+	/**
+	* Whether the vault still can't be read. When the launch read failed, the
+	* vault is read again first, and a session it holds for this install is
+	* loaded (same rule as `create`). While it can't be read, the stored
+	* session is unknown: callers must not replace it with a new user.
+	*/
+	async vaultStillUnreadable() {
+		if (!this.vault || !this.vaultUnreadable) return false;
+		let stored;
+		try {
+			stored = await this.vault.read();
+		} catch {
+			return true;
+		}
+		this.vaultUnreadable = false;
+		this.noteStoredSeq(stored);
+		if (this.sessionToken === null && this.refreshToken === null) this.adoptStored(stored);
+		return false;
+	}
+	/** Keep the next sequence number above an entry read from the vault. */
+	noteStoredSeq(stored) {
+		if (stored) this.seq = Math.max(this.seq, seqOf(stored.write_seq) ?? 0);
+	}
+	/** Load a stored vault session that belongs to this install. */
+	adoptStored(stored) {
+		if (!stored || stored.session_token === null && stored.refresh_token === null || !entryBelongs(stored, this.anonymousId, this.appUserId, this.installIdStored ? this.installId : null, this.recordSeq, this.vaultSeq)) return;
+		this.sessionToken = isExpired(stored.expires_at) ? null : stored.session_token;
+		this.refreshToken = stored.refresh_token;
+		this.expiresAt = isExpired(stored.expires_at) ? null : stored.expires_at;
+		if (stored.app_user_id != null) this.appUserId = stored.app_user_id;
+		this.vaultHolds = {
+			refreshToken: this.refreshToken,
+			appUserId: this.appUserId
 		};
 	}
 	getAnonymousId() {
@@ -372,19 +516,53 @@ var IdentityStore = class IdentityStore {
 	isAuthenticated() {
 		return this.sessionToken !== null;
 	}
+	/**
+	* Store a session. `anonymous` records whether it is a purely anonymous
+	* one (true only for `/v1/client/auth/anonymous`); omit it to keep the
+	* current value (a token refresh of the same session).
+	*/
 	async setSession(args) {
 		this.appUserId = args.appUserId;
 		this.sessionToken = args.sessionToken;
 		this.refreshToken = args.refreshToken;
 		this.expiresAt = args.expiresAt;
+		if (args.anonymous !== void 0) this.anonymousSession = args.anonymous;
+		await this.flush();
+	}
+	/** The current session gained an identity (a link). */
+	async markIdentified() {
+		if (this.anonymousSession === false) return;
+		this.anonymousSession = false;
+		await this.flush();
+	}
+	/**
+	* Adopt the anonymous id the server holds for this install's user: the id
+	* an anonymous sign-in answered with, or the fresh id a link gave the user.
+	*/
+	async setAnonymousId(anonymousId) {
+		if (anonymousId === this.anonymousId) return;
+		this.anonymousId = anonymousId;
 		await this.flush();
 	}
-	async clearSession(rotateAnonymousId) {
+	/**
+	* End the session. The anonymous id is rotated when `rotateAnonymousId`
+	* is set, and whenever the session being ended was not purely anonymous:
+	* that id then identifies an account with a real sign-in, and the next
+	* person on the device must start fresh. A session of unknown kind (stored
+	* by an SDK before 4.0.14) counts as identified, unless
+	* `keepIdWhenKindUnknown` is set (the server decides on the next
+	* anonymous sign-in).
+	*/
+	async clearSession(rotateAnonymousId, opts = {}) {
+		const hadSession = this.sessionToken !== null || this.refreshToken !== null;
+		const identified = this.anonymousSession === false || this.anonymousSession === null && !opts.keepIdWhenKindUnknown;
+		const nextAnonymousId = rotateAnonymousId || hadSession && identified ? uuidv4() : this.anonymousId;
 		this.appUserId = null;
 		this.sessionToken = null;
 		this.refreshToken = null;
 		this.expiresAt = null;
-		if (rotateAnonymousId) this.anonymousId = uuidv4();
+		this.anonymousSession = null;
+		this.anonymousId = nextAnonymousId;
 		await this.flush({ signingOut: true });
 	}
 	/**
@@ -394,55 +572,107 @@ var IdentityStore = class IdentityStore {
 	* from `clearSession`: when the vault can't be emptied, the install moves
 	* to a new anonymous id so the entry left behind no longer belongs to it.
 	*/
-	async flush(opts) {
+	flush(opts) {
+		const run = this.flushChain.then(() => this.flushNow(opts));
+		this.flushChain = run.catch(() => void 0);
+		return run;
+	}
+	async flushNow(opts) {
 		if (!this.vault) {
+			const seq$1 = ++this.seq;
+			const recordSeq$1 = opts?.hydrating ? this.recordSeq : seq$1;
 			const payload = {
 				anonymous_id: this.anonymousId,
 				app_user_id: this.appUserId,
 				session_token: this.sessionToken,
 				refresh_token: this.refreshToken,
-				expires_at: this.expiresAt
+				expires_at: this.expiresAt,
+				anonymous_session: this.anonymousSession,
+				write_seq: recordSeq$1,
+				vault_seq: null,
+				install_id: this.installId
 			};
 			await this.persistence.write(IDENTITY_KEY, JSON.stringify(payload));
+			this.recordSeq = recordSeq$1;
+			this.installIdStored = true;
 			return;
 		}
-		let saved = false;
 		if (this.vaultUnreadable) try {
 			const stored = await this.vault.read();
 			this.vaultUnreadable = false;
-			if (opts?.hydrating && stored && (stored.session_token !== null || stored.refresh_token !== null) && stored.anonymous_id === this.anonymousId) {
-				this.sessionToken = isExpired(stored.expires_at) ? null : stored.session_token;
-				this.refreshToken = stored.refresh_token;
-				this.expiresAt = isExpired(stored.expires_at) ? null : stored.expires_at;
-				if (stored.app_user_id != null) this.appUserId = stored.app_user_id;
-			}
+			this.noteStoredSeq(stored);
+			if (opts?.hydrating) this.adoptStored(stored);
 		} catch {}
-		if (!this.vaultUnreadable) try {
-			await this.vault.write({
-				session_token: this.sessionToken,
-				refresh_token: this.refreshToken,
-				expires_at: this.expiresAt,
-				anonymous_id: this.anonymousId,
-				app_user_id: this.appUserId
-			});
+		const seq = ++this.seq;
+		if (opts?.signingOut) {
+			this.vaultSeq = null;
+			try {
+				await this.persistence.write(IDENTITY_KEY, JSON.stringify(this.recordFor(seq, false)));
+				this.recordSeq = seq;
+				this.installIdStored = true;
+			} catch {}
+		}
+		let holdVaultWrite = false;
+		if (!this.installIdStored && opts?.hydrating && !this.vaultUnreadable) try {
+			await this.persistence.write(IDENTITY_KEY, JSON.stringify(this.recordFor(this.recordSeq, false)));
+			this.installIdStored = true;
+		} catch {
+			holdVaultWrite = true;
+		}
+		const slice = {
+			session_token: this.sessionToken,
+			refresh_token: this.refreshToken,
+			expires_at: this.expiresAt,
+			anonymous_id: this.anonymousId,
+			app_user_id: this.appUserId,
+			write_seq: seq,
+			install_id: this.installId
+		};
+		let saved = false;
+		if (!this.vaultUnreadable && !holdVaultWrite) try {
+			await this.vault.write(slice);
 			saved = true;
+			this.vaultSeq = seq;
+			this.vaultHolds = {
+				refreshToken: slice.refresh_token,
+				appUserId: slice.app_user_id ?? null
+			};
 		} catch (err) {
 			if (typeof console !== "undefined") console.warn("[amba] could not save the session to the secure store", err);
 		}
+		const vaultHasLive = this.vaultHolds.refreshToken === this.refreshToken && this.vaultHolds.appUserId === this.appUserId;
+		if (opts?.signingOut && !saved || !vaultHasLive) this.vaultSeq = null;
 		if (opts?.signingOut && !saved) {
 			this.anonymousId = uuidv4();
 			if (typeof console !== "undefined") console.warn("[amba] could not clear the secure store at sign-out; starting a new anonymous id so the stored session can't be restored");
 		}
+		const recordSeq = opts?.hydrating && !saved ? this.recordSeq : seq;
+		const record = this.recordFor(recordSeq, saved && vaultHasLive);
+		await this.persistence.write(IDENTITY_KEY, JSON.stringify(record));
+		this.recordSeq = recordSeq;
+		this.installIdStored = true;
+		if (record.refresh_token === null) this.plaintext = null;
+	}
+	/**
+	* The AsyncStorage record for a vault in use. It keeps the earlier
+	* version's plaintext copy only while that copy is still the live session
+	* (same user, same refresh token) and the vault doesn't hold it yet
+	* (`saved`). Sign-out, another user or a refresh (which retires the old
+	* refresh token) drops it.
+	*/
+	recordFor(recordSeq, saved) {
 		const keep = !saved && this.plaintext !== null && this.refreshToken !== null && this.plaintext.appUserId === this.appUserId && this.plaintext.slice.refresh_token === this.refreshToken ? this.plaintext.slice : null;
-		const record = {
+		return {
 			anonymous_id: this.anonymousId,
 			app_user_id: this.appUserId,
 			session_token: keep?.session_token ?? null,
 			refresh_token: keep?.refresh_token ?? null,
-			expires_at: keep?.expires_at ?? null
+			expires_at: keep?.expires_at ?? null,
+			anonymous_session: this.anonymousSession,
+			write_seq: recordSeq,
+			vault_seq: this.vaultSeq,
+			install_id: this.installId
 		};
-		await this.persistence.write(IDENTITY_KEY, JSON.stringify(record));
-		if (!keep) this.plaintext = null;
 	}
 };
 function freshSeed() {
@@ -451,7 +681,11 @@ function freshSeed() {
 		app_user_id: null,
 		session_token: null,
 		refresh_token: null,
-		expires_at: null
+		expires_at: null,
+		anonymous_session: null,
+		write_seq: 0,
+		vault_seq: null,
+		install_id: null
 	};
 }
 
@@ -510,7 +744,9 @@ var SecureTokenVault = class {
 				refresh_token: parsed.refresh_token ?? null,
 				expires_at: parsed.expires_at ?? null,
 				anonymous_id: parsed.anonymous_id ?? null,
-				app_user_id: parsed.app_user_id ?? null
+				app_user_id: parsed.app_user_id ?? null,
+				write_seq: parsed.write_seq ?? null,
+				install_id: parsed.install_id ?? null
 			};
 		} catch {
 			return null;
@@ -518,7 +754,15 @@ var SecureTokenVault = class {
 	}
 	async write(slice) {
 		if (isEmpty(slice)) {
-			await this.storage.removeItem(this.key);
+			try {
+				await this.storage.removeItem(this.key);
+			} catch (err) {
+				try {
+					await this.storage.setItem(this.key, JSON.stringify(slice));
+				} catch {
+					throw err;
+				}
+			}
 			return;
 		}
 		await this.storage.setItem(this.key, JSON.stringify(slice));
@@ -864,6 +1108,25 @@ var OfflineQueue = class {
 		await this.clear();
 	}
 	/**
+	* Give the ops queued before any session under `anonymousId` to the
+	* signed-in `appUserId`. Those ops replay under the session that holds
+	* their anonymous id; the SDK calls this before that session's anonymous
+	* id changes (a link, or adopting the account's id), so they keep an owner
+	* that matches.
+	*/
+	async claimAnonymousOps(anonymousId, appUserId) {
+		await this.mutate((ops) => ({
+			next: ops.map((op) => op.owner && op.owner.appUserId === null && op.owner.anonymousId === anonymousId ? {
+				...op,
+				owner: {
+					appUserId,
+					anonymousId
+				}
+			} : op),
+			result: void 0
+		}));
+	}
+	/**
 	* Replay the current owner's ops in FIFO order. Each op is removed only
 	* after it succeeds; the first failure stops the flush and retains the
 	* remainder (so order is preserved and nothing is dropped mid-batch). Ops
@@ -1817,7 +2080,7 @@ function delay(ms) {
 //#endregion
 //#region src/index.ts
 /** SDK semver — burned in at build time. Bump alongside package.json. */
-const SDK_VERSION = "4.0.11";
+const SDK_VERSION = "4.0.14";
 /**
 * Default host that serves deployed functions. `Amba.functions.invoke(name)`
 * targets `https://<projectId>.<DEFAULT_FUNCTIONS_HOST>/<name>` unless a
@@ -1929,21 +2192,52 @@ function expiresAtFromResult(result) {
 	if (result.expires_at && typeof result.expires_at === "string") return result.expires_at;
 	return new Date(Date.now() + 3600 * 1e3).toISOString();
 }
-async function persistAuthResult(state_, result) {
+async function persistAuthResult(state_, result, anonymous) {
 	await state_.identity.setSession({
 		appUserId: result.user.id,
 		sessionToken: result.session_token,
 		refreshToken: result.refresh_token,
-		expiresAt: expiresAtFromResult(result)
+		expiresAt: expiresAtFromResult(result),
+		anonymous
 	});
 }
+function nonEmptyString(value) {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+* POST to an endpoint that answers with a session pair, and store it.
+* An anonymous sign-in records a purely anonymous session and adopts the
+* anonymous id the server answered with (the server mints one when the
+* request carried none). A link adopts the account's rotated anonymous id.
+* A refresh keeps the session's kind; every other sign-in records an
+* identified session.
+*/
 async function postAuth(state_, path, body) {
 	const result = normalizeAuthResult((await state_.http.post(path, body)).data);
-	await persistAuthResult(state_, result);
+	await persistAuthResult(state_, result, path === P.authAnonymous ? true : path === P.authRefresh ? void 0 : false);
+	const adoptedAnonymousId = path === P.authAnonymous ? nonEmptyString(result.anonymous_id) ?? nonEmptyString(result.user?.anonymous_id) : path === P.authLink ? nonEmptyString(result.user?.anonymous_id) : null;
+	if (adoptedAnonymousId) await adoptAnonymousId(state_, adoptedAnonymousId);
 	state_.eventQueue?.flush();
 	await notifyFromAuthResult(result);
 	return result;
 }
+/**
+* Adopt the anonymous id the server holds for the signed-in user. Offline
+* writes queued before any session under the old id would replay under this
+* session; they are handed to the signed-in user first, so the id change
+* leaves them replayable.
+*/
+async function adoptAnonymousId(state_, anonymousId) {
+	const previous = state_.identity.getAnonymousId();
+	if (anonymousId === previous) return;
+	const appUserId = state_.identity.getAppUserId();
+	if (appUserId && state_.offlineEnabled) try {
+		await getOfflineQueue(state_).claimAnonymousOps(previous, appUserId);
+	} catch (err) {
+		if (typeof console !== "undefined") console.warn("[amba] could not reassign queued offline writes", err);
+	}
+	await state_.identity.setAnonymousId(anonymousId);
+}
 /** Paths that must NOT trigger lazy anonymous sign-in. */
 function pathSkipsLazySession(path) {
 	if (path.startsWith("/v1/client/auth/")) return true;
@@ -1955,9 +2249,14 @@ function pathSkipsLazySession(path) {
 }
 async function ensureAnonymousSession(state_) {
 	if (state_.identity.getSessionToken()) return;
+	if (state_.anonSignInInflight) {
+		await state_.anonSignInInflight.catch(() => {});
+		if (state_.identity.getSessionToken()) return;
+	}
 	if (!state_.anonSignInInflight) state_.anonSignInInflight = (async () => {
 		try {
-			await postAuth(state_, P.authAnonymous, { anonymous_id: state_.identity.getAnonymousId() });
+			if (await resumeWithRefreshToken(state_)) return;
+			await signInAnonymouslyFresh(state_);
 		} finally {
 			state_.anonSignInInflight = null;
 		}
@@ -1965,10 +2264,218 @@ async function ensureAnonymousSession(state_) {
 	await state_.anonSignInInflight;
 }
 /**
-* POST helper for endpoints that return `{ data: { user } }` WITHOUT
-* minting new tokens. Used by `linkSmsOtp` / `linkEmailOtp` / `unlink*`
-* — these are "decorate the current user," not "re-authenticate."
-* Existing session tokens stay untouched.
+* Restore a stored session whose session token expired while the app was
+* closed, using its refresh token, so `isAuthenticated` and
+* `onAuthStateChange` show the signed-in user without waiting for an
+* authenticated call. Shares the in-flight slot with the lazy sign-in, so a
+* concurrent authenticated call waits for it. A rejected refresh token ends
+* the session (subscribers hear `null`); this never signs in anonymously.
+*/
+function restoreStoredSession(state_) {
+	if (!state_.anonSignInInflight) state_.anonSignInInflight = (async () => {
+		try {
+			await resumeWithRefreshToken(state_);
+		} finally {
+			state_.anonSignInInflight = null;
+		}
+	})();
+	return state_.anonSignInInflight;
+}
+/**
+* Server answers that mean the refresh token's session is over. A 401
+* without the server's envelope (a proxy, a captive portal) maps to
+* `UNAUTHORIZED` and leaves the session in place.
+*/
+const SESSION_ENDED_CODES = new Set(["INVALID_TOKEN", "SESSION_REVOKED"]);
+function isSessionEnded(err) {
+	return err instanceof AmbaApiError && SESSION_ENDED_CODES.has(err.code);
+}
+/** Record a link in flight until it settles; returns the same promise. */
+function trackLink(state_, link) {
+	const links = state_.linksInflight ??= /* @__PURE__ */ new Set();
+	links.add(link);
+	const settle = () => {
+		links.delete(link);
+	};
+	link.then(settle, settle);
+	return link;
+}
+/**
+* After the server refused the stored session token on an authenticated
+* call (`SESSION_REVOKED`, `INVALID_SESSION_TOKEN`). True when a usable
+* session for the user the call was sent for is stored afterwards, so the
+* call is sent once more as that user:
+*   - a link in flight on this device stores the pair it returns, which is
+*     waited for first;
+*   - a session another flow stored after the call left is used as is;
+*   - otherwise the refresh token continues the session. A rejected refresh
+*     token ends it (subscribers hear `null`) and the call's own error
+*     reaches the app.
+* A session of any other user (a sign-in meanwhile, or the anonymous user
+* a lazy sign-in starts after the session ended) answers false, and the
+* call fails with the server's code. Offline or a server error keeps the
+* session and answers false. The
+* refresh runs in the in-flight slot the launch restore and the lazy
+* sign-in share, so calls refused together end or continue the session
+* once.
+*/
+async function recoverRefusedSession(state_, usedToken, usedUserId) {
+	if (usedUserId === null) return false;
+	const usableForCaller = (token) => token !== null && token !== usedToken && state_.identity.getAppUserId() === usedUserId;
+	if (state_.linksInflight && state_.linksInflight.size > 0) await Promise.allSettled(state_.linksInflight);
+	const current = state_.identity.getSessionToken();
+	if (current !== usedToken) return usableForCaller(current);
+	if (!state_.anonSignInInflight) state_.anonSignInInflight = (async () => {
+		try {
+			await resumeWithRefreshToken(state_);
+		} catch {} finally {
+			state_.anonSignInInflight = null;
+		}
+	})();
+	await state_.anonSignInInflight.catch(() => {});
+	return usableForCaller(state_.identity.getSessionToken());
+}
+/**
+* Continue the stored session with its refresh token. True when it did.
+* False when there is no refresh token, or the server rejected it: the
+* session is then cleared (the anonymous id rotates unless the session was
+* purely anonymous) and subscribers hear the sign-out. Any other failure
+* (offline, a 5xx) is thrown, so a flaky network never starts a new user.
+*/
+async function resumeWithRefreshToken(state_) {
+	const used = state_.identity.getRefreshToken();
+	if (!used) return false;
+	try {
+		await refreshSession(state_);
+		return true;
+	} catch (err) {
+		if (state_.identity.getRefreshToken() !== used) return state_.identity.getSessionToken() !== null;
+		if (!isSessionEnded(err)) throw err;
+		await state_.identity.clearSession(false, { keepIdWhenKindUnknown: true });
+		notifyAuthSubscribers(null);
+		return false;
+	}
+}
+/**
+* `/v1/client/auth/anonymous` with the device's anonymous id. When the
+* server answers `IDENTITY_SIGN_IN_REQUIRED` (the id belongs to a user who
+* signs in with a linked identity), the device takes a new anonymous id and
+* signs in once more as a new anonymous user.
+*/
+async function signInAnonymouslyFresh(state_) {
+	try {
+		return await postAuth(state_, P.authAnonymous, { anonymous_id: state_.identity.getAnonymousId() });
+	} catch (err) {
+		if (!(err instanceof AmbaApiError) || err.code !== IDENTITY_SIGN_IN_REQUIRED) throw err;
+		return recoverFromHeldAnonymousId(state_);
+	}
+}
+const IDENTITY_SIGN_IN_REQUIRED = "IDENTITY_SIGN_IN_REQUIRED";
+/**
+* After `/anonymous` answered `IDENTITY_SIGN_IN_REQUIRED`: continue the
+* stored session when this device holds its refresh token, and otherwise
+* take a new anonymous id and sign in as a new anonymous user. While the
+* secure store can't be read (an iOS device not yet unlocked since a
+* restart), the stored session is unknown, so the call fails with
+* `SECURE_STORE_UNAVAILABLE` and replaces nothing.
+*/
+async function recoverFromHeldAnonymousId(state_) {
+	if (await state_.identity.vaultStillUnreadable()) throw new AmbaApiError("SECURE_STORE_UNAVAILABLE", "the stored session can't be read yet (the device may be locked); retry once it is unlocked");
+	const used = state_.identity.getRefreshToken();
+	if (used) try {
+		return await refreshSession(state_);
+	} catch (refreshErr) {
+		if (!isSessionEnded(refreshErr)) throw refreshErr;
+		const current = state_.identity.getRefreshToken();
+		if (current !== null && current !== used) throw refreshErr;
+	}
+	await state_.identity.clearSession(true);
+	return postAuth(state_, P.authAnonymous, { anonymous_id: state_.identity.getAnonymousId() });
+}
+/**
+* Rotate the session pair with the stored refresh token. The session keeps
+* its user and its kind (anonymous or identified), and auth-state
+* subscribers hear the refreshed session. The server includes the user; an
+* older server that leaves it out keeps the stored user id, and the result's
+* user then carries only that id.
+*/
+function refreshSession(state_) {
+	if (state_.refreshInflight) return state_.refreshInflight;
+	const inflight = refreshSessionOnce(state_);
+	state_.refreshInflight = inflight;
+	const release = () => {
+		if (state_.refreshInflight === inflight) state_.refreshInflight = null;
+	};
+	inflight.then(release, release);
+	return inflight;
+}
+async function refreshSessionOnce(state_) {
+	const refreshToken = state_.identity.getRefreshToken();
+	if (!refreshToken) throw new AmbaApiError("UNAUTHORIZED", "no refresh token available — call signIn* first");
+	const env = await state_.http.post(P.authRefresh, { refresh_token: refreshToken });
+	if (state_.identity.getRefreshToken() !== refreshToken) throw new AmbaApiError("SESSION_CHANGED", "the session changed while it was being refreshed");
+	const appUserId = env.data.user?.id ?? state_.identity.getAppUserId();
+	if (!appUserId) throw new AmbaApiError("UNAUTHORIZED", "the refreshed session names no user — call signIn* first");
+	const user = env.data.user ? normalizeUserAuthProviders(env.data.user) : {
+		id: appUserId,
+		auth_providers: [],
+		properties: {}
+	};
+	const result = {
+		session_token: env.data.session_token,
+		refresh_token: env.data.refresh_token,
+		user,
+		expires_at: env.data.expires_at ?? null
+	};
+	await persistAuthResult(state_, result, void 0);
+	const anonymousId = nonEmptyString(user.anonymous_id);
+	if (anonymousId && anonymousId !== state_.identity.getAnonymousId() && state_.identity.getRefreshToken() === result.refresh_token) {
+		if (state_.identity.snapshot().anonymousSession === true) await state_.identity.markIdentified();
+		await adoptAnonymousId(state_, anonymousId);
+	}
+	state_.eventQueue?.flush();
+	await notifyFromAuthResult(result);
+	return result;
+}
+/**
+* POST an OTP or email + password link. The request asks the server to
+* rotate the session (`rotate_session: true`): the link revokes every token
+* minted for this user before it, and answers with the pair that replaces
+* them, which is stored here. The user id does not change, so no auth-state
+* change fires. The session counts as identified from now on, and the
+* account's rotated anonymous id is adopted.
+*/
+function postLink(state_, body) {
+	return trackLink(state_, postLinkOnce(state_, body));
+}
+async function postLinkOnce(state_, body) {
+	const env = await state_.http.post(P.authLink, {
+		...body,
+		rotate_session: true
+	});
+	const user = normalizeUserAuthProviders(env.data.user);
+	const sessionToken = nonEmptyString(env.data.session_token);
+	const refreshToken = nonEmptyString(env.data.refresh_token);
+	if (sessionToken && refreshToken) await state_.identity.setSession({
+		appUserId: user.id,
+		sessionToken,
+		refreshToken,
+		expiresAt: expiresAtFromResult({
+			session_token: sessionToken,
+			refresh_token: refreshToken,
+			user,
+			expires_at: env.data.expires_at ?? null
+		}),
+		anonymous: false
+	});
+	else await state_.identity.markIdentified();
+	const anonymousId = nonEmptyString(user.anonymous_id);
+	if (anonymousId) await adoptAnonymousId(state_, anonymousId);
+	return user;
+}
+/**
+* POST helper for endpoints that return `{ data: { user } }` and mint no
+* tokens. Used by `unlink*`: existing session tokens stay untouched.
 */
 async function postUserNoRotate(state_, path, body) {
 	return normalizeUserAuthProviders((await state_.http.post(path, body)).data.user);
@@ -2214,7 +2721,8 @@ const Amba = {
 			ensureSession: config.autoAnonymousSession === false ? void 0 : async (path) => {
 				if (pathSkipsLazySession(path)) return;
 				await ensureAnonymousSession(getState());
-			}
+			},
+			onSessionRefused: (usedToken, usedUserId) => recoverRefusedSession(getState(), usedToken, usedUserId)
 		});
 		const prior = state;
 		_offlineEnableToken += 1;
@@ -2259,6 +2767,7 @@ const Amba = {
 			} catch {}
 		}
 		if (!nextState.functionsBaseUrl && !PROJECT_ID_PATTERN.test(nextState.projectId)) resolveFunctionsProjectId(nextState).catch(() => {});
+		if (config.autoAnonymousSession !== false && !identity.getSessionToken() && identity.getRefreshToken()) restoreStoredSession(nextState).catch(() => {});
 	},
 	_reset: () => {
 		state?.detachEventAppState?.();
@@ -2340,7 +2849,12 @@ const Amba = {
 	auth: {
 		signInAnonymously: async () => {
 			const s = getState();
-			return postAuth(s, P.authAnonymous, { anonymous_id: s.identity.getAnonymousId() });
+			try {
+				return await postAuth(s, P.authAnonymous, { anonymous_id: s.identity.getAnonymousId() });
+			} catch (err) {
+				if (!(err instanceof AmbaApiError) || err.code !== IDENTITY_SIGN_IN_REQUIRED) throw err;
+				return recoverFromHeldAnonymousId(s);
+			}
 		},
 		signInWithEmail: async (email, password) => {
 			requireEmail(email);
@@ -2413,12 +2927,12 @@ const Amba = {
 			const s = getState();
 			const sessionToken = s.identity.getSessionToken();
 			if (!sessionToken) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
-			return postAuth(s, P.authLink, {
+			return trackLink(s, postAuth(s, P.authLink, {
 				provider: providerTrimmed,
 				token: credential,
 				session_token: sessionToken,
 				...nonceField(options)
-			});
+			}));
 		},
 		linkSmsOtp: async (phone, code) => {
 			requireE164Phone(phone);
@@ -2426,7 +2940,7 @@ const Amba = {
 			const s = getState();
 			const sessionToken = s.identity.getSessionToken();
 			if (!sessionToken) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
-			return postUserNoRotate(s, P.authLink, {
+			return postLink(s, {
 				provider: "sms_otp",
 				phone,
 				code,
@@ -2439,7 +2953,7 @@ const Amba = {
 			const s = getState();
 			const sessionToken = s.identity.getSessionToken();
 			if (!sessionToken) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
-			return postUserNoRotate(s, P.authLink, {
+			return postLink(s, {
 				provider: "email_otp",
 				email,
 				code,
@@ -2452,7 +2966,7 @@ const Amba = {
 			const s = getState();
 			const sessionToken = s.identity.getSessionToken();
 			if (!sessionToken) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
-			return postUserNoRotate(s, P.authLink, {
+			return postLink(s, {
 				provider: "email_password",
 				email,
 				password,
@@ -2471,7 +2985,8 @@ const Amba = {
 		signOut: async (rotateAnonymousId = false) => {
 			const s = getState();
 			if (s.identity.getSessionToken()) try {
-				await s.http.post(P.authLogout, {});
+				const refreshToken = s.identity.getRefreshToken();
+				await s.http.post(P.authLogout, refreshToken ? { refresh_token: refreshToken } : {});
 			} catch (err) {
 				if (typeof console !== "undefined") console.warn("[amba] signOut server call failed", err);
 			}
@@ -2484,12 +2999,7 @@ const Amba = {
 			s.eventQueue?.flush();
 			notifyAuthSubscribers(null);
 		},
-		refresh: async () => {
-			const s = getState();
-			const refreshToken = s.identity.getRefreshToken();
-			if (!refreshToken) throw new AmbaApiError("UNAUTHORIZED", "no refresh token available — call signIn* first");
-			return postAuth(s, P.authRefresh, { refresh_token: refreshToken });
-		},
+		refresh: async () => refreshSession(getState()),
 		me: async () => {
 			const s = getState();
 			if (!s.identity.getSessionToken()) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");