@softr/sdk 0.0.24 → 0.0.25

package/dist/assertions.js

@@ -18,9 +18,6 @@ function assert(condition, message) {
 function panic(message) {
 	throwAtCaller(panic, new AssertionError(unwrapErrorMessage(message)));
 }
-function todo(message) {
-	throwAtCaller(todo, new UnimplementedError(unwrapErrorMessage(message)));
-}
 /**
 * A soft assertion that throws an error in non prod environments, including
 * staging, but logs an error in production mode.
@@ -47,9 +44,6 @@ var AssertionError = class extends Error {
 var SoftAssertionError = class extends Error {
 	name = "SoftAssertionError";
 };
-var UnimplementedError = class extends Error {
-	name = "UnimplementedError";
-};
 function unwrapErrorMessage(message) {
 	return typeof message === "function" ? message() : message ?? "";
 }
@@ -65,4 +59,4 @@ function throwAtCaller(f, ex) {
 }
 
 //#endregion
-export { assert, panic, requireDefined, softAssert, todo };
+export { assert, panic, requireDefined, softAssert };

package/dist/auth/methods/authenticator.d.ts

@@ -0,0 +1,80 @@
+import { User } from "../user.js";
+import { AuthError, Result } from "./utils.js";
+
+//#region src/auth/methods/authenticator.d.ts
+
+/**
+ * Starts enrolling an authenticator app, for a sign-in that asked to set one up
+ * or for a signed-in visitor adding one.
+ *
+ * `otpauthUri` is what an authenticator app reads. `qrPngBase64` is that same
+ * URI as a PNG for `<img src="data:image/png;base64,…">`, so a page can show
+ * the QR code without a QR library. Neither one enrols anybody.
+ * {@link confirmAuthenticatorSetup} does that, once it accepts a first code.
+ *
+ * Call it again to hand back a fresh QR code, for a visitor who lost the first
+ * one. Only the newest one enrols them.
+ */
+declare function startAuthenticatorSetup(): Promise<Result<{
+  otpauthUri: string;
+  qrPngBase64: string;
+}, AuthError>>;
+/**
+ * Enrols the authenticator app on its first code and signs the visitor in.
+ *
+ * This is the only call that returns the backup codes, and it returns them
+ * once. Nothing fetches them again, so render them before leaving the page.
+ */
+declare function confirmAuthenticatorSetup(details: {
+  code: string;
+}): Promise<Result<{
+  user: User;
+  backupCodes: Array<string>;
+}, AuthError>>;
+/**
+ * Skips enrolment and finishes the sign-in, for a visitor whose app offers an
+ * authenticator without requiring one. Only the `setupOptional` step.
+ *
+ * Later sign-ins stop asking.
+ */
+declare function skipAuthenticatorSetup(): Promise<Result<User, AuthError>>;
+/**
+ * Finishes a sign-in that stopped at the `verify` step, with the code the
+ * visitor's authenticator app shows or one of their backup codes.
+ *
+ * Each backup code works once.
+ */
+declare function verifyAuthenticator(credentials: {
+  code: string;
+} | {
+  backupCode: string;
+}): Promise<Result<User, AuthError>>;
+/**
+ * Emails the signed-in visitor the code that {@link resetAuthenticator} and
+ * {@link removeAuthenticator} ask for.
+ *
+ * Both change how the visitor signs in, so both want a code from their inbox
+ * on top of being signed in.
+ */
+declare function sendAuthenticatorResetCode(): Promise<Result<null, AuthError>>;
+/**
+ * Unpairs the visitor's authenticator app so they can enrol a new one with
+ * {@link startAuthenticatorSetup}, after a lost or replaced phone.
+ *
+ * `code` is the one {@link sendAuthenticatorResetCode} emailed.
+ */
+declare function resetAuthenticator(details: {
+  code: string;
+}): Promise<Result<null, AuthError>>;
+/**
+ * Turns the visitor's authenticator app off entirely.
+ *
+ * `code` is the one {@link sendAuthenticatorResetCode} emailed. An app that
+ * requires an authenticator will ask them to set one up again on their next
+ * sign-in.
+ */
+declare function removeAuthenticator(details: {
+  code: string;
+}): Promise<Result<null, AuthError>>;
+//#endregion
+export { confirmAuthenticatorSetup, removeAuthenticator, resetAuthenticator, sendAuthenticatorResetCode, skipAuthenticatorSetup, startAuthenticatorSetup, verifyAuthenticator };

package/dist/auth/methods/authenticator.js

@@ -0,0 +1,175 @@
+import { assert, panic } from "../../assertions.js";
+import { writeCookies } from "../../cookies.js";
+import { sessionConfig } from "../config.js";
+import { makePlatform } from "../platform.js";
+import { clearPendingAuth, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionToken } from "../session.js";
+import { authError } from "./utils.js";
+
+//#region src/auth/methods/authenticator.ts
+/**
+* Starts enrolling an authenticator app, for a sign-in that asked to set one up
+* or for a signed-in visitor adding one.
+*
+* `otpauthUri` is what an authenticator app reads. `qrPngBase64` is that same
+* URI as a PNG for `<img src="data:image/png;base64,…">`, so a page can show
+* the QR code without a QR library. Neither one enrols anybody.
+* {@link confirmAuthenticatorSetup} does that, once it accepts a first code.
+*
+* Call it again to hand back a fresh QR code, for a visitor who lost the first
+* one. Only the newest one enrols them.
+*/
+async function startAuthenticatorSetup() {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorSetupInit(readPendingAuthToken() ?? readSessionToken());
+	if (!result.ok) {
+		if (result.status === 401) return authError("notAuthenticated", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected authenticator setup to start, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	return {
+		success: true,
+		data: result.data
+	};
+}
+/**
+* Enrols the authenticator app on its first code and signs the visitor in.
+*
+* This is the only call that returns the backup codes, and it returns them
+* once. Nothing fetches them again, so render them before leaving the page.
+*/
+async function confirmAuthenticatorSetup(details) {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorSetupComplete(readPendingAuthToken() ?? readSessionToken(), details.code);
+	if (!result.ok) {
+		if (result.status === 400 || result.status === 401) return authError("invalidCode", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected authenticator setup to finish, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	const { session, backupCodes } = result.data;
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+		user: session.user,
+		permissions: session.permissions
+	}, session.jwt)]);
+	clearPendingAuth();
+	return {
+		success: true,
+		data: {
+			user: session.user,
+			backupCodes
+		}
+	};
+}
+/**
+* Skips enrolment and finishes the sign-in, for a visitor whose app offers an
+* authenticator without requiring one. Only the `setupOptional` step.
+*
+* Later sign-ins stop asking.
+*/
+async function skipAuthenticatorSetup() {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorSetupDismiss(readPendingAuthToken() ?? readSessionToken());
+	if (!result.ok) {
+		if (result.status === 401) return authError("notAuthenticated", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected to skip authenticator setup, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	const { session } = result.data;
+	assert(session, "Expected a session from skipping setup, but got none");
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+		user: session.user,
+		permissions: session.permissions
+	}, session.jwt)]);
+	clearPendingAuth();
+	return {
+		success: true,
+		data: session.user
+	};
+}
+/**
+* Finishes a sign-in that stopped at the `verify` step, with the code the
+* visitor's authenticator app shows or one of their backup codes.
+*
+* Each backup code works once.
+*/
+async function verifyAuthenticator(credentials) {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorVerify(readPendingAuthToken() ?? readSessionToken(), "code" in credentials ? { totpCode: credentials.code } : { backupCode: credentials.backupCode });
+	if (!result.ok) {
+		if (result.status === 400 || result.status === 401) return authError("invalidCode", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected to verify the authenticator, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	const { session } = result.data;
+	assert(session, "Expected a session from verification, but got none");
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+		user: session.user,
+		permissions: session.permissions
+	}, session.jwt)]);
+	clearPendingAuth();
+	return {
+		success: true,
+		data: session.user
+	};
+}
+/**
+* Emails the signed-in visitor the code that {@link resetAuthenticator} and
+* {@link removeAuthenticator} ask for.
+*
+* Both change how the visitor signs in, so both want a code from their inbox
+* on top of being signed in.
+*/
+async function sendAuthenticatorResetCode() {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorSendResetCode(readSessionToken());
+	if (!result.ok) {
+		if (result.status === 401) return authError("notAuthenticated", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected the reset code to be emailed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	return {
+		success: true,
+		data: null
+	};
+}
+/**
+* Unpairs the visitor's authenticator app so they can enrol a new one with
+* {@link startAuthenticatorSetup}, after a lost or replaced phone.
+*
+* `code` is the one {@link sendAuthenticatorResetCode} emailed.
+*/
+async function resetAuthenticator(details) {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorReset(readSessionToken(), details.code);
+	if (!result.ok) {
+		if (result.status === 400 || result.status === 401) return authError("invalidCode", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected the authenticator to be reset, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	return {
+		success: true,
+		data: null
+	};
+}
+/**
+* Turns the visitor's authenticator app off entirely.
+*
+* `code` is the one {@link sendAuthenticatorResetCode} emailed. An app that
+* requires an authenticator will ask them to set one up again on their next
+* sign-in.
+*/
+async function removeAuthenticator(details) {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorRemove(readSessionToken(), details.code);
+	if (!result.ok) {
+		if (result.status === 400 || result.status === 401) return authError("invalidCode", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected the authenticator to be removed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	return {
+		success: true,
+		data: null
+	};
+}
+
+//#endregion
+export { confirmAuthenticatorSetup, removeAuthenticator, resetAuthenticator, sendAuthenticatorResetCode, skipAuthenticatorSetup, startAuthenticatorSetup, verifyAuthenticator };

package/dist/auth/methods/code.d.ts

@@ -0,0 +1,40 @@
+import { User } from "../user.js";
+import { AuthError, Result } from "./utils.js";
+
+//#region src/auth/methods/code.d.ts
+
+/**
+ * Emails a one-time sign-in code, for an app that signs people in with a code
+ * rather than a password.
+ *
+ * It succeeds whether or not the address has an account, so nobody can use the
+ * form it backs to find out who is registered. Say "check your email" either
+ * way.
+ */
+declare function sendSignInCode(details: {
+  email: string;
+}): Promise<Result<null, AuthError>>;
+/**
+ * Signs a visitor in with the code {@link sendSignInCode} emailed them.
+ *
+ * A `signedIn` result means the visitor is signed in. An app that also asks for
+ * an authenticator app answers `authenticatorRequired` instead, naming the step
+ * to send them to next.
+ */
+declare function signInWithCode(credentials: {
+  email: string;
+  code: string;
+}): Promise<Result<{
+  status: "signedIn";
+  user: User;
+} | {
+  status: "authenticatorRequired";
+  /**
+   * `verify`: they have an authenticator app and owe a code.
+   * `setup`: the app requires one and they have none yet.
+   * `setupOptional`: same, except they may skip it instead.
+   */
+  step: "verify" | "setup" | "setupOptional";
+}, AuthError>>;
+//#endregion
+export { sendSignInCode, signInWithCode };

package/dist/auth/methods/code.js

@@ -0,0 +1,74 @@
+import { assert, panic } from "../../assertions.js";
+import { writeCookies } from "../../cookies.js";
+import { sessionConfig } from "../config.js";
+import { makePlatform } from "../platform.js";
+import { clearPendingAuth, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie } from "../session.js";
+import { authError } from "./utils.js";
+
+//#region src/auth/methods/code.ts
+/**
+* Emails a one-time sign-in code, for an app that signs people in with a code
+* rather than a password.
+*
+* It succeeds whether or not the address has an account, so nobody can use the
+* form it backs to find out who is registered. Say "check your email" either
+* way.
+*/
+async function sendSignInCode(details) {
+	const result = await makePlatform(sessionConfig().applicationId).sendSignInCode(details.email);
+	if (!result.ok) {
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status === 400) return authError("invalidDetails", result.message);
+		if (result.status >= 500) panic(`Expected the sign-in code to be emailed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app signs people in with an emailed code.`);
+	}
+	return {
+		success: true,
+		data: null
+	};
+}
+/**
+* Signs a visitor in with the code {@link sendSignInCode} emailed them.
+*
+* A `signedIn` result means the visitor is signed in. An app that also asks for
+* an authenticator app answers `authenticatorRequired` instead, naming the step
+* to send them to next.
+*/
+async function signInWithCode(credentials) {
+	const result = await makePlatform(sessionConfig().applicationId).signInWithCode(credentials);
+	if (!result.ok) {
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status === 400 || result.status === 401) return authError("invalidCode", result.message);
+		if (result.status >= 500) panic(`Expected sign-in to succeed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app signs people in with an emailed code.`);
+	}
+	if (result.data.status === "MFA_REQUIRED") {
+		const { mfa } = result.data;
+		assert(mfa, "Expected a challenge from sign-in, but got none");
+		writeCookies([makePendingAuthCookie(mfa.challengeToken)]);
+		return {
+			success: true,
+			data: {
+				status: "authenticatorRequired",
+				step: mfa.action === "VERIFICATION_REQUIRED" ? "verify" : mfa.action === "SETUP_REQUIRED" ? "setup" : "setupOptional"
+			}
+		};
+	}
+	const { session } = result.data;
+	assert(session, "Expected a session from sign-in, but got none");
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+		user: session.user,
+		permissions: session.permissions
+	}, session.jwt)]);
+	clearPendingAuth();
+	return {
+		success: true,
+		data: {
+			status: "signedIn",
+			user: session.user
+		}
+	};
+}
+
+//#endregion
+export { sendSignInCode, signInWithCode };

package/dist/auth/methods/magicLink.d.ts

@@ -0,0 +1,24 @@
+import { User } from "../user.js";
+import { AuthError, Result } from "./utils.js";
+
+//#region src/auth/methods/magicLink.d.ts
+
+/**
+ * Signs a visitor in with the token from a magic link they followed.
+ *
+ * The token keeps working after it is used, so anyone holding the link can sign
+ * in as that visitor. Never log it, and redirect away from the URL that carried
+ * it.
+ *
+ */
+declare function signInWithMagicLink(credentials: {
+  token: string;
+}): Promise<Result<{
+  status: "signedIn";
+  user: User;
+} | {
+  status: "authenticatorRequired";
+  step: "verify" | "setup" | "setupOptional";
+}, AuthError>>;
+//#endregion
+export { signInWithMagicLink };

package/dist/auth/methods/magicLink.js

@@ -0,0 +1,53 @@
+import { assert, panic } from "../../assertions.js";
+import { writeCookies } from "../../cookies.js";
+import { sessionConfig } from "../config.js";
+import { makePlatform } from "../platform.js";
+import { makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie } from "../session.js";
+import { authError } from "./utils.js";
+
+//#region src/auth/methods/magicLink.ts
+/**
+* Signs a visitor in with the token from a magic link they followed.
+*
+* The token keeps working after it is used, so anyone holding the link can sign
+* in as that visitor. Never log it, and redirect away from the URL that carried
+* it.
+*
+*/
+async function signInWithMagicLink(credentials) {
+	const result = await makePlatform(sessionConfig().applicationId).signInWithMagicLink(credentials);
+	if (!result.ok) {
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status === 400 || result.status === 401) return authError("invalidCredentials", result.message);
+		if (result.status >= 500) panic(`Expected magic-link sign-in to succeed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app signs people in with a magic link.`);
+	}
+	if (result.data.status === "MFA_REQUIRED") {
+		const { mfa } = result.data;
+		assert(mfa, "Expected a challenge from magic-link sign-in, but got none");
+		writeCookies([makePendingAuthCookie(mfa.challengeToken)]);
+		return {
+			success: true,
+			data: {
+				status: "authenticatorRequired",
+				step: mfa.action === "VERIFICATION_REQUIRED" ? "verify" : mfa.action === "SETUP_REQUIRED" ? "setup" : "setupOptional"
+			}
+		};
+	}
+	const { session } = result.data;
+	assert(session, "Expected a session from magic-link sign-in, but got none");
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+		user: session.user,
+		permissions: session.permissions
+	}, session.jwt)]);
+	return {
+		success: true,
+		data: {
+			status: "signedIn",
+			user: session.user
+		}
+	};
+}
+
+//#endregion
+export { signInWithMagicLink };

package/dist/auth/methods/password.d.ts

@@ -5,17 +5,31 @@ import { AuthError, Result } from "./utils.js";
 
 /**
  * Signs a visitor in with an email and password.
+ *
+ * A `signedIn` result means the visitor is signed in. An app that also asks for
+ * an authenticator app answers `authenticatorRequired` instead, naming the step
+ * to send them to next.
  */
 declare function signIn(credentials: {
   email: string;
   password: string;
-}): Promise<Result<User, AuthError>>;
+}): Promise<Result<{
+  status: "signedIn";
+  user: User;
+} | {
+  status: "authenticatorRequired";
+  /**
+   * `verify`: they have an authenticator app and owe a code.
+   * `setup`: the app requires one and they have none yet.
+   * `setupOptional`: same, except they may skip it instead.
+   */
+  step: "verify" | "setup" | "setupOptional";
+}, AuthError>>;
 /**
- * Signs the visitor out and clears the session cookies.
+ * Signs the visitor out.
  *
- * This revokes **every** outstanding session for that user in this app, on every
- * device: the platform stamps `tokensInvalidatedAt` and rejects anything issued
- * before it. There is no per-device sign-out.
+ * This ends **every** session that user has in this app, on every device. There
+ * is no per-device sign-out.
  */
 declare function signOut(): Promise<void>;
 //#endregion

package/dist/auth/methods/password.js

@@ -1,44 +1,65 @@
-import { panic, softAssert } from "../../assertions.js";
+import { assert, panic, softAssert } from "../../assertions.js";
 import { writeCookies } from "../../cookies.js";
 import { sessionConfig } from "../config.js";
 import { makePlatform } from "../platform.js";
-import { clearSession, makeSessionDataCookie, makeSessionTokenCookie, readSessionToken } from "../session.js";
+import { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readSessionToken } from "../session.js";
 import { authError } from "./utils.js";
 
 //#region src/auth/methods/password.ts
 /**
 * Signs a visitor in with an email and password.
+*
+* A `signedIn` result means the visitor is signed in. An app that also asks for
+* an authenticator app answers `authenticatorRequired` instead, naming the step
+* to send them to next.
 */
 async function signIn(credentials) {
 	const result = await makePlatform(sessionConfig().applicationId).tokens(credentials);
 	if (!result.ok) {
-		if (result.status === 401 || result.status === 429) return authError(result.status === 401 ? "invalidCredentials" : "tooManyAttempts", result.message);
-		if (result.status >= 500) panic(result.message);
+		if (result.status === 401) return authError("invalidCredentials", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected sign-in to succeed, but got ${result.status}: ` + result.message);
 		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows sign-in.`);
 	}
-	const { jwt, user, permissions } = result.data;
-	writeCookies([makeSessionTokenCookie(jwt), makeSessionDataCookie({
-		user,
-		permissions
-	}, jwt)]);
+	if (result.data.status === "MFA_REQUIRED") {
+		const { mfa } = result.data;
+		assert(mfa, "Expected a challenge from sign-in, but got none");
+		writeCookies([makePendingAuthCookie(mfa.challengeToken)]);
+		return {
+			success: true,
+			data: {
+				status: "authenticatorRequired",
+				step: mfa.action === "VERIFICATION_REQUIRED" ? "verify" : mfa.action === "SETUP_REQUIRED" ? "setup" : "setupOptional"
+			}
+		};
+	}
+	const { session } = result.data;
+	assert(session, "Expected a session from sign-in, but got none");
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+		user: session.user,
+		permissions: session.permissions
+	}, session.jwt)]);
+	clearPendingAuth();
 	return {
 		success: true,
-		data: user
+		data: {
+			status: "signedIn",
+			user: session.user
+		}
 	};
 }
 /**
-* Signs the visitor out and clears the session cookies.
+* Signs the visitor out.
 *
-* This revokes **every** outstanding session for that user in this app, on every
-* device: the platform stamps `tokensInvalidatedAt` and rejects anything issued
-* before it. There is no per-device sign-out.
+* This ends **every** session that user has in this app, on every device. There
+* is no per-device sign-out.
 */
 async function signOut() {
 	const token = readSessionToken();
 	clearSession();
 	if (!token) return;
 	const result = await makePlatform(sessionConfig().applicationId).signOut(token);
-	softAssert(result.ok || result.status < 500, () => `Could not revoke the session (${result.status}). This browser is signed out, but other devices may still be.`);
+	softAssert(result.ok || result.status < 500, () => `Expected sign-out to succeed, but got ${result.status}. This browser is signed out, other devices may not be.`);
 }
 
 //#endregion

package/dist/auth/methods/signup.d.ts

@@ -13,25 +13,33 @@ declare function signUp(details: {
   name?: string;
 }): Promise<Result<null, AuthError>>;
 /**
- * Finishes sign-up flow with the emailed code and signs the visitor in.
+ * Finishes a sign-up with the emailed code, creating the account and signing
+ * the visitor in.
  *
- * The platform splits on how the app is configured: a code-only app creates the
- * user on the second `sign-up` request and answers with a token, while a
- * password app answers it with an empty 200 and expects the password on
- * `users/new`.
+ * `password` is what the account is created with. Leave it out only for an app
+ * that signs people in with an emailed code. An app expecting a password
+ * rejects a sign-up without one, and the other way round.
+ *
+ * A `signedIn` result means the visitor is signed in. An app that also asks for
+ * an authenticator app answers `authenticatorRequired` instead, naming the step
+ * to send them to next.
  */
 declare function confirmSignUp(details: {
   email: string;
-  /**
-   * What `users/new` creates the account with, and unused on a code-only app,
-   * which never reaches that request.
-   *
-   * TODO: temporary in one respect — it is spent a second time on the
-   * 400-after-create workaround below, which goes away with the platform fix.
-   */
-  password: string;
   code: string;
   name?: string;
-}): Promise<Result<User, AuthError>>;
+  password?: string;
+}): Promise<Result<{
+  status: "signedIn";
+  user: User;
+} | {
+  status: "authenticatorRequired";
+  /**
+   * `verify`: they have an authenticator app and owe a code.
+   * `setup`: the app requires one and they have none yet.
+   * `setupOptional`: same, except they may skip it instead.
+   */
+  step: "verify" | "setup" | "setupOptional";
+}, AuthError>>;
 //#endregion
 export { confirmSignUp, signUp };