@softr/sdk 0.0.24 → 0.0.25

package/dist/auth/methods/signup.js

@@ -1,10 +1,9 @@
-import { panic, todo } from "../../assertions.js";
+import { assert, panic } from "../../assertions.js";
 import { writeCookies } from "../../cookies.js";
 import { sessionConfig } from "../config.js";
 import { makePlatform } from "../platform.js";
-import { makeSessionDataCookie, makeSessionTokenCookie } from "../session.js";
+import { clearPendingAuth, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie } from "../session.js";
 import { authError } from "./utils.js";
-import { signIn } from "./password.js";
 
 //#region src/auth/methods/signup.ts
 /**
@@ -13,11 +12,13 @@ import { signIn } from "./password.js";
 * User only exists once `confirmSignUp` returns the code.
 */
 async function signUp(details) {
-	const result = await makePlatform(sessionConfig().applicationId).signUp(signUpBody(details));
+	const result = await makePlatform(sessionConfig().applicationId).sendSignUpCode(details);
 	if (!result.ok) {
-		if (result.status >= 500) panic(result.message);
 		if (result.status === 409) return authError("emailTaken", result.message);
-		return authError("invalidDetails", result.message);
+		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-up code to be emailed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows sign-up.`);
 	}
 	return {
 		success: true,
@@ -25,63 +26,56 @@ async function signUp(details) {
 	};
 }
 /**
-* 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.
 */
 async function confirmSignUp(details) {
 	const platform = makePlatform(sessionConfig().applicationId);
-	const verified = await platform.signUp({
-		...signUpBody(details),
-		token: details.code
+	const { password,...rest } = details;
+	const result = password === void 0 ? await platform.signUpWithCode(rest) : await platform.signUpWithPassword({
+		...rest,
+		password
 	});
-	if (!verified.ok) {
-		if (verified.status >= 500) panic(verified.message);
-		if (verified.status === 409) return authError("emailTaken", verified.message);
-		return authError("invalidCode", verified.message);
+	if (!result.ok) {
+		if (result.status === 409) return authError("emailTaken", result.message);
+		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-up to succeed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows sign-up.`);
 	}
-	let token = verified.data?.jwt;
-	if (!token) {
-		const created = await platform.new({
-			...signUpBody(details),
-			password: details.password,
-			token: details.code
-		});
-		if (created.ok) token = created.data?.jwt;
-		else {
-			if (created.status >= 500) panic(created.message);
-			if (created.status === 409) return authError("emailTaken", created.message);
-			const signedIn = await signIn({
-				email: details.email,
-				password: details.password
-			});
-			if (!signedIn.success) return authError("invalidCode", created.message);
-			return signedIn;
-		}
+	if (result.data.status === "MFA_REQUIRED") {
+		const { mfa } = result.data;
+		assert(mfa, "Expected a challenge from sign-up, 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"
+			}
+		};
 	}
-	if (!token) todo("The sign-up returned no session token. This app is configured for a sign-up flow the SDK cannot finish yet.");
-	const result = await platform.session(token);
-	if (!result.ok) panic(result.message);
-	const session = result.data;
-	if (session.user === null) panic("Session token issued, but no user could be resolved for it.");
-	writeCookies([makeSessionTokenCookie(token), makeSessionDataCookie(session, token)]);
+	const { session } = result.data;
+	assert(session, "Expected a session from sign-up, but got none");
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+		user: session.user,
+		permissions: session.permissions
+	}, session.jwt)]);
+	clearPendingAuth();
 	return {
 		success: true,
-		data: session.user
-	};
-}
-/**
-* `name` is dropped when absent rather than sent as `undefined`: the platform's
-* validator runs on whatever key is present, and an explicit null is not the
-* same request as no name at all.
-*/
-function signUpBody(details) {
-	return details.name === void 0 ? { email: details.email } : {
-		email: details.email,
-		name: details.name
+		data: {
+			status: "signedIn",
+			user: session.user
+		}
 	};
 }
 

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

@@ -0,0 +1,35 @@
+import { User } from "../user.js";
+import { AuthError, Result } from "./utils.js";
+
+//#region src/auth/methods/social.d.ts
+
+/**
+ * Signs a visitor in with a Google token the browser obtained, creating their
+ * account the first time.
+ *
+ * Pass the id token Google Identity Services handed the page. An access token
+ * is rejected, and so is a token minted for another app. `fullName` names a
+ * first-time visitor and does nothing for one who already has an account.
+ *
+ * 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 signInWithGoogle(credentials: {
+  email: string;
+  token: string;
+  fullName?: 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 { signInWithGoogle };

package/dist/auth/methods/social.js

@@ -0,0 +1,58 @@
+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/social.ts
+/**
+* Signs a visitor in with a Google token the browser obtained, creating their
+* account the first time.
+*
+* Pass the id token Google Identity Services handed the page. An access token
+* is rejected, and so is a token minted for another app. `fullName` names a
+* first-time visitor and does nothing for one who already has an account.
+*
+* 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 signInWithGoogle(credentials) {
+	const result = await makePlatform(sessionConfig().applicationId).signInWithGoogle(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 Google sign-in to succeed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows Google sign-in.`);
+	}
+	if (result.data.status === "MFA_REQUIRED") {
+		const { mfa } = result.data;
+		assert(mfa, "Expected a challenge from Google 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 Google 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 { signInWithGoogle };

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

@@ -10,6 +10,6 @@ type AuthError = {
   code: AuthErrorCode;
   message: string;
 };
-type AuthErrorCode = "invalidCredentials" | "tooManyAttempts" | "emailTaken" | "invalidDetails" | "invalidCode";
+type AuthErrorCode = "invalidCredentials" | "tooManyAttempts" | "emailTaken" | "invalidDetails" | "invalidCode" | "notAuthenticated";
 //#endregion
 export { AuthError, Result };

package/dist/auth/platform.js

@@ -22,18 +22,196 @@ function makePlatform(applicationId) {
 			method: "POST",
 			json: credentials
 		}, z.object({
-			jwt: z.string(),
-			user: userSchema,
-			permissions: permissionsSchema
+			status: z.enum(["AUTHENTICATED", "MFA_REQUIRED"]),
+			session: z.object({
+				jwt: z.string(),
+				user: userSchema,
+				permissions: permissionsSchema
+			}).nullish(),
+			mfa: z.object({
+				action: z.enum([
+					"VERIFICATION_REQUIRED",
+					"SETUP_REQUIRED",
+					"SETUP_OPTIONAL"
+				]),
+				challengeToken: z.string()
+			}).nullish()
+		})),
+		sendSignInCode: (email) => request(`/v1/vibe/applications/${applicationId}/users/tokens/send-code`, {
+			method: "POST",
+			json: { email }
+		}, z.null()),
+		signInWithCode: (credentials) => request(`/v1/vibe/applications/${applicationId}/users/tokens/with-code`, {
+			method: "POST",
+			json: credentials
+		}, z.object({
+			status: z.enum(["AUTHENTICATED", "MFA_REQUIRED"]),
+			session: z.object({
+				jwt: z.string(),
+				user: userSchema,
+				permissions: permissionsSchema
+			}).nullish(),
+			mfa: z.object({
+				action: z.enum([
+					"VERIFICATION_REQUIRED",
+					"SETUP_REQUIRED",
+					"SETUP_OPTIONAL"
+				]),
+				challengeToken: z.string()
+			}).nullish()
+		})),
+		signInWithGoogle: (body) => request(`/v1/vibe/applications/${applicationId}/users/tokens/with-google`, {
+			method: "POST",
+			json: body
+		}, z.object({
+			status: z.enum(["AUTHENTICATED", "MFA_REQUIRED"]),
+			session: z.object({
+				jwt: z.string(),
+				user: userSchema,
+				permissions: permissionsSchema
+			}).nullish(),
+			mfa: z.object({
+				action: z.enum([
+					"VERIFICATION_REQUIRED",
+					"SETUP_REQUIRED",
+					"SETUP_OPTIONAL"
+				]),
+				challengeToken: z.string()
+			}).nullish()
 		})),
-		signUp: (body) => request(`/v1/applications/${applicationId}/users/sign-up`, {
+		signInWithMagicLink: (body) => request(`/v1/vibe/applications/${applicationId}/users/tokens/with-magic-link`, {
 			method: "POST",
 			json: body
-		}, z.object({ jwt: z.string().nullish() }).nullable()),
-		new: (body) => request(`/v1/applications/${applicationId}/users/new`, {
+		}, z.object({
+			status: z.enum(["AUTHENTICATED", "MFA_REQUIRED"]),
+			session: z.object({
+				jwt: z.string(),
+				user: userSchema,
+				permissions: permissionsSchema
+			}).nullish(),
+			mfa: z.object({
+				action: z.enum([
+					"VERIFICATION_REQUIRED",
+					"SETUP_REQUIRED",
+					"SETUP_OPTIONAL"
+				]),
+				challengeToken: z.string()
+			}).nullish()
+		})),
+		sendSignUpCode: (body) => request(`/v1/vibe/applications/${applicationId}/users/sign-up/send-code`, {
+			method: "POST",
+			json: body
+		}, z.null()),
+		signUpWithCode: (body) => request(`/v1/vibe/applications/${applicationId}/users/sign-up/with-code`, {
+			method: "POST",
+			json: body
+		}, z.object({
+			status: z.enum(["AUTHENTICATED", "MFA_REQUIRED"]),
+			session: z.object({
+				jwt: z.string(),
+				user: userSchema,
+				permissions: permissionsSchema
+			}).nullish(),
+			mfa: z.object({
+				action: z.enum([
+					"VERIFICATION_REQUIRED",
+					"SETUP_REQUIRED",
+					"SETUP_OPTIONAL"
+				]),
+				challengeToken: z.string()
+			}).nullish()
+		})),
+		signUpWithPassword: (body) => request(`/v1/vibe/applications/${applicationId}/users/sign-up/with-password`, {
 			method: "POST",
 			json: body
-		}, z.object({ jwt: z.string().nullish() }).nullable()),
+		}, z.object({
+			status: z.enum(["AUTHENTICATED", "MFA_REQUIRED"]),
+			session: z.object({
+				jwt: z.string(),
+				user: userSchema,
+				permissions: permissionsSchema
+			}).nullish(),
+			mfa: z.object({
+				action: z.enum([
+					"VERIFICATION_REQUIRED",
+					"SETUP_REQUIRED",
+					"SETUP_OPTIONAL"
+				]),
+				challengeToken: z.string()
+			}).nullish()
+		})),
+		authenticatorSetupInit: (token) => request(`/v1/vibe/applications/${applicationId}/users/authenticator/setup/init`, {
+			method: "POST",
+			token
+		}, z.object({
+			otpauthUri: z.string(),
+			qrPngBase64: z.string()
+		})),
+		authenticatorSetupComplete: (token, code) => request(`/v1/vibe/applications/${applicationId}/users/authenticator/setup/complete`, {
+			method: "POST",
+			token,
+			json: { code }
+		}, z.object({
+			session: z.object({
+				jwt: z.string(),
+				user: userSchema,
+				permissions: permissionsSchema
+			}),
+			backupCodes: z.array(z.string())
+		})),
+		authenticatorSetupDismiss: (token) => request(`/v1/vibe/applications/${applicationId}/users/authenticator/setup/dismiss`, {
+			method: "POST",
+			token
+		}, z.object({
+			status: z.enum(["AUTHENTICATED", "MFA_REQUIRED"]),
+			session: z.object({
+				jwt: z.string(),
+				user: userSchema,
+				permissions: permissionsSchema
+			}).nullish(),
+			mfa: z.object({
+				action: z.enum([
+					"VERIFICATION_REQUIRED",
+					"SETUP_REQUIRED",
+					"SETUP_OPTIONAL"
+				]),
+				challengeToken: z.string()
+			}).nullish()
+		})),
+		authenticatorVerify: (token, body) => request(`/v1/vibe/applications/${applicationId}/users/authenticator/totp/verify`, {
+			method: "POST",
+			token,
+			json: body
+		}, z.object({
+			status: z.enum(["AUTHENTICATED", "MFA_REQUIRED"]),
+			session: z.object({
+				jwt: z.string(),
+				user: userSchema,
+				permissions: permissionsSchema
+			}).nullish(),
+			mfa: z.object({
+				action: z.enum([
+					"VERIFICATION_REQUIRED",
+					"SETUP_REQUIRED",
+					"SETUP_OPTIONAL"
+				]),
+				challengeToken: z.string()
+			}).nullish()
+		})),
+		authenticatorSendResetCode: (token) => request(`/v1/vibe/applications/${applicationId}/users/authenticator/reset/send-code`, {
+			method: "POST",
+			token
+		}, z.null()),
+		authenticatorReset: (token, code) => request(`/v1/vibe/applications/${applicationId}/users/authenticator/reset`, {
+			method: "POST",
+			token,
+			json: { code }
+		}, z.null()),
+		authenticatorRemove: (token, code) => request(`/v1/vibe/applications/${applicationId}/users/authenticator/remove`, {
+			method: "POST",
+			token,
+			json: { code }
+		}, z.null()),
 		signOut: (token) => request(`/v1/applications/${applicationId}/users/sign-out`, {
 			method: "POST",
 			token

package/dist/auth/server.d.ts

@@ -1,5 +1,9 @@
+import { confirmAuthenticatorSetup, removeAuthenticator, resetAuthenticator, sendAuthenticatorResetCode, skipAuthenticatorSetup, startAuthenticatorSetup, verifyAuthenticator } from "./methods/authenticator.js";
+import { sendSignInCode, signInWithCode } from "./methods/code.js";
+import { signInWithMagicLink } from "./methods/magicLink.js";
 import { signIn, signOut } from "./methods/password.js";
 import { confirmSignUp, signUp } from "./methods/signup.js";
+import { signInWithGoogle } from "./methods/social.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/auth/server.d.ts
@@ -12,6 +16,17 @@ declare const auth: {
   signOut: typeof signOut;
   signUp: typeof signUp;
   confirmSignUp: typeof confirmSignUp;
+  sendSignInCode: typeof sendSignInCode;
+  signInWithCode: typeof signInWithCode;
+  signInWithGoogle: typeof signInWithGoogle;
+  signInWithMagicLink: typeof signInWithMagicLink;
+  startAuthenticatorSetup: typeof startAuthenticatorSetup;
+  confirmAuthenticatorSetup: typeof confirmAuthenticatorSetup;
+  skipAuthenticatorSetup: typeof skipAuthenticatorSetup;
+  verifyAuthenticator: typeof verifyAuthenticator;
+  sendAuthenticatorResetCode: typeof sendAuthenticatorResetCode;
+  resetAuthenticator: typeof resetAuthenticator;
+  removeAuthenticator: typeof removeAuthenticator;
 };
 //#endregion
 export { auth };

package/dist/auth/server.js

@@ -1,5 +1,9 @@
+import { confirmAuthenticatorSetup, removeAuthenticator, resetAuthenticator, sendAuthenticatorResetCode, skipAuthenticatorSetup, startAuthenticatorSetup, verifyAuthenticator } from "./methods/authenticator.js";
+import { sendSignInCode, signInWithCode } from "./methods/code.js";
+import { signInWithMagicLink } from "./methods/magicLink.js";
 import { signIn, signOut } from "./methods/password.js";
 import { confirmSignUp, signUp } from "./methods/signup.js";
+import { signInWithGoogle } from "./methods/social.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/auth/server.ts
@@ -10,7 +14,18 @@ const auth = {
 	signIn,
 	signOut,
 	signUp,
-	confirmSignUp
+	confirmSignUp,
+	sendSignInCode,
+	signInWithCode,
+	signInWithGoogle,
+	signInWithMagicLink,
+	startAuthenticatorSetup,
+	confirmAuthenticatorSetup,
+	skipAuthenticatorSetup,
+	verifyAuthenticator,
+	sendAuthenticatorResetCode,
+	resetAuthenticator,
+	removeAuthenticator
 };
 
 //#endregion

package/dist/auth/session.js

@@ -9,8 +9,14 @@ import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:
 //#region src/auth/session.ts
 const SESSION_TOKEN = "session_token";
 const SESSION_DATA = "session_data";
+const PENDING_AUTH = "pending_auth";
 const SESSION_DATA_TTL_SECONDS = 300;
 /**
+* How long a visitor has to answer a second factor. The platform expires the
+* challenge token itself. This only decides how long the browser carries it.
+*/
+const PENDING_AUTH_TTL_SECONDS = 600;
+/**
 * A browser refuses a `__Host-` cookie unless it is `Secure`, `Path=/` and free
 * of `Domain` — that last clause is the one worth having, since it stops a
 * sibling host planting a cookie of this name for us to honour.
@@ -67,10 +73,37 @@ function makeSessionDataCookie(session, sessionToken) {
 	});
 }
 /**
+* The challenge token from a sign-in that stopped at a second factor, or
+* `null`.
+*
+* It is a bearer credential scoped to the authenticator endpoints, so it stays
+* sealed in the jar the way a session token does, instead of passing through
+* the app.
+*/
+function readPendingAuthToken() {
+	const { name } = sessionCookie(PENDING_AUTH);
+	return openEnvelope(readRequestCookies()[name], PENDING_AUTH);
+}
+function makePendingAuthCookie(token) {
+	const { name, secure } = sessionCookie(PENDING_AUTH);
+	return serializeCookie(name, sealEnvelope(token, PENDING_AUTH), {
+		maxAge: PENDING_AUTH_TTL_SECONDS,
+		secure
+	});
+}
+/** Drops an outstanding challenge without touching the session. */
+function clearPendingAuth() {
+	clearCookies([PENDING_AUTH]);
+}
+/**
 * Writes rather than returns: a forgotten list would leave the session live.
 */
 function clearSession() {
-	clearCookies([SESSION_TOKEN, SESSION_DATA]);
+	clearCookies([
+		SESSION_TOKEN,
+		SESSION_DATA,
+		PENDING_AUTH
+	]);
 }
 const sessionDataSchema = z.object({
 	user: userSchema.nullable(),
@@ -163,4 +196,4 @@ function openEnvelope(raw, purpose) {
 }
 
 //#endregion
-export { clearSession, makeSessionDataCookie, makeSessionTokenCookie, readSessionData, readSessionToken };
+export { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionData, readSessionToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.24
+  library_version: 0.0.25
 ---
 
 # Softr SDK core
@@ -124,4 +124,4 @@ type User = {
 
 ## Version
 
-Targets `@softr/sdk` v0.0.24.
+Targets `@softr/sdk` v0.0.25.