@sjolystinnovation/app-kit 0.4.0 → 0.6.0

package/src/auth/createAuthOptions.ts

@@ -0,0 +1,313 @@
+import axios, { type AxiosInstance } from "axios";
+import jwt from "jsonwebtoken";
+import type { NextAuthOptions, Session, User } from "next-auth";
+import CredentialsProvider from "next-auth/providers/credentials";
+import type { JWT } from "next-auth/jwt";
+import { resolveJwtSecret, type SessionConfig } from "../config";
+import { SESSION_ERRORS, SIGN_IN_ERRORS, isTerminalSessionError } from "../session/expiry";
+
+/** The signed-in user, as the session carries it. */
+export interface SessionUser {
+  id: string;
+  name: string;
+  email: string;
+  roles: string[];
+}
+
+interface TokenPair {
+  token: string;
+  refreshToken: string;
+}
+
+interface ApiClaims {
+  sub: string;
+  unique_name: string;
+  role?: string | string[];
+  exp: number;
+  iat: number;
+}
+
+// The fields this module stores in next-auth's JWT. An intersection still compiles when the app
+// declares the same fields itself.
+type AppToken = JWT & {
+  accessToken?: string;
+  refreshToken?: string;
+  refreshAt?: number;
+  loginAt?: number;
+  user?: SessionUser;
+  error?: string;
+};
+
+interface AuthorizedUser extends User {
+  roles: string[];
+  accessToken: string;
+  refreshToken: string;
+}
+
+export type AuthOptionsSettings = {
+  /** The server environment, usually `process.env`. It holds the API JWT secret. */
+  env: Record<string, string | undefined>;
+} & (
+  | {
+      /** Base URL of the API, such as `https://api.example.com/api`. */
+      apiUrl: string;
+      http?: never;
+    }
+  | {
+      /** An HTTP client with its own base URL, for tests. */
+      http: AxiosInstance;
+      apiUrl?: never;
+    }
+);
+
+const ABSOLUTE_SESSION_MAX_AGE = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+// Refresh ahead of expiry, so the token is still fresh when the user saves.
+const MAX_REFRESH_SKEW_MS = 5 * 60 * 1000;
+
+// The soonest a refresh can be due. The floor stops a short-lived token from refreshing on every
+// session read.
+const MIN_REFRESH_GAP_MS = 30 * 1000;
+
+// How long a refresh result is remembered. It is also the wait before a failed refresh is retried.
+const REMEMBER_ROTATION_MS = 60 * 1000;
+
+// How far this server's clock may differ from the API's when a token's times are checked.
+const CLOCK_TOLERANCE_S = 60;
+
+// Sign-in and session reads wait for the API, so a hung connection must not hold them forever.
+const API_TIMEOUT_MS = 10_000;
+
+function rolesOf(claims: ApiClaims): string[] {
+  const raw = claims.role;
+  return Array.isArray(raw) ? raw : raw ? [raw] : [];
+}
+
+// The skew is capped at a quarter of the token's lifetime, so a short-lived token is not refreshed
+// on every read. A token without a lifetime gets the floor.
+function nextRefreshAt(claims: ApiClaims): number {
+  const expiresAt = claims.exp * 1000;
+  const lifetimeMs = Math.max(0, (claims.exp - claims.iat) * 1000);
+  const refreshAt = expiresAt - Math.min(MAX_REFRESH_SKEW_MS, lifetimeMs / 4);
+  if (!Number.isFinite(refreshAt)) return Date.now() + MIN_REFRESH_GAP_MS;
+  return Math.max(Date.now() + MIN_REFRESH_GAP_MS, refreshAt);
+}
+
+// No answer, or a gateway that could not reach the API. A plain 500 is left out, because the API
+// may fail after it has checked the password.
+function apiUnavailable(error: unknown): boolean {
+  if (!axios.isAxiosError(error)) return false;
+  const status = error.response?.status;
+  return status === undefined || status === 502 || status === 503 || status === 504;
+}
+
+// What a log line may contain. The error itself carries the request, which holds the password or
+// tokens.
+function failureShape(error: unknown) {
+  return {
+    status: axios.isAxiosError(error) ? error.response?.status : undefined,
+    code: axios.isAxiosError(error) ? error.code : undefined,
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+/**
+ * next-auth options for email and password sign-in against the API. The API issues a short-lived
+ * access token and a refresh token that changes on every refresh. The session refreshes ahead of
+ * expiry, rides out temporary API failures, and ends seven days after sign-in.
+ */
+export function createAuthOptions(config: SessionConfig, settings: AuthOptionsSettings): NextAuthOptions {
+  const { env } = settings;
+  if (settings.http === undefined && !settings.apiUrl) {
+    throw new Error("createAuthOptions needs the API base URL, and apiUrl is empty.");
+  }
+  const http = settings.http ?? axios.create({ baseURL: settings.apiUrl, allowAbsoluteUrls: false });
+
+  const readClaims = (token: string) =>
+    jwt.verify(token, resolveJwtSecret(config, env), {
+      clockTolerance: CLOCK_TOLERANCE_S,
+    }) as unknown as ApiClaims;
+
+  async function postTokens(path: string, body: object): Promise<TokenPair> {
+    const response = await http.post<TokenPair>(path, body, { timeout: API_TIMEOUT_MS });
+    return response.data;
+  }
+
+  // Parallel session reads carry the same refresh token. The API accepts each refresh token once.
+  // It treats a second use as replay and revokes every session the user has. So all reads of one
+  // token share one refresh. The result is kept for a while, because a slow read can arrive with
+  // the old token after the refresh is done.
+  //
+  // The map lives in one server process. Replicas do not share it.
+  const inFlight = new Map<string, Promise<AppToken>>();
+
+  function refreshOnce(token: AppToken): Promise<AppToken> {
+    const key = token.refreshToken as string;
+    const existing = inFlight.get(key);
+    if (existing) return existing;
+
+    const pending = rotate(token);
+    inFlight.set(key, pending);
+    // The minute counts from the answer, so a slow refresh is remembered as long as a fast one.
+    void pending.then(() => {
+      // unref, so the timer cannot keep a serverless invocation alive.
+      const expiry = setTimeout(() => inFlight.delete(key), REMEMBER_ROTATION_MS) as unknown as {
+        unref?: () => void;
+      };
+      expiry.unref?.();
+    });
+    return pending;
+  }
+
+  async function rotate(token: AppToken): Promise<AppToken> {
+    let refreshed: TokenPair;
+    try {
+      refreshed = await postTokens(
+        "/auth/refresh-token",
+        { token: token.accessToken, refreshToken: token.refreshToken },
+      );
+    } catch (error) {
+      // The API refused the token pair: a bad access token, or a refresh token that is unknown,
+      // expired or already used. Only this ends the session.
+      const status = axios.isAxiosError(error) ? error.response?.status : undefined;
+      if (status === 400 || status === 401) {
+        return { ...token, error: SESSION_ERRORS.refreshRejected };
+      }
+      // A network error or an API restart keeps the session. A later read tries again.
+      console.error("Refresh token request failed, keeping the session", failureShape(error));
+      return { ...token, refreshAt: Date.now() + REMEMBER_ROTATION_MS };
+    }
+
+    // A success without tokens is treated as a temporary failure, and the session keeps its own.
+    if (!refreshed?.token || !refreshed.refreshToken) {
+      console.error("Refresh token response had no tokens, keeping the session");
+      return { ...token, refreshAt: Date.now() + REMEMBER_ROTATION_MS };
+    }
+
+    // The API has already replaced the old tokens. Keep the new ones whatever happens below,
+    // because the old refresh token now counts as replay.
+    const next: AppToken = {
+      ...token,
+      accessToken: refreshed.token,
+      refreshToken: refreshed.refreshToken,
+    };
+    delete next.error;
+
+    try {
+      const claims = readClaims(refreshed.token);
+      next.refreshAt = nextRefreshAt(claims);
+      next.user = { ...(token.user as SessionUser), roles: rolesOf(claims) };
+    } catch (error) {
+      // The token is unreadable, for example after a secret change. Retry soon with the new
+      // refresh token.
+      console.error("Could not read the refreshed access token, retrying shortly", failureShape(error));
+      next.refreshAt = Date.now() + REMEMBER_ROTATION_MS;
+    }
+
+    return next;
+  }
+
+  return {
+    providers: [
+      CredentialsProvider({
+        name: "Credentials",
+        credentials: {
+          email: { label: "Email", type: "email" },
+          password: { label: "Password", type: "password" },
+        },
+        async authorize(credentials) {
+          if (!credentials) {
+            throw new Error("Credentials are missing");
+          }
+          try {
+            const tokens = await postTokens(
+              "/auth/login",
+              { email: credentials.email, password: credentials.password },
+            );
+            if (!tokens?.token || !tokens.refreshToken) {
+              throw new Error("Login response had no tokens");
+            }
+            const claims = readClaims(tokens.token);
+            const user: AuthorizedUser = {
+              id: claims.sub,
+              name: claims.unique_name,
+              email: credentials.email,
+              roles: rolesOf(claims),
+              accessToken: tokens.token,
+              refreshToken: tokens.refreshToken,
+            };
+            return user;
+          } catch (error) {
+            console.error("Sign-in failed", failureShape(error));
+            // No cause: next-auth logs this error, and the cause carries the password.
+            // eslint-disable-next-line preserve-caught-error
+            throw new Error(
+              apiUnavailable(error) ? SIGN_IN_ERRORS.unavailable : SIGN_IN_ERRORS.invalidCredentials,
+            );
+          }
+        },
+      }),
+    ],
+    pages: {
+      signIn: config.loginRoute,
+    },
+    session: {
+      maxAge: ABSOLUTE_SESSION_MAX_AGE / 1000,
+    },
+    callbacks: {
+      async jwt({ token: current, user }) {
+        let token = current as AppToken;
+        if (user) {
+          const signedIn = user as AuthorizedUser;
+          const claims = readClaims(signedIn.accessToken);
+          token = {
+            ...token,
+            accessToken: signedIn.accessToken,
+            refreshToken: signedIn.refreshToken,
+            refreshAt: nextRefreshAt(claims),
+            loginAt: Date.now(),
+            user: {
+              id: signedIn.id,
+              name: signedIn.name ?? "",
+              email: signedIn.email ?? "",
+              roles: signedIn.roles,
+            },
+          };
+          delete token.error;
+        }
+
+        // A session without a sign-in time counts as expired.
+        if (token.loginAt === undefined || Date.now() - token.loginAt > ABSOLUTE_SESSION_MAX_AGE) {
+          return { ...token, error: SESSION_ERRORS.absoluteExpiry };
+        }
+
+        // Only a new sign-in recovers a terminal session, so the API is not asked again.
+        if (isTerminalSessionError(token.error)) {
+          return token;
+        }
+
+        if (token.refreshAt && Date.now() < token.refreshAt) {
+          return token;
+        }
+
+        if (!token.refreshToken) {
+          return { ...token, error: SESSION_ERRORS.noRefreshToken };
+        }
+
+        return refreshOnce(token);
+      },
+      async session({ session, token: current }) {
+        const token = current as AppToken;
+        // Cast, so it compiles against the app's own Session declaration.
+        return {
+          ...session,
+          user: token.user,
+          accessToken: token.accessToken,
+          error: token.error,
+          // Lets the UI warn before the seven days run out.
+          absoluteExpiresAt: token.loginAt ? token.loginAt + ABSOLUTE_SESSION_MAX_AGE : undefined,
+        } as Session;
+      },
+    },
+  };
+}

package/src/auth/index.ts

@@ -0,0 +1,2 @@
+export { createAuthOptions } from "./createAuthOptions";
+export type { AuthOptionsSettings, SessionUser } from "./createAuthOptions";

package/src/config.ts

@@ -1,6 +1,6 @@
 /**
  * The values that differ between the apps using this package. Everything else in the session layer
- * is identical across them, so it stays hardcoded rather than becoming an option.
+ * is the same in every app, so it is hardcoded.
  */
 export interface SessionConfig {
   /**
@@ -10,7 +10,7 @@ export interface SessionConfig {
   jwtSecretEnvVar: string;
   /**
    * Where an expired or rejected session sends the browser. An app with a locale prefix uses
-   * something like "/en/login", one without uses "/login".
+   * something like "/en/login". An app without one uses "/login".
    */
   loginRoute: string;
   /**
@@ -23,7 +23,7 @@ export interface SessionConfig {
 
 /**
  * Declares an app's config as a typed constant. Throws when `draftStoragePrefix` is not a bare name,
- * so a bad value fails when the app starts rather than when a form first opens.
+ * so a bad value fails at app start, before any form opens.
  */
 export function defineSessionConfig(config: SessionConfig): SessionConfig {
   draftPrefix(config);
@@ -31,8 +31,8 @@ export function defineSessionConfig(config: SessionConfig): SessionConfig {
 }
 
 /**
- * The key prefix for form drafts. A colon or an empty name builds keys such as "app:draft::draft:",
- * which match none of the drafts already saved under "app:draft:".
+ * The key prefix for form drafts. Throws on a colon or an empty name. Those build keys such as
+ * "app:draft::draft:", which match no draft saved under "app:draft:".
  */
 export function draftPrefix(config: Pick<SessionConfig, "draftStoragePrefix">): string {
   const name = config.draftStoragePrefix;
@@ -43,11 +43,22 @@ export function draftPrefix(config: Pick<SessionConfig, "draftStoragePrefix">):
 }
 
 /**
- * Reads the API JWT secret named by the config. Throws rather than returning undefined, because a
- * missing secret silently breaks token verification at runtime instead of at boot.
+ * Returns `value`, or throws when it is unset or empty. Pass `process.env.NAME` directly, so Next.js
+ * can inline public variables at build time.
+ */
+export function requireEnv(name: string, value: string | undefined): string {
+  if (!value) {
+    throw new Error(`Missing ${name}.`);
+  }
+  return value;
+}
+
+/**
+ * Reads the API JWT secret named by the config. Throws when it is missing, with a message that names
+ * the variable.
  *
- * The caller passes the environment, usually `process.env`. Reading it here would put
- * `@types/node` in the type surface of a package that ends up in a browser bundle.
+ * The caller passes the environment, usually `process.env`, so this entry point needs no Node
+ * types and stays safe to import in browser code.
  */
 export function resolveJwtSecret(
   config: SessionConfig,

package/src/errors.ts

@@ -9,7 +9,7 @@ export type StatusMessages = Partial<Record<number, string>>;
 
 /**
  * Axios codes for a request that never got a response from the network. A browser reports every
- * network failure as ERR_NETWORK. On the server, Node reports the cause instead.
+ * network failure as ERR_NETWORK. On the server, Node reports the specific cause.
  */
 const NO_RESPONSE_CODES = new Set([
   "ERR_NETWORK",
@@ -26,15 +26,19 @@ const NO_RESPONSE_CODES = new Set([
 /**
  * Turns a failed request into one line a user can read.
  *
- * On a 4xx response the body's own message comes first: a text body, then `message`, the first
- * validation error and `detail` from a JSON body. After that come `statusMessages` for the status
- * and `fallback`. On a 5xx the caller's status message comes first, because the body may be a
- * proxy's "Bad Gateway" rather than the API's own words. A problem details `title` is never used:
- * ASP.NET Core fills it with generic text such as "Bad Request", which says less than `fallback`.
+ * On a 4xx response the order is:
+ * 1. The body's own message: a text body, or `message`, the first validation error or `detail` from
+ *    a JSON body.
+ * 2. `statusMessages` for the status.
+ * 3. `fallback`.
+ *
+ * On a 5xx the caller's status message comes first, because the body may come from a proxy, such
+ * as "Bad Gateway". A problem details `title` is never used. ASP.NET Core fills it with generic text
+ * such as "Bad Request", which says less than `fallback`.
  *
  * Only single line text counts as a message. Axios's own message, such as "Request failed with
- * status code 500", is never shown, and a cancelled request gives `fallback`. Any other `Error`
- * gives its message.
+ * status code 500", is never shown. A cancelled request gives `fallback`. Any other `Error` gives
+ * its message.
  */
 export function formatApiError(
   error: unknown,

package/src/forms/useFormDraft.ts

@@ -5,9 +5,8 @@ import { draftPrefix, type SessionConfig } from "../config";
 
 const WRITE_DELAY_MS = 500;
 
-// How long a draft is offered. Long enough to outlive an expired session or a closed tab, short
-// enough that week-old work is not offered as if it were current. An expired draft is removed when
-// its form next reads it.
+// How long a draft is offered. Long enough to outlive an expired session or a closed tab. Short
+// enough that stale work is not offered as current. A form removes its expired draft on next read.
 const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 interface Envelope<T> {
@@ -35,10 +34,10 @@ function read<T>(storageKey: string): T | null {
 
 export interface FormDraftOptions<T> {
   /**
-   * The signed-in user's id. A browser profile can be shared, so the draft is stored per user.
-   * Without that, the next person to sign in is offered the previous one's work. The last known
-   * owner is kept, because a lost cookie reports nobody and that is the moment the draft matters
-   * most. Nothing is stored until an owner is known.
+   * The signed-in user's id. A browser profile can be shared, so drafts are stored per user. That
+   * way nobody is offered another user's work. The hook keeps the last known owner. A lost cookie
+   * reports nobody, and that is when the draft matters most. Nothing is stored until an owner is
+   * known.
    */
   owner: string | undefined;
   /** Identifies the form and the entity it edits, for example `recipe:new` or `recipe:42`. */
@@ -63,16 +62,15 @@ export interface FormDraft<T> {
  * Keeps a form's values in localStorage so a sign-out, reload or closed tab does not lose them.
  * Values are written half a second after the last change, so only that last half second is at risk.
  *
- * A draft found at mount is offered for restore rather than applied, so an edit form never silently
- * overwrites what the API returned. Saving starts immediately either way. The offer is held in
- * memory, so the newest work is always the thing in storage.
+ * A draft found at mount is offered for restore, not applied. So an edit form never silently
+ * overwrites what the API returned. Saving starts at once, whether or not the offer is answered.
+ * The offer is held in memory, so storage always holds the newest work.
  */
 export function useFormDraft<T>(
   config: Pick<SessionConfig, "draftStoragePrefix">,
   { owner, scope, value }: FormDraftOptions<T>,
 ): FormDraft<T> {
-  // Adjusted during render rather than in an effect, which is the supported way to derive state
-  // from changing inputs.
+  // Set during render, which is React's supported way to derive state from changing inputs.
   const [lastOwner, setLastOwner] = useState<string | undefined>(undefined);
   if (owner && owner !== lastOwner) setLastOwner(owner);
 
@@ -86,21 +84,21 @@ export function useFormDraft<T>(
   const writeTimer = useRef<number | null>(null);
 
   useEffect(() => {
-    // Re-base on a key change too. The values on screen belong to the old key, and writing them
-    // under the new one would put this form's work in another form's draft.
+    // Re-base on a key change too. The values on screen belong to the old key and must not land
+    // in the new key's draft.
     untouched.current = json;
-    // Reading the store is an external-system read, which is what an effect is for.
+    // Reading storage is an external-system read, which belongs in an effect.
     // eslint-disable-next-line react-hooks/set-state-in-effect
     setPending(key == null ? null : read<T>(key));
-    // Keyed on the draft key alone on purpose. Re-reading whenever the values change would
-    // re-offer a draft the user has already answered.
+    // Runs on a key change only. Re-reading on every value change would re-offer a draft the user
+    // has already answered.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [key]);
 
   useEffect(() => {
     if (key == null) return;
-    // Write only once the form differs from how it opened. Writing the pristine form would
-    // overwrite the draft being offered before the user has answered.
+    // Write only once the form differs from how it opened, so the pristine form never overwrites
+    // a draft that is still on offer.
     if (json === untouched.current) return;
     const timer = window.setTimeout(() => {
       try {
@@ -116,14 +114,14 @@ export function useFormDraft<T>(
 
   const clear = useCallback(() => {
     if (key == null) return;
-    // Cancel a write that is already scheduled, and treat the current values as the new baseline.
-    // Otherwise a save is followed by the draft being written back.
+    // Cancel any scheduled write and make the current values the baseline, so a save is never
+    // followed by a fresh draft write.
     if (writeTimer.current != null) window.clearTimeout(writeTimer.current);
     untouched.current = json;
     try {
       window.localStorage.removeItem(key);
     } catch {
-      // The draft is a convenience, not state anything depends on.
+      // The draft is a convenience. Nothing depends on it.
     }
   }, [key, json]);
 

package/src/index.ts

@@ -1,4 +1,4 @@
-export { defineSessionConfig, resolveJwtSecret } from "./config";
+export { defineSessionConfig, requireEnv, resolveJwtSecret } from "./config";
 export type { SessionConfig } from "./config";
 export { formatApiError } from "./errors";
 export type { StatusMessages } from "./errors";

package/src/session/expiry.ts

@@ -9,6 +9,17 @@ export const SESSION_ERRORS = {
   noRefreshToken: "NoRefreshToken",
 } as const;
 
+/**
+ * The codes a failed sign-in reports in next-auth's `error`. Wrong credentials and every API answer
+ * look the same, so the message never hints that a password was right. Only an API that does not
+ * answer, or a gateway error, reports `unavailable`. That depends on the server, never on the
+ * password.
+ */
+export const SIGN_IN_ERRORS = {
+  invalidCredentials: "InvalidCredentials",
+  unavailable: "SignInUnavailable",
+} as const;
+
 /** One of the values in `SESSION_ERRORS`. */
 export type SessionError = (typeof SESSION_ERRORS)[keyof typeof SESSION_ERRORS];
 
@@ -19,13 +30,13 @@ export function isTerminalSessionError(error: string | undefined): boolean {
   return error != null && TERMINAL.has(error);
 }
 
-// Whether the re-sign-in prompt is showing. It lives outside React because the axios interceptor
-// that raises it is a plain module, and because the page gate has to know: it must not redirect to
-// the login page while the prompt is recovering the session in place.
+// Whether the re-sign-in prompt is showing. It lives outside React for two reasons:
+// 1. The axios interceptor that raises it is a plain module.
+// 2. The page gate reads it, so it never redirects to login while the prompt recovers the session.
 //
-// Kept on globalThis under a registered symbol, so two copies of this module, such as two installed
-// versions of the package, still share one prompt. Separate state would let a prompt raised through
-// one copy go unseen by a gate reading the other, and the gate would redirect away from the form.
+// It sits on globalThis under a registered symbol, so two copies of this module share one prompt.
+// Two installed versions of the package are one example. A gate reading one copy then sees a
+// prompt raised through the other and keeps the form on screen.
 interface PromptState {
   open: boolean;
   listeners: Set<() => void>;

package/src/session/index.ts

@@ -1,5 +1,6 @@
 export {
   SESSION_ERRORS,
+  SIGN_IN_ERRORS,
   closeSessionPrompt,
   getSessionPromptOpen,
   isTerminalSessionError,

package/src/session/react/ProtectedGate.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useEffect, type ReactNode } from "react";
+import { useSessionGate } from "./useSessionGate";
+
+export interface ProtectedGateProps {
+  /** Where a signed-out visitor, or a session dead on arrival, is sent. */
+  loginHref: string;
+  /** What shows while the page may not render yet. */
+  fallback?: ReactNode | undefined;
+  children: ReactNode;
+}
+
+/**
+ * Renders a protected page only on a usable session, and keeps it rendered while the re-sign-in
+ * prompt recovers the session. Never redirects while the prompt is open.
+ */
+export function ProtectedGate({ loginHref, fallback = null, children }: ProtectedGateProps) {
+  const router = useRouter();
+  const { status, promptOpen, usable, wasUsable, mayRender } = useSessionGate();
+
+  useEffect(() => {
+    // A page opened on a dead session must not render, or the user starts work they cannot save.
+    // A session that dies later keeps the page, and the prompt recovers it in place.
+    if (promptOpen) return;
+    if (status === "unauthenticated" || (status === "authenticated" && !usable && !wasUsable)) {
+      // replace, so Back does not return to a page that only redirects again.
+      router.replace(loginHref);
+    }
+  }, [status, usable, wasUsable, promptOpen, router, loginHref]);
+
+  return mayRender ? children : fallback;
+}