@procedures/better-auth 0.13.0 → 0.13.1

package/dist/browser.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The browser half of the sign-in (Graph's split, wave 2, W8): the calls of a page to the auth routes of a
+ * procedures server with Better Auth. This entry has no framework and no global state: each function gives data,
+ * and the app decides what the page does (a redirect, a reload).
+ *
+ * - The session cookie is `httpOnly`, so each call sends the cookies (`credentials: "include"`).
+ * - The passkeys use WebAuthn through `@simplewebauthn/browser`. It loads only when a passkey function runs.
+ * - The functions give `{ error }` for a refused or failed call. They do not throw for an answer of the server.
+ *
+ * Import it as `@procedures/better-auth/browser`. The package root is for the server.
+ */
+/** A signed-in user, as the session route gives it. */
+export interface BrowserUser {
+    readonly id: string;
+    readonly name?: string | undefined;
+    readonly email?: string | undefined;
+}
+/** A refused or failed call. */
+export interface BrowserAuthError {
+    readonly error: string;
+}
+/** The WebAuthn ceremonies. The default is `@simplewebauthn/browser`. A test gives its own. */
+export interface WebAuthnCeremonies {
+    startRegistration(options: {
+        optionsJSON: unknown;
+    }): Promise<unknown>;
+    startAuthentication(options: {
+        optionsJSON: unknown;
+    }): Promise<unknown>;
+}
+/** The options of `createBrowserAuth`. */
+export interface BrowserAuthOptions {
+    /**
+     * The origin of the server. An empty text is the origin of the page, the simplest form. A server on another
+     * origin needs CORS with credentials for the origin of the page (refer to the README).
+     */
+    readonly baseURL: string;
+    /** The path of the auth routes. The default is `/auth`, as `betterAuthConfig` gives it. */
+    readonly basePath?: string | undefined;
+    /** The fetch of the calls. The default is the fetch of the page. */
+    readonly fetch?: typeof fetch | undefined;
+    /** The WebAuthn ceremonies of the passkeys. */
+    readonly webauthn?: WebAuthnCeremonies | undefined;
+    /** The longest wait of `session()`, in milliseconds. The default is 4000. */
+    readonly sessionTimeoutMs?: number | undefined;
+}
+/** The sign-in calls of a page. */
+export interface BrowserAuth {
+    /** The signed-in user of this browser, or undefined (signed out, or the server did not answer in time). */
+    session(): Promise<BrowserUser | undefined>;
+    /** The page of the provider: the app goes to `url`. After the sign-in, the provider comes back to `callbackURL`. */
+    signInSocial(provider: string, callbackURL: string, errorCallbackURL?: string): Promise<{
+        readonly url: string;
+    } | BrowserAuthError>;
+    /** This method ends the session. The app then loads the page again. */
+    signOut(): Promise<{
+        readonly signedOut: true;
+    } | BrowserAuthError>;
+    /** This method makes a passkey of this device for the signed-in user. */
+    addPasskey(name: string): Promise<{
+        readonly added: true;
+        readonly name: string;
+    } | BrowserAuthError>;
+    /** This method signs in with a passkey of this device. The app then loads the page again. */
+    signInWithPasskey(): Promise<{
+        readonly signedIn: true;
+    } | BrowserAuthError>;
+    /** A test server only (`AUTH_TEST_ACCOUNTS`): a sign-in, or a sign-up, with an email and a password. */
+    signInWithPassword(input: {
+        email: string;
+        password: string;
+        name?: string | undefined;
+        signUp?: boolean | undefined;
+    }): Promise<{
+        readonly signedIn: true;
+        readonly user?: string | undefined;
+    } | BrowserAuthError>;
+}
+/**
+ * This function gives the sign-in calls of a page to a server.
+ *
+ * @example
+ * ```ts
+ * const auth = createBrowserAuth({ baseURL: "https://api.example.com" });
+ * const user = await auth.session();
+ * const out = await auth.signInSocial("github", location.href);
+ * if ("url" in out) location.assign(out.url);
+ * ```
+ */
+export declare function createBrowserAuth(options: BrowserAuthOptions): BrowserAuth;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,+FAA+F;AAC/F,MAAM,WAAW,kBAAkB;IACjC,iBAAiB,CAAC,OAAO,EAAE;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,mBAAmB,CAAC,OAAO,EAAE;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,GAAG,SAAS,CAAC;IAC1C,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACnD,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChD;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,2GAA2G;IAC3G,OAAO,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAC5C,oHAAoH;IACpH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,gBAAgB,CAAC,CAAC;IACrI,uEAAuE;IACvE,OAAO,IAAI,OAAO,CAAC;QAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;KAAE,GAAG,gBAAgB,CAAC,CAAC;IACpE,yEAAyE;IACzE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,gBAAgB,CAAC,CAAC;IACtG,6FAA6F;IAC7F,iBAAiB,IAAI,OAAO,CAAC;QAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG,gBAAgB,CAAC,CAAC;IAC7E,wGAAwG;IACxG,kBAAkB,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,gBAAgB,CAAC,CAAC;CACtN;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAuF1E"}

package/dist/browser.js

@@ -0,0 +1,114 @@
+/**
+ * The browser half of the sign-in (Graph's split, wave 2, W8): the calls of a page to the auth routes of a
+ * procedures server with Better Auth. This entry has no framework and no global state: each function gives data,
+ * and the app decides what the page does (a redirect, a reload).
+ *
+ * - The session cookie is `httpOnly`, so each call sends the cookies (`credentials: "include"`).
+ * - The passkeys use WebAuthn through `@simplewebauthn/browser`. It loads only when a passkey function runs.
+ * - The functions give `{ error }` for a refused or failed call. They do not throw for an answer of the server.
+ *
+ * Import it as `@procedures/better-auth/browser`. The package root is for the server.
+ */
+const errorOf = (answer) => ({
+    error: typeof answer.json?.["message"] === "string" ? answer.json["message"] : `HTTP ${answer.status}`,
+});
+/**
+ * This function gives the sign-in calls of a page to a server.
+ *
+ * @example
+ * ```ts
+ * const auth = createBrowserAuth({ baseURL: "https://api.example.com" });
+ * const user = await auth.session();
+ * const out = await auth.signInSocial("github", location.href);
+ * if ("url" in out) location.assign(out.url);
+ * ```
+ */
+export function createBrowserAuth(options) {
+    const base = `${options.baseURL.replace(/\/+$/, "")}${options.basePath ?? "/auth"}`;
+    const doFetch = options.fetch ?? ((...args) => fetch(...args));
+    const timeoutMs = options.sessionTimeoutMs ?? 4000;
+    let ceremonies;
+    const webauthn = () => (ceremonies ??= options.webauthn ? Promise.resolve(options.webauthn) : import("@simplewebauthn/browser"));
+    const call = async (path, init = {}) => {
+        const response = await doFetch(`${base}${path}`, { credentials: "include", ...init });
+        let json;
+        try {
+            const body = await response.json();
+            json = body !== null && typeof body === "object" ? body : undefined;
+        }
+        catch {
+            json = undefined;
+        }
+        return { ok: response.ok, status: response.status, json };
+    };
+    const post = (path, body) => call(path, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body ?? {}) });
+    return {
+        async session() {
+            const abort = new AbortController();
+            const timer = setTimeout(() => abort.abort(), timeoutMs);
+            try {
+                const answer = await call("/get-session", { signal: abort.signal });
+                const user = answer.ok ? answer.json?.["user"] : undefined;
+                if (!user || (typeof user["id"] !== "string" && typeof user["id"] !== "number"))
+                    return undefined;
+                return {
+                    id: String(user["id"]),
+                    ...(typeof user["name"] === "string" && user["name"] ? { name: user["name"] } : {}),
+                    ...(typeof user["email"] === "string" && user["email"] ? { email: user["email"] } : {}),
+                };
+            }
+            catch {
+                return undefined;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+        async signInSocial(provider, callbackURL, errorCallbackURL = callbackURL) {
+            const answer = await post("/sign-in/social", { provider, callbackURL, errorCallbackURL });
+            const url = answer.json?.["url"];
+            return answer.ok && typeof url === "string" ? { url } : errorOf(answer);
+        },
+        async signOut() {
+            const answer = await post("/sign-out", {});
+            return answer.ok ? { signedOut: true } : errorOf(answer);
+        },
+        async addPasskey(name) {
+            const options = await call("/passkey/generate-register-options");
+            if (!options.ok)
+                return errorOf(options);
+            let response;
+            try {
+                response = await (await webauthn()).startRegistration({ optionsJSON: options.json });
+            }
+            catch (error) {
+                return { error: `the passkey was not made: ${error.message}` };
+            }
+            const answer = await post("/passkey/verify-registration", { response, name });
+            return answer.ok ? { added: true, name } : errorOf(answer);
+        },
+        async signInWithPasskey() {
+            const options = await call("/passkey/generate-authenticate-options");
+            if (!options.ok)
+                return errorOf(options);
+            let response;
+            try {
+                response = await (await webauthn()).startAuthentication({ optionsJSON: options.json });
+            }
+            catch (error) {
+                return { error: `no passkey was used: ${error.message}` };
+            }
+            const answer = await post("/passkey/verify-authentication", { response });
+            return answer.ok ? { signedIn: true } : errorOf(answer);
+        },
+        async signInWithPassword({ email, password, name, signUp }) {
+            const path = signUp ? "/sign-up/email" : "/sign-in/email";
+            const answer = await post(path, { email, password, ...(signUp ? { name: name || email.split("@")[0] } : {}) });
+            if (!answer.ok)
+                return errorOf(answer);
+            const user = answer.json?.["user"];
+            return { signedIn: true, ...(user && typeof user["id"] === "string" ? { user: user["id"] } : {}) };
+        },
+    };
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/better-auth",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Better Auth for a procedures server: the sign-in with GitHub, Google and passkeys over MongoDB, and a request hook that gives the principal of a session or of an agent token.",
   "keywords": [
     "procedures",
@@ -30,6 +30,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
     }
   },
   "files": [
@@ -49,7 +53,8 @@
   "client": null,
   "dependencies": {
     "@better-auth/passkey": "^1.7.10",
-    "@procedures/client": "0.13.0",
+    "@procedures/client": "0.13.1",
+    "@simplewebauthn/browser": "^13.3.0",
     "better-auth": "^1.7.10",
     "zod": "^4.6.5"
   },

package/src/browser.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { createBrowserAuth, type WebAuthnCeremonies } from "./browser.js";
+
+interface Sent {
+  url: string;
+  method: string;
+  credentials: string | undefined;
+  body: unknown;
+}
+
+/** A fetch that answers from a table of path → [status, body], and records each call. */
+function fakeServer(routes: Record<string, [number, unknown]>) {
+  const sent: Sent[] = [];
+  const fetch = (async (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
+    const url = String(input);
+    sent.push({ url, method: init?.method ?? "GET", credentials: init?.credentials, body: init?.body ? JSON.parse(String(init.body)) : undefined });
+    const path = url.replace(/^https:\/\/api\.example\.com\/auth/, "");
+    const [status, body] = routes[path] ?? [404, { message: "no such route" }];
+    return new Response(body === undefined ? null : JSON.stringify(body), { status });
+  }) as typeof globalThis.fetch;
+  return { fetch, sent };
+}
+
+const ceremonies = (fail = false): WebAuthnCeremonies => ({
+  startRegistration: async () => {
+    if (fail) throw new Error("the user cancelled");
+    return { id: "credential" };
+  },
+  startAuthentication: async () => {
+    if (fail) throw new Error("the user cancelled");
+    return { id: "assertion" };
+  },
+});
+
+describe("createBrowserAuth", () => {
+  it("reads the user of the session, with the cookies, and undefined when signed out or on an error", async () => {
+    const server = fakeServer({ "/get-session": [200, { user: { id: "u1", name: "Ana", email: "ana@example.com" }, session: {} }] });
+    const auth = createBrowserAuth({ baseURL: "https://api.example.com/", fetch: server.fetch });
+    expect(await auth.session()).toEqual({ id: "u1", name: "Ana", email: "ana@example.com" });
+    expect(server.sent[0]).toMatchObject({ url: "https://api.example.com/auth/get-session", credentials: "include" });
+    expect(await createBrowserAuth({ baseURL: "https://api.example.com", fetch: fakeServer({ "/get-session": [200, null] }).fetch }).session()).toBeUndefined();
+    const broken = (async () => { throw new Error("offline"); }) as typeof fetch;
+    expect(await createBrowserAuth({ baseURL: "https://api.example.com", fetch: broken }).session()).toBeUndefined();
+  });
+
+  it("gives the page of a provider, or the error of the server", async () => {
+    const server = fakeServer({ "/sign-in/social": [200, { url: "https://github.com/login/oauth" }] });
+    const auth = createBrowserAuth({ baseURL: "https://api.example.com", fetch: server.fetch });
+    expect(await auth.signInSocial("github", "https://app.example.com/board")).toEqual({ url: "https://github.com/login/oauth" });
+    expect(server.sent[0]).toMatchObject({ method: "POST", body: { provider: "github", callbackURL: "https://app.example.com/board", errorCallbackURL: "https://app.example.com/board" } });
+    const refused = createBrowserAuth({ baseURL: "https://api.example.com", fetch: fakeServer({ "/sign-in/social": [400, { message: "unknown provider" }] }).fetch });
+    expect(await refused.signInSocial("x", "https://app.example.com")).toEqual({ error: "unknown provider" });
+  });
+
+  it("signs out, and gives the HTTP status when the server gives no message", async () => {
+    expect(await createBrowserAuth({ baseURL: "https://api.example.com", fetch: fakeServer({ "/sign-out": [200, { success: true }] }).fetch }).signOut()).toEqual({ signedOut: true });
+    expect(await createBrowserAuth({ baseURL: "https://api.example.com", fetch: fakeServer({ "/sign-out": [500, undefined] }).fetch }).signOut()).toEqual({ error: "HTTP 500" });
+  });
+
+  it("makes a passkey: the options, the ceremony, then the verification with the name", async () => {
+    const server = fakeServer({ "/passkey/generate-register-options": [200, { challenge: "c" }], "/passkey/verify-registration": [200, { ok: true }] });
+    const auth = createBrowserAuth({ baseURL: "https://api.example.com", fetch: server.fetch, webauthn: ceremonies() });
+    expect(await auth.addPasskey("My laptop")).toEqual({ added: true, name: "My laptop" });
+    expect(server.sent.map((s) => s.url.split("/auth")[1])).toEqual(["/passkey/generate-register-options", "/passkey/verify-registration"]);
+    expect(server.sent[1]!.body).toEqual({ response: { id: "credential" }, name: "My laptop" });
+  });
+
+  it("signs in with a passkey, and reports a cancelled ceremony without a verification", async () => {
+    const routes: Record<string, [number, unknown]> = { "/passkey/generate-authenticate-options": [200, { challenge: "c" }], "/passkey/verify-authentication": [200, { ok: true }] };
+    expect(await createBrowserAuth({ baseURL: "https://api.example.com", fetch: fakeServer(routes).fetch, webauthn: ceremonies() }).signInWithPasskey()).toEqual({ signedIn: true });
+    const server = fakeServer(routes);
+    const out = await createBrowserAuth({ baseURL: "https://api.example.com", fetch: server.fetch, webauthn: ceremonies(true) }).signInWithPasskey();
+    expect(out).toEqual({ error: "no passkey was used: the user cancelled" });
+    expect(server.sent).toHaveLength(1);
+  });
+
+  it("signs up and signs in with a password on a test server, with a name from the email", async () => {
+    const server = fakeServer({ "/sign-up/email": [200, { user: { id: "u2" } }], "/sign-in/email": [401, { message: "invalid password" }] });
+    const auth = createBrowserAuth({ baseURL: "https://api.example.com", fetch: server.fetch });
+    expect(await auth.signInWithPassword({ email: "bo@example.com", password: "pw", signUp: true })).toEqual({ signedIn: true, user: "u2" });
+    expect(server.sent[0]!.body).toEqual({ email: "bo@example.com", password: "pw", name: "bo" });
+    expect(await auth.signInWithPassword({ email: "bo@example.com", password: "bad" })).toEqual({ error: "invalid password" });
+  });
+
+  it("takes another base path", async () => {
+    const server = fakeServer({});
+    await createBrowserAuth({ baseURL: "", basePath: "/api/auth", fetch: server.fetch }).signOut();
+    expect(server.sent[0]!.url).toBe("/api/auth/sign-out");
+  });
+});

package/src/browser.ts

@@ -0,0 +1,172 @@
+/**
+ * The browser half of the sign-in (Graph's split, wave 2, W8): the calls of a page to the auth routes of a
+ * procedures server with Better Auth. This entry has no framework and no global state: each function gives data,
+ * and the app decides what the page does (a redirect, a reload).
+ *
+ * - The session cookie is `httpOnly`, so each call sends the cookies (`credentials: "include"`).
+ * - The passkeys use WebAuthn through `@simplewebauthn/browser`. It loads only when a passkey function runs.
+ * - The functions give `{ error }` for a refused or failed call. They do not throw for an answer of the server.
+ *
+ * Import it as `@procedures/better-auth/browser`. The package root is for the server.
+ */
+
+/** A signed-in user, as the session route gives it. */
+export interface BrowserUser {
+  readonly id: string;
+  readonly name?: string | undefined;
+  readonly email?: string | undefined;
+}
+
+/** A refused or failed call. */
+export interface BrowserAuthError {
+  readonly error: string;
+}
+
+/** The WebAuthn ceremonies. The default is `@simplewebauthn/browser`. A test gives its own. */
+export interface WebAuthnCeremonies {
+  startRegistration(options: { optionsJSON: unknown }): Promise<unknown>;
+  startAuthentication(options: { optionsJSON: unknown }): Promise<unknown>;
+}
+
+/** The options of `createBrowserAuth`. */
+export interface BrowserAuthOptions {
+  /**
+   * The origin of the server. An empty text is the origin of the page, the simplest form. A server on another
+   * origin needs CORS with credentials for the origin of the page (refer to the README).
+   */
+  readonly baseURL: string;
+  /** The path of the auth routes. The default is `/auth`, as `betterAuthConfig` gives it. */
+  readonly basePath?: string | undefined;
+  /** The fetch of the calls. The default is the fetch of the page. */
+  readonly fetch?: typeof fetch | undefined;
+  /** The WebAuthn ceremonies of the passkeys. */
+  readonly webauthn?: WebAuthnCeremonies | undefined;
+  /** The longest wait of `session()`, in milliseconds. The default is 4000. */
+  readonly sessionTimeoutMs?: number | undefined;
+}
+
+/** The sign-in calls of a page. */
+export interface BrowserAuth {
+  /** The signed-in user of this browser, or undefined (signed out, or the server did not answer in time). */
+  session(): Promise<BrowserUser | undefined>;
+  /** The page of the provider: the app goes to `url`. After the sign-in, the provider comes back to `callbackURL`. */
+  signInSocial(provider: string, callbackURL: string, errorCallbackURL?: string): Promise<{ readonly url: string } | BrowserAuthError>;
+  /** This method ends the session. The app then loads the page again. */
+  signOut(): Promise<{ readonly signedOut: true } | BrowserAuthError>;
+  /** This method makes a passkey of this device for the signed-in user. */
+  addPasskey(name: string): Promise<{ readonly added: true; readonly name: string } | BrowserAuthError>;
+  /** This method signs in with a passkey of this device. The app then loads the page again. */
+  signInWithPasskey(): Promise<{ readonly signedIn: true } | BrowserAuthError>;
+  /** A test server only (`AUTH_TEST_ACCOUNTS`): a sign-in, or a sign-up, with an email and a password. */
+  signInWithPassword(input: { email: string; password: string; name?: string | undefined; signUp?: boolean | undefined }): Promise<{ readonly signedIn: true; readonly user?: string | undefined } | BrowserAuthError>;
+}
+
+interface Answer {
+  ok: boolean;
+  status: number;
+  json: Record<string, unknown> | undefined;
+}
+
+const errorOf = (answer: Answer): BrowserAuthError => ({
+  error: typeof answer.json?.["message"] === "string" ? answer.json["message"] : `HTTP ${answer.status}`,
+});
+
+/**
+ * This function gives the sign-in calls of a page to a server.
+ *
+ * @example
+ * ```ts
+ * const auth = createBrowserAuth({ baseURL: "https://api.example.com" });
+ * const user = await auth.session();
+ * const out = await auth.signInSocial("github", location.href);
+ * if ("url" in out) location.assign(out.url);
+ * ```
+ */
+export function createBrowserAuth(options: BrowserAuthOptions): BrowserAuth {
+  const base = `${options.baseURL.replace(/\/+$/, "")}${options.basePath ?? "/auth"}`;
+  const doFetch = options.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args));
+  const timeoutMs = options.sessionTimeoutMs ?? 4000;
+  let ceremonies: Promise<WebAuthnCeremonies> | undefined;
+  const webauthn = (): Promise<WebAuthnCeremonies> =>
+    (ceremonies ??= options.webauthn ? Promise.resolve(options.webauthn) : import("@simplewebauthn/browser") as Promise<WebAuthnCeremonies>);
+
+  const call = async (path: string, init: RequestInit = {}): Promise<Answer> => {
+    const response = await doFetch(`${base}${path}`, { credentials: "include", ...init });
+    let json: Record<string, unknown> | undefined;
+    try {
+      const body: unknown = await response.json();
+      json = body !== null && typeof body === "object" ? (body as Record<string, unknown>) : undefined;
+    } catch {
+      json = undefined;
+    }
+    return { ok: response.ok, status: response.status, json };
+  };
+  const post = (path: string, body: unknown): Promise<Answer> =>
+    call(path, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body ?? {}) });
+
+  return {
+    async session() {
+      const abort = new AbortController();
+      const timer = setTimeout(() => abort.abort(), timeoutMs);
+      try {
+        const answer = await call("/get-session", { signal: abort.signal });
+        const user = answer.ok ? (answer.json?.["user"] as Record<string, unknown> | undefined) : undefined;
+        if (!user || (typeof user["id"] !== "string" && typeof user["id"] !== "number")) return undefined;
+        return {
+          id: String(user["id"]),
+          ...(typeof user["name"] === "string" && user["name"] ? { name: user["name"] } : {}),
+          ...(typeof user["email"] === "string" && user["email"] ? { email: user["email"] } : {}),
+        };
+      } catch {
+        return undefined;
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+
+    async signInSocial(provider, callbackURL, errorCallbackURL = callbackURL) {
+      const answer = await post("/sign-in/social", { provider, callbackURL, errorCallbackURL });
+      const url = answer.json?.["url"];
+      return answer.ok && typeof url === "string" ? { url } : errorOf(answer);
+    },
+
+    async signOut() {
+      const answer = await post("/sign-out", {});
+      return answer.ok ? { signedOut: true as const } : errorOf(answer);
+    },
+
+    async addPasskey(name) {
+      const options = await call("/passkey/generate-register-options");
+      if (!options.ok) return errorOf(options);
+      let response: unknown;
+      try {
+        response = await (await webauthn()).startRegistration({ optionsJSON: options.json });
+      } catch (error) {
+        return { error: `the passkey was not made: ${(error as Error).message}` };
+      }
+      const answer = await post("/passkey/verify-registration", { response, name });
+      return answer.ok ? { added: true as const, name } : errorOf(answer);
+    },
+
+    async signInWithPasskey() {
+      const options = await call("/passkey/generate-authenticate-options");
+      if (!options.ok) return errorOf(options);
+      let response: unknown;
+      try {
+        response = await (await webauthn()).startAuthentication({ optionsJSON: options.json });
+      } catch (error) {
+        return { error: `no passkey was used: ${(error as Error).message}` };
+      }
+      const answer = await post("/passkey/verify-authentication", { response });
+      return answer.ok ? { signedIn: true as const } : errorOf(answer);
+    },
+
+    async signInWithPassword({ email, password, name, signUp }) {
+      const path = signUp ? "/sign-up/email" : "/sign-in/email";
+      const answer = await post(path, { email, password, ...(signUp ? { name: name || email.split("@")[0] } : {}) });
+      if (!answer.ok) return errorOf(answer);
+      const user = answer.json?.["user"] as Record<string, unknown> | undefined;
+      return { signedIn: true as const, ...(user && typeof user["id"] === "string" ? { user: user["id"] } : {}) };
+    },
+  };
+}