@protobase/client 0.3.5 → 0.4.0

package/dist/better-auth-client.js

@@ -0,0 +1,18 @@
+import { passkeyClient } from "@better-auth/passkey/client";
+import { createAuthClient } from "better-auth/client";
+import { emailOTPClient, jwtClient, twoFactorClient } from "better-auth/client/plugins";
+//#region src/better-auth-client.ts
+/** Better Auth's browser client with the plugins `createAuth` turns on: tokens, emailed codes, two-factor authentication and passkeys. */
+const betterAuthClient = (baseURL, basePath, fetch) => createAuthClient({
+	baseURL,
+	basePath,
+	plugins: [
+		jwtClient(),
+		emailOTPClient(),
+		twoFactorClient(),
+		passkeyClient()
+	],
+	fetchOptions: { customFetchImpl: fetch }
+});
+//#endregion
+export { betterAuthClient };

package/dist/index.d.ts

@@ -3,7 +3,13 @@ import { ClientOptions } from "./transport.js";
 import { BatchOp, BatchRef, BatchResult, Facet, Histogram, HistogramBucket, ListPage, Meta, MetaResult, RecordOf, RecordPermissions, ResourcePermissions, ResourceRef, Series, SeriesParams, SeriesPoint, Stored } from "./types.js";
 import { Client, createClient } from "./client.js";
 import { ApiError, PreconditionFailedError, ProblemDetails, ProblemError, isApiError } from "./problem.js";
-import { AuthError, AuthSession, AuthSessionOptions, AuthUser, SetupStatus, createAuthSession, createStaticSession, tokenExpiry } from "./auth.js";
+import { SignInPolicy, SignInPolicyClient, SignInPolicyState, SignInRule, StaffAccessRule } from "./sign-in-policy.js";
+import { AccountSecurity, AccountSignIn, AuthenticatorSetup, Passkey, RequiredSetup } from "./account-security.js";
+import { StaffSignIn, StaffSignInClient } from "./staff-sign-in.js";
+import { AuthUser, SetupStatus, SignInMethod, SignInResult, TwoFactorMethod } from "./auth-types.js";
+import { AuthError } from "./auth-error.js";
+import { AuthSession, AuthSessionOptions, createAuthSession, tokenExpiry } from "./auth.js";
+import { createStaticSession } from "./static-session.js";
 import { AssistantClient, AssistantClientOptions, AssistantConnection, createAssistantClient } from "./assistant.js";
 import { RuntimeClient, RuntimeClientOptions, RuntimePolicy, RuntimeStatus, createRuntimeClient } from "./runtime.js";
-export { ApiError, type AssistantClient, type AssistantClientOptions, type AssistantConnection, AuthError, type AuthSession, type AuthSessionOptions, type AuthUser, type BatchOp, type BatchRef, type BatchResult, type Client, type ClientOptions, type Facet, type FilterInput, type Histogram, type HistogramBucket, type ListPage, type ListParams, type Meta, type MetaResult, PreconditionFailedError, type ProblemDetails, type ProblemError, type RecordOf, type RecordPermissions, type ResourcePermissions, type ResourceRef, type RuntimeClient, type RuntimeClientOptions, type RuntimePolicy, type RuntimeStatus, type Series, type SeriesParams, type SeriesPoint, type SetupStatus, type Stored, createAssistantClient, createAuthSession, createClient, createRuntimeClient, createStaticSession, filterText, isApiError, listWire, tokenExpiry };
+export { type AccountSecurity, type AccountSignIn, ApiError, type AssistantClient, type AssistantClientOptions, type AssistantConnection, AuthError, type AuthSession, type AuthSessionOptions, type AuthUser, type AuthenticatorSetup, type BatchOp, type BatchRef, type BatchResult, type Client, type ClientOptions, type Facet, type FilterInput, type Histogram, type HistogramBucket, type ListPage, type ListParams, type Meta, type MetaResult, type Passkey, PreconditionFailedError, type ProblemDetails, type ProblemError, type RecordOf, type RecordPermissions, type RequiredSetup, type ResourcePermissions, type ResourceRef, type RuntimeClient, type RuntimeClientOptions, type RuntimePolicy, type RuntimeStatus, type Series, type SeriesParams, type SeriesPoint, type SetupStatus, type SignInMethod, type SignInPolicy, type SignInPolicyClient, type SignInPolicyState, type SignInResult, type SignInRule, type StaffAccessRule, type StaffSignIn, type StaffSignInClient, type Stored, type TwoFactorMethod, createAssistantClient, createAuthSession, createClient, createRuntimeClient, createStaticSession, filterText, isApiError, listWire, tokenExpiry };

package/dist/index.js

@@ -1,7 +1,9 @@
 import { filterText, listWire } from "./query-string.js";
 import { ApiError, PreconditionFailedError, isApiError } from "./problem.js";
 import { createClient } from "./client.js";
-import { AuthError, createAuthSession, createStaticSession, tokenExpiry } from "./auth.js";
+import { AuthError } from "./auth-error.js";
+import { createAuthSession, tokenExpiry } from "./auth.js";
+import { createStaticSession } from "./static-session.js";
 import { createAssistantClient } from "./assistant.js";
 import { createRuntimeClient } from "./runtime.js";
 export { ApiError, AuthError, PreconditionFailedError, createAssistantClient, createAuthSession, createClient, createRuntimeClient, createStaticSession, filterText, isApiError, listWire, tokenExpiry };

package/dist/sign-in-flows.js

@@ -0,0 +1,69 @@
+import { authError } from "./auth-error.js";
+//#region src/sign-in-flows.ts
+/**
+* The ways to sign in: a password, an emailed code or a passkey, and the second step after a password or a code for
+* an account with two-factor authentication. `signedIn` runs once a session exists, to fetch the API token.
+*/
+const signInFlows = (client, signedIn) => {
+	const finish = async (data) => {
+		if (data?.twoFactorRedirect) return {
+			kind: "two-factor",
+			methods: data.twoFactorMethods ?? []
+		};
+		await signedIn();
+		return {
+			kind: "signed-in",
+			user: data?.user
+		};
+	};
+	return {
+		signIn: async (email, password) => {
+			const { data, error } = await client.signIn.email({
+				email,
+				password
+			});
+			if (error || !data) throw authError(error, "Sign-in failed");
+			return finish(data);
+		},
+		/** Emails a sign-in code when an account has this address; the answer is the same either way. */
+		sendSignInCode: async (email) => {
+			const { error } = await client.emailOtp.sendVerificationOtp({
+				email,
+				type: "sign-in"
+			});
+			if (error) throw authError(error, "Could not send the code");
+		},
+		signInWithCode: async (email, code) => {
+			const { data, error } = await client.signIn.emailOtp({
+				email,
+				otp: code
+			});
+			if (error || !data) throw authError(error, "Sign-in failed");
+			return finish(data);
+		},
+		/** Asks the browser for one of the person's passkeys for this site. */
+		signInWithPasskey: async () => {
+			const { data, error } = await client.signIn.passkey();
+			if (error || !data) throw authError(error, "Sign-in failed");
+			await signedIn();
+			return data.user;
+		},
+		/** Emails the code for the second step, to the address of the account signing in. */
+		sendTwoFactorCode: async () => {
+			const { error } = await client.twoFactor.sendOtp();
+			if (error) throw authError(error, "Could not send the code");
+		},
+		/** Finishes a sign-in with the second step. `trustDevice` skips it in this browser for 30 days. */
+		verifyTwoFactor: async ({ method, code, trustDevice = false }) => {
+			const { data, error } = await (method === "totp" ? client.twoFactor.verifyTotp : method === "otp" ? client.twoFactor.verifyOtp : client.twoFactor.verifyBackupCode)({
+				code,
+				trustDevice
+			});
+			if (error || !data) throw authError(error, "The code did not work");
+			await signedIn();
+			return data.user;
+		}
+	};
+};
+//#endregion
+export { signInFlows };

package/dist/sign-in-policy.d.ts

@@ -0,0 +1,37 @@
+import { BetterAuthClient } from "./better-auth-client.js";
+//#region src/sign-in-policy.d.ts
+export type SignInRule = 'allowed' | 'required' | 'forbidden';
+/** Whether the operator's staff may sign in as people: yes, yes and the person gets an email, or no. */
+export type StaffAccessRule = 'allowed' | 'notify' | 'forbidden';
+/**
+ * How people may sign in, as the server stores it: passwords and emailed codes are allowed or forbidden, passkeys and
+ * two-factor authentication can also be required (everyone without one is asked to set it up), and staff of the
+ * operator may sign in as people, with or without telling them, or not.
+ */
+export type SignInPolicy = {
+  password: 'allowed' | 'forbidden';
+  emailCode: 'allowed' | 'forbidden';
+  passkey: SignInRule;
+  twoFactor: SignInRule;
+  staffAccess: StaffAccessRule;
+};
+/**
+ * The saved policy, how it applies (`effective`: emailed codes need mail, and without mail passwords stay on and staff
+ * who would have to tell the person cannot sign in), the name of the operator provider when staff can sign in at all,
+ * and who saved it when.
+ */
+export type SignInPolicyState = {
+  policy: SignInPolicy;
+  effective: SignInPolicy;
+  mail: boolean;
+  operator?: string;
+  savedAt?: string;
+  savedBy?: string;
+};
+/** Reading and saving the sign-in policy, for admins. Saving rejects with `AuthError` saying why a policy cannot be saved. */
+export declare const signInPolicyClient: (client: BetterAuthClient) => {
+  read: () => Promise<SignInPolicyState>;
+  save: (policy: SignInPolicy) => Promise<SignInPolicyState>;
+};
+export type SignInPolicyClient = ReturnType<typeof signInPolicyClient>;
+//#endregion

package/dist/sign-in-policy.js

@@ -0,0 +1,20 @@
+import { authError } from "./auth-error.js";
+//#region src/sign-in-policy.ts
+/** Reading and saving the sign-in policy, for admins. Saving rejects with `AuthError` saying why a policy cannot be saved. */
+const signInPolicyClient = (client) => ({
+	read: async () => {
+		const { data, error } = await client.$fetch("/policy/sign-in");
+		if (error || !data) throw authError(error, "Could not read the sign-in policy");
+		return data;
+	},
+	save: async (policy) => {
+		const { data, error } = await client.$fetch("/policy/sign-in", {
+			method: "POST",
+			body: policy
+		});
+		if (error || !data) throw authError(error, "Could not save the sign-in policy");
+		return data;
+	}
+});
+//#endregion
+export { signInPolicyClient };

package/dist/staff-sign-in.d.ts

@@ -0,0 +1,32 @@
+import { BetterAuthClient } from "./better-auth-client.js";
+//#region src/staff-sign-in.d.ts
+/** A staff sign-in as someone: who, as whom (`user`), why, and when it started and ends (or ended). */
+export type StaffSignIn = {
+  id: string;
+  user: string;
+  staff: string;
+  staffName?: string;
+  reason: string;
+  startedAt: string;
+  expiresAt: string;
+  endedAt?: string;
+};
+/**
+ * Staff of the operator signing in as a person, for support. `start` answers the operator provider's URL, which sends
+ * the browser back to `callbackURL` signed in as the person, or with `?staff-error=<code>`. Each call rejects with `AuthError`.
+ */
+export declare const staffSignInClient: (client: BetterAuthClient) => {
+  start: (input: {
+    email: string;
+    reason: string;
+    callbackURL: string;
+  }) => Promise<string>;
+  /** The staff sign-in behind this session, or `undefined` when the person signed in themselves. */
+  current: () => Promise<StaffSignIn | undefined>;
+  /** Ends the staff session; the browser is signed out. */
+  stop: () => Promise<void>;
+  /** For admins: the log of staff sign-ins, newest first. */
+  log: () => Promise<StaffSignIn[]>;
+};
+export type StaffSignInClient = ReturnType<typeof staffSignInClient>;
+//#endregion

package/dist/staff-sign-in.js

@@ -0,0 +1,45 @@
+import { authError } from "./auth-error.js";
+//#region src/staff-sign-in.ts
+const iso = (value) => new Date(value).toISOString();
+const entry = ({ startedAt, expiresAt, endedAt, ...rest }) => ({
+	...rest,
+	startedAt: iso(startedAt),
+	expiresAt: iso(expiresAt),
+	...endedAt && { endedAt: iso(endedAt) }
+});
+/**
+* Staff of the operator signing in as a person, for support. `start` answers the operator provider's URL, which sends
+* the browser back to `callbackURL` signed in as the person, or with `?staff-error=<code>`. Each call rejects with `AuthError`.
+*/
+const staffSignInClient = (client) => ({
+	start: async (input) => {
+		const { data, error } = await client.$fetch("/staff/sign-in", {
+			method: "POST",
+			body: input
+		});
+		if (error || !data?.url) throw authError(error, "Could not start the staff sign-in");
+		return data.url;
+	},
+	/** The staff sign-in behind this session, or `undefined` when the person signed in themselves. */
+	current: async () => {
+		const { data, error } = await client.$fetch("/staff/session");
+		if (error || !data) throw authError(error, "Could not read the session");
+		return data.staff ? entry(data.staff) : void 0;
+	},
+	/** Ends the staff session; the browser is signed out. */
+	stop: async () => {
+		const { error } = await client.$fetch("/staff/stop", {
+			method: "POST",
+			body: {}
+		});
+		if (error) throw authError(error, "Could not end the staff session");
+	},
+	/** For admins: the log of staff sign-ins, newest first. */
+	log: async () => {
+		const { data, error } = await client.$fetch("/staff/sign-ins");
+		if (error || !data) throw authError(error, "Could not read the staff sign-ins");
+		return data.signIns.map(entry);
+	}
+});
+//#endregion
+export { staffSignInClient };

package/dist/static-session.d.ts

@@ -0,0 +1,10 @@
+import { AuthUser } from "./auth-types.js";
+import { AuthSession } from "./auth.js";
+//#region src/static-session.d.ts
+/**
+ * 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. Its account has nothing to set up, and it cannot change
+ * passkeys, two-factor authentication or the sign-in policy, and is never a staff session.
+ */
+export declare const createStaticSession: (token: string, user?: AuthUser) => AuthSession;
+//#endregion

package/dist/static-session.js

@@ -0,0 +1,81 @@
+import { AuthError } from "./auth-error.js";
+//#region src/static-session.ts
+const unsupported = (what) => async () => {
+	throw new AuthError(`A static session cannot ${what}`, 400);
+};
+/**
+* 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. Its account has nothing to set up, and it cannot change
+* passkeys, two-factor authentication or the sign-in policy, and is never a staff session.
+*/
+const createStaticSession = (token, user = {
+	id: "token",
+	email: "token",
+	name: "API token",
+	role: null
+}) => ({
+	token: async () => token,
+	status: async () => ({
+		needsAdmin: false,
+		signInMethods: ["password"],
+		passwordReset: false,
+		socialProviders: []
+	}),
+	session: async () => user,
+	signIn: async () => ({
+		kind: "signed-in",
+		user
+	}),
+	sendSignInCode: async () => void 0,
+	signInWithCode: async () => ({
+		kind: "signed-in",
+		user
+	}),
+	signInWithPasskey: async () => user,
+	sendTwoFactorCode: async () => void 0,
+	verifyTwoFactor: async () => user,
+	signInSocial: unsupported("sign in with a provider"),
+	signOut: async () => void 0,
+	requestPasswordReset: async () => void 0,
+	resetPassword: async () => void 0,
+	account: {
+		signInMethods: async () => ({
+			policy: {
+				password: "allowed",
+				emailCode: "allowed",
+				passkey: "allowed",
+				twoFactor: "allowed",
+				staffAccess: "allowed"
+			},
+			mail: false,
+			account: {
+				password: false,
+				passkeys: 0,
+				twoFactor: false,
+				authenticatorApp: false
+			},
+			missing: []
+		}),
+		passkeys: async () => [],
+		addPasskey: unsupported("add a passkey"),
+		renamePasskey: unsupported("rename a passkey"),
+		removePasskey: unsupported("remove a passkey"),
+		startAuthenticatorApp: unsupported("turn on two-factor authentication"),
+		confirmAuthenticatorApp: unsupported("turn on two-factor authentication"),
+		turnOnEmailedCodes: unsupported("turn on two-factor authentication"),
+		turnOffTwoFactor: unsupported("turn off two-factor authentication"),
+		newBackupCodes: unsupported("make backup codes")
+	},
+	signInPolicy: {
+		read: unsupported("read the sign-in policy"),
+		save: unsupported("save the sign-in policy")
+	},
+	staff: {
+		start: unsupported("start a staff sign-in"),
+		current: async () => void 0,
+		stop: unsupported("end a staff session"),
+		log: unsupported("read the staff sign-ins")
+	}
+});
+//#endregion
+export { createStaticSession };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/client",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Typed fetch client for the Protobase REST API.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,8 +29,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@protobase/layout": "0.3.5",
-    "@protobase/schema": "0.3.5",
+    "@better-auth/passkey": "^1.7.7",
+    "@protobase/layout": "0.4.0",
+    "@protobase/schema": "0.4.0",
     "better-auth": "^1.7.7"
   }
 }