@astralarium/repo-auth 0.0.0-stage → 0.2.0

package/dist/client.js

@@ -0,0 +1,203 @@
+/** Browser half of shell-auth: the session store, auth calls and OAuth popups. */
+import { log } from "@astralarium/repo-telemetry";
+import { getGlobalBroadcastChannel } from "better-auth/client";
+import { InferServerPlugin } from "better-auth/client/plugins";
+import { createAuthClient } from "better-auth/react";
+/**
+ * Posts Better Auth's session broadcast: every other tab refetches its
+ * session. Better Auth posts it itself on sign-out and user updates. The
+ * posting tab refetches on its own.
+ */
+function broadcastSession() {
+  getGlobalBroadcastChannel().post({
+    event: "session",
+    data: {
+      trigger: "getSession"
+    },
+    clientId: crypto.randomUUID()
+  });
+}
+/** Opens `url`, a page starting a provider's OAuth redirect, in a popup
+ *  centered over this window. */
+export function openAuthPopup(url) {
+  const width = Math.min(400, screen.availWidth * 0.8, window.innerWidth);
+  const height = Math.min(600, screen.availHeight * 0.8, window.innerHeight);
+  const left = window.screenLeft + (window.innerWidth - width) / 2;
+  const top = window.screenTop + (window.innerHeight - height) / 2;
+  window.open(url, "_blank", `popup,width=${width},height=${height},left=${left},top=${top}`);
+}
+/** Ends an OAuth popup on its landing page: the other tabs, opener
+ *  included, refresh their session; the popup closes. */
+export function finishAuthPopup() {
+  broadcastSession();
+  window.close();
+}
+/** The error redirect's params in `search`; non-string values drop. */
+export function parseAuthErrorSearch(search) {
+  const {
+    error,
+    error_description
+  } = search;
+  return {
+    ...(typeof error === "string" ? {
+      error
+    } : {}),
+    ...(typeof error_description === "string" ? {
+      error_description
+    } : {})
+  };
+}
+/** A response that started a session: Better Auth answers sign-in and
+ *  sign-up with the new session's `token` and its `user`. */
+function startsSession(data) {
+  return typeof data === "object" && data !== null && "token" in data && typeof data.token === "string" && "user" in data && typeof data.user === "object" && data.user !== null;
+}
+/** Broadcasts after a request starts a session. Better Auth's own
+ *  listener refetches this tab; this one tells the others. */
+const sessionBroadcast = {
+  id: "session-broadcast",
+  fetchPlugins: [{
+    id: "session-broadcast",
+    name: "session-broadcast",
+    hooks: {
+      onSuccess({
+        data
+      }) {
+        if (startsSession(data)) broadcastSession();
+      }
+    }
+  }]
+};
+/** Shared live session store and auth operations for `Auth`. */
+export function createShellAuthClient() {
+  const authClient = createAuthClient({
+    plugins: [InferServerPlugin(), sessionBroadcast],
+    sessionOptions: {
+      refetchOnWindowFocus: true,
+      refetchWhenOffline: false
+    }
+  });
+  /** The client's live session. */
+  const sessionStore = authClient.$store.atoms.session;
+  /** Seeds the store with the page's dehydrated session. Better Auth types
+   *  the seed with the base user merged in; the projection omits those
+   *  fields. */
+  function hydrateSession(data) {
+    authClient.hydrateSession(data);
+  }
+  /**
+   * Reads the session fresh after a change made outside the auth client
+   * (a server function updating the user): past the cookie cache in this
+   * tab, then broadcast to the others.
+   */
+  async function refreshSession() {
+    await sessionStore.get().refetch({
+      query: {
+        disableCookieCache: true
+      }
+    });
+    broadcastSession();
+  }
+  /** The signed-in user's id, `null` signed out; `undefined` while the
+   *  store awaits its first read. */
+  function readUserId() {
+    const {
+      data,
+      isPending
+    } = sessionStore.get();
+    return isPending ? undefined : data?.user.id ?? null;
+  }
+  /**
+   * Seeds the store with the page's `session` (`null` signed out), then
+   * calls `onChange` whenever the signed-in user changes: sign-in,
+   * sign-out, account switch, from this tab or another. An `undefined`
+   * session leaves the store unseeded; its first read sets the user. The
+   * seed and that first read fire nothing. Returns the unsubscribe.
+   */
+  function watchSession(session, onChange) {
+    if (session !== undefined) hydrateSession(session);
+    let userId = session === undefined ? readUserId() : session?.user.id ?? null;
+    return sessionStore.listen(() => {
+      const next = readUserId();
+      if (next === undefined || next === userId) return;
+      const known = userId !== undefined;
+      userId = next;
+      if (known) onChange();
+    });
+  }
+  /**
+   * Watches the signed-in user from the first loaded page under `routeId`,
+   * the layout route carrying `viewerRouteContext`; other pages read no
+   * session. A server-rendered page's session seeds the watch; one reached
+   * by client navigation carries none, and the store's first read sets the
+   * user. Each user change after clears `queryClient`'s queries and
+   * invalidates `router`, both holding the previous user's data; the
+   * route loaders refetch the queries they read, then the active queries
+   * still unread refetch: one fetch per query. Returns the unsubscribe.
+   */
+  function watchViewerRouter(router, queryClient, routeId) {
+    let stop = router.subscribe("onLoad", () => {
+      const match = router.state.matches.find(route => route.routeId === routeId);
+      if (!match) return;
+      stop();
+      const {
+        session
+      } = match.context;
+      stop = watchSession(session, () => {
+        for (const query of queryClient.getQueryCache().getAll()) query.reset();
+        const failed = exception => log.warn("auth.viewer_reload_failed", "Reloading the page for a new viewer failed", {
+          exception
+        });
+        void router.invalidate().catch(failed).then(() => queryClient.refetchQueries({
+          type: "active",
+          predicate: ({
+            state
+          }) => state.status === "pending" && state.fetchStatus === "idle"
+        })).catch(failed);
+      });
+    });
+    return () => stop();
+  }
+  /** POSTs `body` to the auth endpoint at `path`, a form with `form`;
+   *  resolves to its error. Endpoint methods (`signIn.social`) type per
+   *  app, unresolved here; plugin endpoints (`devProviderSignIn`) call
+   *  through it. */
+  async function post(path, body, {
+    form = false
+  } = {}) {
+    const {
+      error
+    } = await authClient.$fetch(path, {
+      method: "POST",
+      body,
+      ...(form && {
+        headers: {
+          "content-type": "application/x-www-form-urlencoded"
+        }
+      })
+    });
+    return error ?? undefined;
+  }
+  /** Starts `provider`'s OAuth redirect, landing on `callbackURL`.
+   *  Resolves to the failure detail when the redirect fails to start. */
+  async function signInWithProvider(provider, callbackURL) {
+    try {
+      const error = await post("/sign-in/social", {
+        provider,
+        callbackURL
+      });
+      return error ? error.message ?? error.statusText : undefined;
+    } catch (cause) {
+      return cause instanceof Error ? cause.message : String(cause);
+    }
+  }
+  return {
+    authClient,
+    sessionStore,
+    refreshSession,
+    watchSession,
+    watchViewerRouter,
+    post,
+    signInWithProvider
+  };
+}

package/dist/dev-sign-in/client.d.ts

@@ -0,0 +1,21 @@
+/** Dev builds' browser sign-in as provider accounts. */
+import type { createShellAuthClient } from "../client.ts";
+/** What dev sign-in calls of a shell auth client
+ *  (`createShellAuthClient`). */
+export interface DevSignInClient {
+    post: ReturnType<typeof createShellAuthClient>["post"];
+    sessionStore: {
+        get(): {
+            refetch(): Promise<unknown>;
+        };
+    };
+}
+/** Signs in through `client`'s dev sign-in (`devProviderSignIn`) as the
+ *  provider account `accountId`, then reads the new session in this tab:
+ *  `post` skips Better Auth's session signal; `sessionBroadcast` tells the
+ *  others. Resolves to the error when sign-in fails. */
+export declare function signInWithDevAccount({ post, sessionStore }: DevSignInClient, accountId: string): Promise<{
+    message?: string | undefined;
+    status: number;
+    statusText: string;
+} | undefined>;

package/dist/dev-sign-in/client.js

@@ -0,0 +1,17 @@
+import { DEV_SIGN_IN_ENDPOINT } from "./endpoint.js";
+/** Signs in through `client`'s dev sign-in (`devProviderSignIn`) as the
+ *  provider account `accountId`, then reads the new session in this tab:
+ *  `post` skips Better Auth's session signal; `sessionBroadcast` tells the
+ *  others. Resolves to the error when sign-in fails. */
+export async function signInWithDevAccount({
+  post,
+  sessionStore
+}, accountId) {
+  const error = await post(DEV_SIGN_IN_ENDPOINT, {
+    accountId
+  }, {
+    form: true
+  });
+  if (!error) await sessionStore.get().refetch();
+  return error;
+}

package/dist/dev-sign-in/endpoint.d.ts

@@ -0,0 +1,2 @@
+/** Dev sign-in's endpoint under `AUTH_BASE_PATH`. */
+export declare const DEV_SIGN_IN_ENDPOINT = "/dev/sign-in";

package/dist/dev-sign-in/endpoint.js

@@ -0,0 +1,2 @@
+/** Dev sign-in's endpoint under `AUTH_BASE_PATH`. */
+export const DEV_SIGN_IN_ENDPOINT = "/dev/sign-in";

package/dist/dev-sign-in/index.d.ts

@@ -0,0 +1,4 @@
+/** Dev builds' sign-in as provider accounts, and provider accounts
+ *  resolved to users for seeds. */
+export { type ContextAuth, ensureProviderUser, type ProviderUser, } from "./provider-user.ts";
+export { type DevProviderSignIn, devProviderSignIn, type DevProviderSignInOptions, isDevSignIn, } from "./sign-in.ts";

package/dist/dev-sign-in/index.js

@@ -0,0 +1,4 @@
+/** Dev builds' sign-in as provider accounts, and provider accounts
+ *  resolved to users for seeds. */
+export { ensureProviderUser } from "./provider-user.js";
+export { devProviderSignIn, isDevSignIn } from "./sign-in.js";

package/dist/dev-sign-in/provider-user.d.ts

@@ -0,0 +1,30 @@
+/** Provider accounts resolved to users through better-auth's adapter. */
+import type { AuthContext } from "better-auth";
+/** A provider account and the user it creates when new. */
+export interface ProviderUser {
+    /** Provider id (`google`, `github`). */
+    providerId: string;
+    /** The provider's account id. */
+    accountId: string;
+    /** Name of a new user. */
+    name: string;
+    /** Email of a new user; a user holding it gains the account. */
+    email: string;
+}
+/** What a dev sign-in function reads of an auth instance: its context's
+ *  `Keys`; `ensureProviderUser` reads `internalAdapter`. */
+export interface ContextAuth<Keys extends keyof AuthContext = "internalAdapter"> {
+    $context: Promise<Pick<AuthContext, Keys>>;
+}
+/**
+ * The id of the user owning `providerId` account `accountId`, else of the
+ * user holding `email`, else of a new user (`name`, verified `email`); the
+ * latter two gain a token-less account. `email` must be trusted (the
+ * account's own claim): its holder gains the account. Rows go through
+ * better-auth's adapter, so the app's `databaseHooks` run. Concurrent
+ * calls for one new account resolve to one user. Queries run inside
+ * `withShellAuth`. Seeds call it outside any request: better-auth's
+ * `handleOAuthUserInfo`, which dev sign-in uses, takes an endpoint context
+ * and creates a session.
+ */
+export declare function ensureProviderUser(auth: ContextAuth, { providerId, accountId, name, email }: ProviderUser): Promise<string>;

package/dist/dev-sign-in/provider-user.js

@@ -0,0 +1,55 @@
+/**
+ * The id of the user owning `providerId` account `accountId`, else of the
+ * user holding `email`, else of a new user (`name`, verified `email`); the
+ * latter two gain a token-less account. `email` must be trusted (the
+ * account's own claim): its holder gains the account. Rows go through
+ * better-auth's adapter, so the app's `databaseHooks` run. Concurrent
+ * calls for one new account resolve to one user. Queries run inside
+ * `withShellAuth`. Seeds call it outside any request: better-auth's
+ * `handleOAuthUserInfo`, which dev sign-in uses, takes an endpoint context
+ * and creates a session.
+ */
+export async function ensureProviderUser(auth, {
+  providerId,
+  accountId,
+  name,
+  email
+}) {
+  const {
+    internalAdapter
+  } = await auth.$context;
+  const owner = () => internalAdapter.findAccountOwnerByKey({
+    providerId,
+    accountId
+  }).then(found => found?.kind === "owned" ? found.user.id : undefined);
+  const existing = await owner();
+  if (existing) return existing;
+  try {
+    const holder = await internalAdapter.findUserByEmail(email);
+    if (holder) {
+      await internalAdapter.linkAccount({
+        userId: holder.user.id,
+        providerId,
+        accountId
+      });
+      return holder.user.id;
+    }
+    const {
+      user
+    } = await internalAdapter.createOAuthUser({
+      name,
+      email,
+      emailVerified: true
+    }, {
+      providerId,
+      accountId
+    });
+    return user.id;
+  } catch (error) {
+    // A concurrent call created the account first: the unique account or
+    // email index rejected this one. A failed re-read leaves `error`.
+    const winner = await owner().catch(() => undefined);
+    if (winner) return winner;
+    throw error;
+  }
+}

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

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import type { ContextAuth } from "./provider-user.ts";
+/** Dev sign-in's provider and its accounts: `devProviderSignIn`'s options. */
+export interface DevProviderSignInOptions {
+    /** Provider id the signed-in accounts belong to. */
+    provider: string;
+    /** Valid account ids; others answer 400. Default: any non-empty id. */
+    accountId?: z.ZodType<string>;
+    /** Name and email of a new account's user. */
+    newUser: (accountId: string) => {
+        name: string;
+        email: string;
+    };
+}
+/**
+ * better-auth plugin for dev builds, `ShellAuthApp.devSignIn`: `POST
+ * /dev/sign-in` with form field `accountId` signs in as that `provider`
+ * account through better-auth's OAuth sign-in (`handleOAuthUserInfo`): its
+ * owner, else the user holding `newUser`'s email under the app's account
+ * linking, else a new user (`newUser`, verified email); new accounts hold
+ * no tokens, stored tokens stay. Requests from a better-auth trusted origin
+ * only (`isTrustedOrigin`: the base URL, allowed hosts, `trustedOrigins`);
+ * others and a missing `Origin` answer 403; a refused sign-in answers 401.
+ * better-auth sets the session cookies, plus a marker cookie holding the
+ * session id signed like the session token (`isDevSignIn`), expiring at
+ * the session's sign-in expiry. Answers the session's `token` and `user`
+ * id.
+ */
+export declare function devProviderSignIn({ provider, accountId, newUser, }: DevProviderSignInOptions): {
+    id: "dev-provider-sign-in";
+    endpoints: {
+        devProviderSignIn: import("better-auth").StrictEndpoint<"/dev/sign-in", {
+            method: "POST";
+            body: z.ZodObject<{
+                accountId: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+            }, z.core.$strip>;
+            requireRequest: true;
+            metadata: {
+                allowedMediaTypes: string[];
+            };
+        }, {
+            token: string;
+            user: {
+                id: string;
+            };
+        }>;
+    };
+};
+/** The dev sign-in plugin `devProviderSignIn` builds. */
+export type DevProviderSignIn = ReturnType<typeof devProviderSignIn>;
+/**
+ * Whether `headers` carry `auth`'s marker cookie holding `session`'s id
+ * signed with `auth`'s secret: the auth server signed that id, as dev
+ * sign-in does for each session it creates. The marker's name follows
+ * `auth`'s cookie naming (prefix, `__Secure-` on HTTPS). False past the
+ * marker's sign-in expiry, while an extended session lives on.
+ */
+export declare function isDevSignIn(auth: ContextAuth<"createAuthCookie" | "secret">, headers: Headers, session: {
+    session: {
+        id: string;
+    };
+} | null): Promise<boolean>;

package/dist/dev-sign-in/sign-in.js

@@ -0,0 +1,116 @@
+import { APIError, createAuthEndpoint } from "better-auth/api";
+import { parseCookies, setSessionCookie } from "better-auth/cookies";
+import { constantTimeEqual, makeSignature } from "better-auth/crypto";
+import { handleOAuthUserInfo } from "better-auth/oauth2";
+import { z } from "zod";
+import { DEV_SIGN_IN_ENDPOINT } from "./endpoint.js";
+/** better-auth cookie holding the id of the session dev sign-in created,
+ *  signed with the auth secret. Its lifetime is fixed at sign-in to the
+ *  session's `expiresIn`; a session extended on refresh (`updateAge`)
+ *  outlives it. */
+const MARKER = "dev_sign_in";
+/**
+ * better-auth plugin for dev builds, `ShellAuthApp.devSignIn`: `POST
+ * /dev/sign-in` with form field `accountId` signs in as that `provider`
+ * account through better-auth's OAuth sign-in (`handleOAuthUserInfo`): its
+ * owner, else the user holding `newUser`'s email under the app's account
+ * linking, else a new user (`newUser`, verified email); new accounts hold
+ * no tokens, stored tokens stay. Requests from a better-auth trusted origin
+ * only (`isTrustedOrigin`: the base URL, allowed hosts, `trustedOrigins`);
+ * others and a missing `Origin` answer 403; a refused sign-in answers 401.
+ * better-auth sets the session cookies, plus a marker cookie holding the
+ * session id signed like the session token (`isDevSignIn`), expiring at
+ * the session's sign-in expiry. Answers the session's `token` and `user`
+ * id.
+ */
+export function devProviderSignIn({
+  provider,
+  accountId = z.string().min(1),
+  newUser
+}) {
+  return {
+    id: "dev-provider-sign-in",
+    endpoints: {
+      devProviderSignIn: createAuthEndpoint(DEV_SIGN_IN_ENDPOINT, {
+        method: "POST",
+        body: z.object({
+          accountId
+        }),
+        requireRequest: true,
+        metadata: {
+          allowedMediaTypes: ["application/x-www-form-urlencoded"]
+        }
+      }, async ctx => {
+        const {
+          request,
+          context
+        } = ctx;
+        const origin = request.headers.get("origin");
+        if (!origin || !context.isTrustedOrigin(origin)) throw APIError.fromStatus("FORBIDDEN", {
+          message: "Untrusted origin sign-in forbidden."
+        });
+        const id = ctx.body.accountId;
+        const signIn = () => handleOAuthUserInfo(ctx, {
+          userInfo: {
+            id,
+            ...newUser(id),
+            emailVerified: true
+          },
+          account: {
+            providerId: provider,
+            accountId: id
+          }
+        });
+        const first = await signIn();
+        // A concurrent sign-in as the same new account fails this one's
+        // create; the retry signs in as the winner's user.
+        const {
+          data,
+          error
+        } = first.data ? first : await signIn();
+        if (!data) throw APIError.fromStatus("UNAUTHORIZED", {
+          message: error
+        });
+        const {
+          session,
+          user
+        } = data;
+        await setSessionCookie(ctx, {
+          session,
+          user
+        });
+        const marker = context.createAuthCookie(MARKER);
+        await ctx.setSignedCookie(marker.name, session.id, context.secret, {
+          ...marker.attributes,
+          maxAge: context.sessionConfig.expiresIn
+        });
+        return ctx.json({
+          token: session.token,
+          user: {
+            id: user.id
+          }
+        });
+      })
+    }
+  };
+}
+/**
+ * Whether `headers` carry `auth`'s marker cookie holding `session`'s id
+ * signed with `auth`'s secret: the auth server signed that id, as dev
+ * sign-in does for each session it creates. The marker's name follows
+ * `auth`'s cookie naming (prefix, `__Secure-` on HTTPS). False past the
+ * marker's sign-in expiry, while an extended session lives on.
+ */
+export async function isDevSignIn(auth, headers, session) {
+  if (!session) return false;
+  const {
+    createAuthCookie,
+    secret
+  } = await auth.$context;
+  const value = parseCookies(headers.get("cookie") ?? "").get(createAuthCookie(MARKER).name);
+  if (value === undefined) return false;
+  const {
+    id
+  } = session.session;
+  return constantTimeEqual(value, `${id}.${await makeSignature(id, secret)}`);
+}