@protobase/client 0.3.5 → 0.4.1

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/account-security.d.ts

@@ -0,0 +1,54 @@
+import { BetterAuthClient } from "./better-auth-client.js";
+import { SignInPolicy } from "./sign-in-policy.js";
+//#region src/account-security.d.ts
+/** What a sign-in policy can require that an account sets up once. */
+export type RequiredSetup = 'twoFactor' | 'passkey';
+/**
+ * The signed-in account's ways to sign in: the policy as it applies, whether mail is on (for emailed codes), what the
+ * account has (a password, how many passkeys, two-factor authentication, and whether that has an authenticator app
+ * with backup codes or only emailed codes), and what the policy requires that it lacks.
+ */
+export type AccountSignIn = {
+  policy: SignInPolicy;
+  mail: boolean;
+  account: {
+    password: boolean;
+    passkeys: number;
+    twoFactor: boolean;
+    authenticatorApp: boolean;
+  };
+  missing: RequiredSetup[];
+};
+export type Passkey = {
+  id: string;
+  name?: string;
+  createdAt?: string;
+  backedUp: boolean;
+};
+/** A new authenticator app: the `otpauth://` URI it scans, and the backup codes that work once each instead of a code. */
+export type AuthenticatorSetup = {
+  totpURI: string;
+  backupCodes: string[];
+};
+/**
+ * The signed-in person's passkeys and two-factor authentication. `password` is asked for by the changes that need it
+ * when the account has one. Each call rejects with `AuthError`.
+ */
+export declare const accountSecurity: (client: BetterAuthClient) => {
+  signInMethods: () => Promise<AccountSignIn>;
+  passkeys: () => Promise<Passkey[]>;
+  /** Asks the browser to create a passkey for this site, named `name` in the list. */
+  addPasskey: (name?: string) => Promise<void>;
+  renamePasskey: (id: string, name: string) => Promise<void>;
+  removePasskey: (id: string) => Promise<void>;
+  /** Starts two-factor authentication with an authenticator app; it is on once `confirmAuthenticatorApp` takes a code from the app. */
+  startAuthenticatorApp: (password?: string) => Promise<AuthenticatorSetup>;
+  confirmAuthenticatorApp: (code: string) => Promise<void>;
+  /** Turns on two-factor authentication with a code emailed at each sign-in. */
+  turnOnEmailedCodes: (password?: string) => Promise<void>;
+  turnOffTwoFactor: (password?: string) => Promise<void>;
+  /** New backup codes for the authenticator app; the old ones stop working. */
+  newBackupCodes: (password?: string) => Promise<string[]>;
+};
+export type AccountSecurity = ReturnType<typeof accountSecurity>;
+//#endregion

package/dist/account-security.js

@@ -0,0 +1,75 @@
+import { authError } from "./auth-error.js";
+//#region src/account-security.ts
+/**
+* The signed-in person's passkeys and two-factor authentication. `password` is asked for by the changes that need it
+* when the account has one. Each call rejects with `AuthError`.
+*/
+const accountSecurity = (client) => ({
+	signInMethods: async () => {
+		const { data, error } = await client.$fetch("/account/sign-in-methods");
+		if (error || !data) throw authError(error, "Could not read your sign-in methods");
+		return data;
+	},
+	passkeys: async () => {
+		const { data, error } = await client.passkey.listUserPasskeys();
+		if (error || !data) throw authError(error, "Could not read your passkeys");
+		return data.map((key) => ({
+			id: key.id,
+			backedUp: key.backedUp,
+			...key.name && { name: key.name },
+			...key.createdAt && { createdAt: new Date(key.createdAt).toISOString() }
+		}));
+	},
+	/** Asks the browser to create a passkey for this site, named `name` in the list. */
+	addPasskey: async (name) => {
+		const { error } = await client.passkey.addPasskey(name ? { name } : {});
+		if (error) throw authError(error, "Could not add the passkey");
+	},
+	renamePasskey: async (id, name) => {
+		const { error } = await client.passkey.updatePasskey({
+			id,
+			name
+		});
+		if (error) throw authError(error, "Could not rename the passkey");
+	},
+	removePasskey: async (id) => {
+		const { error } = await client.passkey.deletePasskey({ id });
+		if (error) throw authError(error, "Could not remove the passkey");
+	},
+	/** Starts two-factor authentication with an authenticator app; it is on once `confirmAuthenticatorApp` takes a code from the app. */
+	startAuthenticatorApp: async (password) => {
+		const { data, error } = await client.twoFactor.enable({
+			method: "totp",
+			...password && { password }
+		});
+		if (error || data?.method !== "totp") throw authError(error, "Could not start two-factor authentication");
+		return {
+			totpURI: data.totpURI,
+			backupCodes: data.backupCodes
+		};
+	},
+	confirmAuthenticatorApp: async (code) => {
+		const { error } = await client.twoFactor.verifyTotp({ code });
+		if (error) throw authError(error, "The code did not work");
+	},
+	/** Turns on two-factor authentication with a code emailed at each sign-in. */
+	turnOnEmailedCodes: async (password) => {
+		const { error } = await client.twoFactor.enable({
+			method: "otp",
+			...password && { password }
+		});
+		if (error) throw authError(error, "Could not turn on two-factor authentication");
+	},
+	turnOffTwoFactor: async (password) => {
+		const { error } = await client.twoFactor.disable(password ? { password } : {});
+		if (error) throw authError(error, "Could not turn off two-factor authentication");
+	},
+	/** New backup codes for the authenticator app; the old ones stop working. */
+	newBackupCodes: async (password) => {
+		const { data, error } = await client.twoFactor.generateBackupCodes(password ? { password } : {});
+		if (error || !data) throw authError(error, "Could not make new backup codes");
+		return data.backupCodes;
+	}
+});
+//#endregion
+export { accountSecurity };

package/dist/auth-error.d.ts

@@ -0,0 +1,8 @@
+//#region src/auth-error.d.ts
+/** A failed sign-in or account change, with Better Auth's status and code (for example `INVALID_EMAIL_OR_PASSWORD`). */
+export declare class AuthError extends Error {
+  readonly status: number;
+  readonly code?: string | undefined;
+  constructor(message: string, status: number, code?: string | undefined);
+}
+//#endregion

package/dist/auth-error.js

@@ -0,0 +1,16 @@
+//#region src/auth-error.ts
+/** A failed sign-in or account change, with Better Auth's status and code (for example `INVALID_EMAIL_OR_PASSWORD`). */
+var AuthError = class extends Error {
+	status;
+	code;
+	constructor(message, status, code) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.name = "AuthError";
+	}
+};
+/** Better Auth's error from a client call as an `AuthError`, with `fallback` when it has no message. */
+const authError = (error, fallback) => new AuthError(error?.message || fallback, error?.status ?? 500, error?.code);
+//#endregion
+export { AuthError, authError };

package/dist/auth-types.d.ts

@@ -0,0 +1,32 @@
+//#region src/auth-types.d.ts
+export type AuthUser = {
+  id: string;
+  email: string;
+  name: string;
+  role?: string | null;
+};
+/** A way to sign in the server offers: a password, a code emailed to the address, or a passkey. */
+export type SignInMethod = 'password' | 'emailCode' | 'passkey';
+/** The second step of a sign-in: a code from an authenticator app (`totp`), or one emailed for it (`otp`). A backup code works whenever `totp` does. */
+export type TwoFactorMethod = 'totp' | 'otp';
+/** A sign-in either finished, or waits for the second step with one of `methods`. */
+export type SignInResult = {
+  kind: 'signed-in';
+  user: AuthUser;
+} | {
+  kind: 'two-factor';
+  methods: TwoFactorMethod[];
+};
+/**
+ * `needsAdmin` while no user exists yet; `signInMethods` the ways to sign in the server's policy leaves on;
+ * `passwordReset` when the server can email reset links; `socialProviders` the ids of the sign-in providers, for example
+ * `github`; `staffSignIn` the operator provider's name when its staff can sign in as people.
+ */
+export type SetupStatus = {
+  needsAdmin: boolean;
+  signInMethods: SignInMethod[];
+  passwordReset: boolean;
+  socialProviders: string[];
+  staffSignIn?: string;
+};
+//#endregion

package/dist/auth.d.ts

@@ -1,16 +1,9 @@
+import { SignInPolicy, SignInPolicyState } from "./sign-in-policy.js";
+import { AccountSignIn, AuthenticatorSetup, Passkey } from "./account-security.js";
+import { StaffSignIn } from "./staff-sign-in.js";
+import { AuthUser, SetupStatus, SignInResult, TwoFactorMethod } from "./auth-types.js";
+import { AuthError } from "./auth-error.js";
 //#region src/auth.d.ts
-export type AuthUser = {
-  id: string;
-  email: string;
-  name: string;
-  role?: string | null;
-};
-/** A failed sign-in or sign-out, with Better Auth's status and code (for example `INVALID_EMAIL_OR_PASSWORD`). */
-export declare class AuthError extends Error {
-  readonly status: number;
-  readonly code?: string | undefined;
-  constructor(message: string, status: number, code?: string | undefined);
-}
 export type AuthSessionOptions = {
   /** Origin of the server; defaults to the page's own. */
   origin?: string;
@@ -24,25 +17,13 @@ export type AuthSessionOptions = {
 };
 /** The expiry of a JWT in milliseconds, read from its payload (the signature is the server's business). */
 export declare const tokenExpiry: (token: string) => number;
-/** `needsAdmin` while no user exists yet; `passwordReset` when the server can email reset links; `socialProviders` the ids of the sign-in providers, for example `github`. */
-export type SetupStatus = {
-  needsAdmin: boolean;
-  passwordReset: boolean;
-  socialProviders: string[];
-};
 /**
- * The browser side of Better Auth: sign in with email and password, and a short-lived JWT held in memory only
- * (never in storage), fetched with the session cookie and refreshed before it expires.
+ * The browser side of Better Auth: sign in with a password, an emailed code or a passkey (with a second step for an
+ * account with two-factor authentication), the account's passkeys and two-factor authentication (`account`), the
+ * sign-in policy for admins (`signInPolicy`), staff of the operator signing in as people (`staff`), and a short-lived
+ * JWT held in memory only (never in storage), fetched with the session cookie and refreshed before it expires.
  */
 export declare const createAuthSession: (options?: AuthSessionOptions) => {
-  token: ({ refresh }?: {
-    refresh?: boolean;
-  }) => Promise<string | undefined>;
-  /** Whether the first admin is still missing. Every server has a login, so a 404 means the URL is not a Protobase server. */
-  status: () => Promise<SetupStatus>;
-  /** The signed-in user from the session cookie, or `undefined`. */
-  session: () => Promise<AuthUser | undefined>;
-  signIn: (email: string, password: string) => Promise<AuthUser>;
   /**
    * Starts sign-in with a provider such as `github`: resolves with the provider's authorization URL, for the page to go to.
    * The provider sends the browser back to `callbackURL` signed in, or with `?error=<code>`.
@@ -56,11 +37,53 @@ export declare const createAuthSession: (options?: AuthSessionOptions) => {
   requestPasswordReset: (email: string, redirectTo: string) => Promise<void>;
   /** Sets a new password with the token from a reset link; the link works once. */
   resetPassword: (token: string, newPassword: string) => Promise<void>;
+  account: {
+    signInMethods: () => Promise<AccountSignIn>;
+    passkeys: () => Promise<Passkey[]>;
+    addPasskey: (name?: string) => Promise<void>;
+    renamePasskey: (id: string, name: string) => Promise<void>;
+    removePasskey: (id: string) => Promise<void>;
+    startAuthenticatorApp: (password?: string) => Promise<AuthenticatorSetup>;
+    confirmAuthenticatorApp: (code: string) => Promise<void>;
+    turnOnEmailedCodes: (password?: string) => Promise<void>;
+    turnOffTwoFactor: (password?: string) => Promise<void>;
+    newBackupCodes: (password?: string) => Promise<string[]>;
+  };
+  signInPolicy: {
+    read: () => Promise<SignInPolicyState>;
+    save: (policy: SignInPolicy) => Promise<SignInPolicyState>;
+  };
+  staff: {
+    stop: () => Promise<void>;
+    start: (input: {
+      email: string;
+      reason: string;
+      callbackURL: string;
+    }) => Promise<string>;
+    current: () => Promise<StaffSignIn | undefined>;
+    log: () => Promise<StaffSignIn[]>;
+  };
+  signIn: (email: string, password: string) => Promise<SignInResult>;
+  sendSignInCode: (email: string) => Promise<void>;
+  signInWithCode: (email: string, code: string) => Promise<SignInResult>;
+  signInWithPasskey: () => Promise<AuthUser>;
+  sendTwoFactorCode: () => Promise<void>;
+  verifyTwoFactor: ({ method, code, trustDevice }: {
+    method: TwoFactorMethod | "backup";
+    code: string;
+    trustDevice?: boolean;
+  }) => Promise<AuthUser>;
+  token: ({ refresh }?: {
+    refresh?: boolean;
+  }) => Promise<string | undefined>;
+  /**
+   * Whether the first admin is still missing, and how people can sign in. Every server has a login, so a 404 means the
+   * URL is not a Protobase server. A server from before sign-in methods were listed offers passwords only.
+   */
+  status: () => Promise<SetupStatus>;
+  /** The signed-in user from the session cookie, or `undefined`. */
+  session: () => Promise<AuthUser | undefined>;
 };
 export type AuthSession = ReturnType<typeof createAuthSession>;
-/**
- * A session that is already signed in with a token you hold, for stories and scripts (`protobase token <email>`).
- * It never refreshes, so use a token that outlives the run.
- */
-export declare const createStaticSession: (token: string, user?: AuthUser) => AuthSession;
-//#endregion
+//#endregion
+export { AuthError };

package/dist/auth.js

@@ -1,17 +1,10 @@
-import { createAuthClient } from "better-auth/client";
-import { jwtClient } from "better-auth/client/plugins";
+import { AuthError, authError } from "./auth-error.js";
+import { accountSecurity } from "./account-security.js";
+import { betterAuthClient } from "./better-auth-client.js";
+import { signInFlows } from "./sign-in-flows.js";
+import { signInPolicyClient } from "./sign-in-policy.js";
+import { staffSignInClient } from "./staff-sign-in.js";
 //#region src/auth.ts
-/** A failed sign-in or sign-out, with Better Auth's status and code (for example `INVALID_EMAIL_OR_PASSWORD`). */
-var AuthError = class extends Error {
-	status;
-	code;
-	constructor(message, status, code) {
-		super(message);
-		this.status = status;
-		this.code = code;
-		this.name = "AuthError";
-	}
-};
 /** The expiry of a JWT in milliseconds, read from its payload (the signature is the server's business). */
 const tokenExpiry = (token) => {
 	const payload = token.split(".")[1];
@@ -21,20 +14,18 @@ const tokenExpiry = (token) => {
 	return json.exp * 1e3;
 };
 /**
-* The browser side of Better Auth: sign in with email and password, and a short-lived JWT held in memory only
-* (never in storage), fetched with the session cookie and refreshed before it expires.
+* The browser side of Better Auth: sign in with a password, an emailed code or a passkey (with a second step for an
+* account with two-factor authentication), the account's passkeys and two-factor authentication (`account`), the
+* sign-in policy for admins (`signInPolicy`), staff of the operator signing in as people (`staff`), and a short-lived
+* JWT held in memory only (never in storage), fetched with the session cookie and refreshed before it expires.
 */
 const createAuthSession = (options = {}) => {
 	const origin = options.origin ?? globalThis.location?.origin ?? "http://localhost";
 	const basePath = options.basePath ?? "/api/auth";
 	const margin = options.refreshMarginMs ?? 6e4;
 	const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
-	const client = createAuthClient({
-		baseURL: origin,
-		basePath,
-		plugins: [jwtClient()],
-		fetchOptions: { customFetchImpl: doFetch }
-	});
+	const client = betterAuthClient(origin, basePath, doFetch);
+	const staff = staffSignInClient(client);
 	let cached;
 	let pending;
 	let timer;
@@ -66,7 +57,10 @@ const createAuthSession = (options = {}) => {
 	};
 	return {
 		token,
-		/** Whether the first admin is still missing. Every server has a login, so a 404 means the URL is not a Protobase server. */
+		/**
+		* Whether the first admin is still missing, and how people can sign in. Every server has a login, so a 404 means the
+		* URL is not a Protobase server. A server from before sign-in methods were listed offers passwords only.
+		*/
 		status: async () => {
 			const response = await doFetch(`${origin}${basePath}/status`);
 			if (response.status === 404) throw new AuthError("This server has no sign-in. Is the API URL right?", 404);
@@ -74,8 +68,10 @@ const createAuthSession = (options = {}) => {
 			const body = await response.json();
 			return {
 				needsAdmin: Boolean(body.needsAdmin),
+				signInMethods: body.signInMethods ?? ["password"],
 				passwordReset: Boolean(body.passwordReset),
-				socialProviders: body.socialProviders ?? []
+				socialProviders: body.socialProviders ?? [],
+				...body.staffSignIn && { staffSignIn: body.staffSignIn }
 			};
 		},
 		/** The signed-in user from the session cookie, or `undefined`. */
@@ -83,15 +79,7 @@ const createAuthSession = (options = {}) => {
 			const { data } = await client.getSession();
 			return data?.user;
 		},
-		signIn: async (email, password) => {
-			const { data, error } = await client.signIn.email({
-				email,
-				password
-			});
-			if (error || !data) throw new AuthError(error?.message || "Sign-in failed", error?.status ?? 500, error?.code);
-			await token({ refresh: true });
-			return data.user;
-		},
+		...signInFlows(client, () => token({ refresh: true })),
 		/**
 		* Starts sign-in with a provider such as `github`: resolves with the provider's authorization URL, for the page to go to.
 		* The provider sends the browser back to `callbackURL` signed in, or with `?error=<code>`.
@@ -103,7 +91,7 @@ const createAuthSession = (options = {}) => {
 				errorCallbackURL: callbackURL,
 				disableRedirect: true
 			});
-			if (error || !data?.url) throw new AuthError(error?.message || "Sign-in failed", error?.status ?? 500, error?.code);
+			if (error || !data?.url) throw authError(error, "Sign-in failed");
 			return data.url;
 		},
 		signOut: async () => {
@@ -119,7 +107,7 @@ const createAuthSession = (options = {}) => {
 				email,
 				redirectTo
 			});
-			if (error) throw new AuthError(error.message || "Could not send the reset link", error.status, error.code);
+			if (error) throw authError(error, "Could not send the reset link");
 		},
 		/** Sets a new password with the token from a reset link; the link works once. */
 		resetPassword: async (token, newPassword) => {
@@ -127,34 +115,18 @@ const createAuthSession = (options = {}) => {
 				token,
 				newPassword
 			});
-			if (error) throw new AuthError(error.message || "Could not set the password", error.status, error.code);
+			if (error) throw authError(error, "Could not set the password");
+		},
+		account: accountSecurity(client),
+		signInPolicy: signInPolicyClient(client),
+		staff: {
+			...staff,
+			stop: async () => {
+				forget();
+				await staff.stop();
+			}
 		}
 	};
 };
-/**
-* A session that is already signed in with a token you hold, for stories and scripts (`protobase token <email>`).
-* It never refreshes, so use a token that outlives the run.
-*/
-const createStaticSession = (token, user = {
-	id: "token",
-	email: "token",
-	name: "API token",
-	role: null
-}) => ({
-	token: async () => token,
-	status: async () => ({
-		needsAdmin: false,
-		passwordReset: false,
-		socialProviders: []
-	}),
-	session: async () => user,
-	signIn: async () => user,
-	signInSocial: async () => {
-		throw new AuthError("A static session cannot sign in with a provider", 400);
-	},
-	signOut: async () => void 0,
-	requestPasswordReset: async () => void 0,
-	resetPassword: async () => void 0
-});
 //#endregion
-export { AuthError, createAuthSession, createStaticSession, tokenExpiry };
+export { AuthError, createAuthSession, tokenExpiry };