@stapel/auth-react 1.0.0

package/src/model/mutations.ts

@@ -0,0 +1,152 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import type {
+  UseMutationOptions,
+  UseMutationResult,
+} from "@tanstack/react-query";
+import type { StapelApiError } from "@stapel/core";
+import type {
+  OtpChannel,
+  StatusResponse,
+  TotpDisableRequest,
+} from "../api/types.js";
+import { useAuthApi, useAuthSession } from "./context.js";
+import { authQueryKeys } from "./queryKeys.js";
+
+/**
+ * Write hooks with cache invalidation (frontend-standard §2 — "мутации с
+ * инвалидацией"). Each invalidates exactly the keys its effect touches so the
+ * security screen / session list stay consistent without a manual refetch.
+ *
+ * Note: options are built as typed `UseMutationOptions` objects rather than
+ * `useMutation<…>()` call-site generics — that keeps `void` (no data / no
+ * variables) in *type-reference* position, which `no-invalid-void-type`
+ * permits, while call-expression type arguments do not.
+ */
+
+/** Explicit logout: revoke server-side, tear down the session, drop auth caches. */
+export function useLogout(): UseMutationResult<void, StapelApiError, void> {
+  const session = useAuthSession();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<void, StapelApiError, void> = {
+    mutationFn: () => session.logout(),
+    onSuccess: () => {
+      queryClient.removeQueries({ queryKey: authQueryKeys.all });
+    },
+  };
+  return useMutation(options);
+}
+
+/** Revoke one session (auth-sa.md §12). Immediate — token blacklisted. */
+export function useRevokeSession(): UseMutationResult<
+  StatusResponse,
+  StapelApiError,
+  string
+> {
+  const api = useAuthApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<StatusResponse, StapelApiError, string> = {
+    mutationFn: (id) => api.revokeSession(id),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: authQueryKeys.sessions() });
+      void queryClient.invalidateQueries({
+        queryKey: authQueryKeys.securityStatus(),
+      });
+    },
+  };
+  return useMutation(options);
+}
+
+/** Revoke all sessions except the current one (auth-sa.md §12). */
+export function useRevokeOtherSessions(): UseMutationResult<
+  StatusResponse,
+  StapelApiError,
+  void
+> {
+  const api = useAuthApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<StatusResponse, StapelApiError, void> = {
+    mutationFn: () => api.revokeOtherSessions(),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: authQueryKeys.sessions() });
+    },
+  };
+  return useMutation(options);
+}
+
+/** Clear the `is_suspicious` flag ("This was me"). Idempotent (auth-sa.md §12). */
+export function useConfirmSession(): UseMutationResult<
+  StatusResponse,
+  StapelApiError,
+  string
+> {
+  const api = useAuthApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<StatusResponse, StapelApiError, string> = {
+    mutationFn: (id) => api.confirmSession(id),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: authQueryKeys.sessions() });
+    },
+  };
+  return useMutation(options);
+}
+
+/** Remove a passkey (auth-sa.md §17). Guard against `last_auth_method`. */
+export function useRemovePasskey(): UseMutationResult<
+  void,
+  StapelApiError,
+  string
+> {
+  const api = useAuthApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<void, StapelApiError, string> = {
+    mutationFn: (id) => api.passkeyRemove(id),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: authQueryKeys.passkeys() });
+      void queryClient.invalidateQueries({
+        queryKey: authQueryKeys.securityStatus(),
+      });
+    },
+  };
+  return useMutation(options);
+}
+
+/** Disable TOTP via authenticator/backup/SMS recovery (auth-sa.md §11). */
+export function useDisableTotp(): UseMutationResult<
+  StatusResponse,
+  StapelApiError,
+  TotpDisableRequest
+> {
+  const api = useAuthApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<
+    StatusResponse,
+    StapelApiError,
+    TotpDisableRequest
+  > = {
+    mutationFn: (request) => api.totpDisable(request),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: authQueryKeys.securityStatus(),
+      });
+    },
+  };
+  return useMutation(options);
+}
+
+/** Cancel a pending delayed authenticator change (auth-sa.md §9). */
+export function useCancelDelayedChange(
+  channel: OtpChannel
+): UseMutationResult<StatusResponse, StapelApiError, string> {
+  const api = useAuthApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<StatusResponse, StapelApiError, string> = {
+    mutationFn: (changeRequestId) =>
+      api.changeDelayedCancel(channel, changeRequestId),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: authQueryKeys.delayedChange(channel),
+      });
+    },
+  };
+  return useMutation(options);
+}

package/src/model/queries.ts

@@ -0,0 +1,130 @@
+import { useQuery } from "@tanstack/react-query";
+import type { UseQueryResult } from "@tanstack/react-query";
+import type { StapelApiError } from "@stapel/core";
+import type {
+  AuditPage,
+  AuthSession as AuthSessionRecord,
+  Capabilities,
+  DelayedChangeStatus,
+  OtpChannel,
+  Passkey,
+  PasswordMethods,
+  SecurityStatus,
+  SsoLookupResponse,
+  StapelUser,
+} from "../api/types.js";
+import { useAuthApi } from "./context.js";
+import { authQueryKeys } from "./queryKeys.js";
+
+/**
+ * Read hooks over the auth API. Staleness follows core's query defaults;
+ * override per call site via `options` where a page needs fresher data (e.g.
+ * `sessions` after a revoke). Keys are namespaced (see `authQueryKeys`).
+ */
+
+/** Login-method feature matrix — call on the sign-in page (auth-sa.md §"capabilities"). */
+export function useCapabilities(): UseQueryResult<Capabilities, StapelApiError> {
+  const api = useAuthApi();
+  return useQuery({
+    queryKey: authQueryKeys.capabilities(),
+    queryFn: () => api.capabilities(),
+    staleTime: 5 * 60_000,
+  });
+}
+
+/** Current user (auth-sa.md §14). Enabled only when a session exists. */
+export function useMe(
+  enabled = true
+): UseQueryResult<StapelUser, StapelApiError> {
+  const api = useAuthApi();
+  return useQuery({
+    queryKey: authQueryKeys.me(),
+    queryFn: () => api.me(),
+    enabled,
+  });
+}
+
+/** Security settings snapshot (auth-sa.md §10). */
+export function useSecurityStatus(): UseQueryResult<
+  SecurityStatus,
+  StapelApiError
+> {
+  const api = useAuthApi();
+  return useQuery({
+    queryKey: authQueryKeys.securityStatus(),
+    queryFn: () => api.securityStatus(),
+  });
+}
+
+/** Password-change tabs (auth-sa.md §4). */
+export function usePasswordMethods(): UseQueryResult<
+  PasswordMethods,
+  StapelApiError
+> {
+  const api = useAuthApi();
+  return useQuery({
+    queryKey: authQueryKeys.passwordMethods(),
+    queryFn: () => api.passwordMethods(),
+  });
+}
+
+/** Active sessions (auth-sa.md §12). */
+export function useSessions(): UseQueryResult<
+  readonly AuthSessionRecord[],
+  StapelApiError
+> {
+  const api = useAuthApi();
+  return useQuery({
+    queryKey: authQueryKeys.sessions(),
+    queryFn: () => api.sessions(),
+  });
+}
+
+/** Registered passkeys (auth-sa.md §17). */
+export function usePasskeys(): UseQueryResult<
+  readonly Passkey[],
+  StapelApiError
+> {
+  const api = useAuthApi();
+  return useQuery({
+    queryKey: authQueryKeys.passkeys(),
+    queryFn: () => api.passkeys(),
+  });
+}
+
+/** A page of the security audit log (auth-sa.md §16). */
+export function useAuditLog(
+  page = 1
+): UseQueryResult<AuditPage, StapelApiError> {
+  const api = useAuthApi();
+  return useQuery({
+    queryKey: authQueryKeys.audit(page),
+    queryFn: () => api.auditLog(page),
+  });
+}
+
+/** Pending delayed authenticator change (auth-sa.md §9). */
+export function useDelayedChangeStatus(
+  channel: OtpChannel
+): UseQueryResult<DelayedChangeStatus, StapelApiError> {
+  const api = useAuthApi();
+  return useQuery({
+    queryKey: authQueryKeys.delayedChange(channel),
+    queryFn: () => api.changeDelayedStatus(channel),
+  });
+}
+
+/**
+ * SSO domain lookup (auth-sa.md §18). Disabled until `domain` is a non-empty
+ * value — call after the user finishes typing their email.
+ */
+export function useSsoLookup(
+  domain: string
+): UseQueryResult<SsoLookupResponse, StapelApiError> {
+  const api = useAuthApi();
+  return useQuery({
+    queryKey: authQueryKeys.ssoLookup(domain),
+    queryFn: () => api.ssoLookup(domain),
+    enabled: domain.length > 0,
+  });
+}

package/src/model/queryKeys.ts

@@ -0,0 +1,32 @@
+/**
+ * Namespaced TanStack Query keys (frontend-standard §2 — "ключи неймспейснуты").
+ * Everything under the `"auth"` root so a host can invalidate the whole module
+ * or match a single resource. Persist scope is per-user via core's query
+ * runtime (`setPersistUser`). Explicit tuple return types satisfy
+ * `--isolatedDeclarations`.
+ */
+const ROOT = "auth" as const;
+
+export const authQueryKeys: {
+  readonly all: readonly ["auth"];
+  capabilities(): readonly ["auth", "capabilities"];
+  me(): readonly ["auth", "me"];
+  securityStatus(): readonly ["auth", "security", "status"];
+  passwordMethods(): readonly ["auth", "password", "methods"];
+  sessions(): readonly ["auth", "sessions"];
+  passkeys(): readonly ["auth", "passkeys"];
+  audit(page: number): readonly ["auth", "audit", number];
+  delayedChange(channel: string): readonly ["auth", "change", "delayed", string];
+  ssoLookup(domain: string): readonly ["auth", "sso", "lookup", string];
+} = {
+  all: [ROOT],
+  capabilities: () => [ROOT, "capabilities"],
+  me: () => [ROOT, "me"],
+  securityStatus: () => [ROOT, "security", "status"],
+  passwordMethods: () => [ROOT, "password", "methods"],
+  sessions: () => [ROOT, "sessions"],
+  passkeys: () => [ROOT, "passkeys"],
+  audit: (page) => [ROOT, "audit", page],
+  delayedChange: (channel) => [ROOT, "change", "delayed", channel],
+  ssoLookup: (domain) => [ROOT, "sso", "lookup", domain],
+};

package/src/model/runtime.ts

@@ -0,0 +1,93 @@
+import { createStapelClient } from "@stapel/core";
+import type { Analytics, PersistStorage, StapelClient } from "@stapel/core";
+import { createAuthApi } from "../api/authApi.js";
+import type { AuthApi } from "../api/authApi.js";
+import {
+  createVerificationController,
+} from "../flows/verificationFlow.js";
+import type { VerificationController } from "../flows/verificationFlow.js";
+import { createAuthSession } from "./session.js";
+import type { AuthSession, TeardownReason } from "./session.js";
+
+/**
+ * The wired auth runtime — the one place the flagship seams are connected
+ * (frontend-standard §2). It builds a {@link StapelClient} whose `getToken` /
+ * `onAuthRefresh` come from the {@link AuthSession} and whose
+ * `onVerificationChallenge` is the {@link VerificationController}'s handler, so
+ * the step-up factor flow and token rotation "just work" for every request.
+ *
+ * The returned `client` is what the host injects into core's
+ * `StapelConfigProvider` (as the default or the `"auth"` module client),
+ * preserving the client-injection fork seam of §7.2.
+ */
+export interface AuthRuntime {
+  readonly client: StapelClient;
+  readonly api: AuthApi;
+  readonly session: AuthSession;
+  readonly verification: VerificationController;
+  readonly analytics: Analytics | null;
+}
+
+export interface CreateAuthRuntimeOptions {
+  /** e.g. `/auth/api` or `https://app.example.com/auth/api`. */
+  readonly baseUrl: string;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly storage?: PersistStorage;
+  readonly analytics?: Analytics | null;
+  /** Cookie mode (httponly JWT cookies) vs header/bearer. Default false. */
+  readonly cookieMode?: boolean;
+  /** Called after a session teardown (revoked/expired/logout). */
+  readonly onTeardown?: (reason: TeardownReason) => void;
+  /** Extra headers merged into every request (e.g. a captcha or tenant id). */
+  readonly defaultHeaders?: Record<string, string>;
+  /** THIN WebAuthn binding for the passkey verification factor. */
+  readonly webauthnGet?: (options: Record<string, unknown>) => Promise<unknown>;
+}
+
+export function createAuthRuntime(
+  options: CreateAuthRuntimeOptions
+): AuthRuntime {
+  const analytics = options.analytics ?? null;
+
+  // `api` is assigned after the client exists; session/verification reference
+  // it lazily through the holder, breaking the client↔session/verification
+  // wiring cycle without a reassigned `let`.
+  const holder: { current: AuthApi | null } = { current: null };
+  const getApi = (): AuthApi => {
+    if (holder.current === null) {
+      throw new Error("auth runtime used before initialization");
+    }
+    return holder.current;
+  };
+
+  const session = createAuthSession({
+    api: getApi,
+    ...(options.storage !== undefined ? { storage: options.storage } : {}),
+    cookieMode: options.cookieMode ?? false,
+    ...(options.onTeardown !== undefined ? { onTeardown: options.onTeardown } : {}),
+  });
+
+  const verification = createVerificationController({
+    api: getApi,
+    analytics,
+    ...(options.webauthnGet !== undefined
+      ? { webauthnGet: options.webauthnGet }
+      : {}),
+  });
+
+  const client = createStapelClient({
+    baseUrl: options.baseUrl,
+    ...(options.fetch !== undefined ? { fetch: options.fetch } : {}),
+    getToken: () => session.getAccessToken(),
+    onAuthRefresh: () => session.onAuthRefresh(),
+    onVerificationChallenge: verification.handler,
+    ...(options.defaultHeaders !== undefined
+      ? { defaultHeaders: options.defaultHeaders }
+      : {}),
+  });
+
+  const api = createAuthApi(client);
+  holder.current = api;
+
+  return { client, api, session, verification, analytics };
+}

package/src/model/session.ts

@@ -0,0 +1,188 @@
+import { StapelApiError } from "@stapel/core";
+import type { PersistStorage } from "@stapel/core";
+import type { AuthApi } from "../api/authApi.js";
+import type { AuthResponse, AuthTokens, StapelUser } from "../api/types.js";
+
+/**
+ * Why a session teardown fired (auth-sa.md §13, §19.3):
+ *  - `revoked`  — refresh token replayed/blacklisted (`error.401.refresh_revoked`);
+ *    a stolen-token signal, hard logout.
+ *  - `expired`  — refresh failed for any other reason (TTL, network).
+ *  - `logout`   — explicit user logout.
+ */
+export type TeardownReason = "revoked" | "expired" | "logout";
+
+export interface AuthSessionState {
+  readonly user: StapelUser | null;
+  readonly tokens: AuthTokens | null;
+  readonly status: "anonymous" | "authenticated";
+}
+
+export interface AuthSession {
+  getState(): AuthSessionState;
+  subscribe(listener: () => void): () => void;
+  /** For `createStapelClient({ getToken })`. Header mode only; cookie mode → null. */
+  getAccessToken(): string | null;
+  /** For `createStapelClient({ onAuthRefresh })`. Dedups + breaks recursion. */
+  onAuthRefresh(): Promise<string | null>;
+  /** Commit a session from any AuthResponse (login/register/merge/modify). */
+  adopt(response: AuthResponse): void;
+  /** Store a bare token pair (e.g. QR `login_request` fulfilment). */
+  setTokens(tokens: AuthTokens): void;
+  /** Explicit logout: revoke server-side, then tear down locally. */
+  logout(): Promise<void>;
+  /** Load a persisted session (call once on mount). */
+  restore(): Promise<void>;
+}
+
+export interface AuthSessionOptions {
+  /** Lazy to break the client↔session wiring cycle (see README). */
+  readonly api: AuthApi | (() => AuthApi);
+  /** Persist backend. Default: core's IndexedDB→localStorage→memory. */
+  readonly storage?: PersistStorage;
+  /** Persist key. Default `"stapel-auth:session"`. */
+  readonly persistKey?: string;
+  /**
+   * Cookie mode: the backend sets httponly JWT cookies, so no bearer token is
+   * attached and refresh uses `GET /token/refresh/` (cookie). `getAccessToken`
+   * returns null. Default `false` (header/bearer mode).
+   */
+  readonly cookieMode?: boolean;
+  /** Notified after a teardown so the host can purge caches / redirect. */
+  readonly onTeardown?: (reason: TeardownReason) => void;
+}
+
+const REFRESH_REVOKED = "error.401.refresh_revoked";
+
+export function createAuthSession(options: AuthSessionOptions): AuthSession {
+  const persistKey = options.persistKey ?? "stapel-auth:session";
+  const cookieMode = options.cookieMode ?? false;
+  const resolveApi = (): AuthApi =>
+    typeof options.api === "function" ? options.api() : options.api;
+
+  let state: AuthSessionState = {
+    user: null,
+    tokens: null,
+    status: "anonymous",
+  };
+  const listeners = new Set<() => void>();
+
+  // Recursion guard: while the refresh network call is in flight, its own 401
+  // must NOT re-enter refresh (that call goes through the same client).
+  let refreshing = false;
+  let inFlight: Promise<string | null> | null = null;
+
+  function notify(): void {
+    for (const listener of listeners) listener();
+  }
+
+  function setState(next: AuthSessionState): void {
+    state = next;
+    notify();
+  }
+
+  function persist(): void {
+    // Only persist when a storage backend is configured; otherwise the session
+    // stays in memory for the page lifetime.
+    const storage = options.storage;
+    if (storage) {
+      void storage.set(persistKey, { user: state.user, tokens: state.tokens });
+    }
+  }
+
+  function adopt(response: AuthResponse): void {
+    setState({
+      user: response.user,
+      tokens: response.tokens,
+      status: "authenticated",
+    });
+    persist();
+  }
+
+  function setTokens(tokens: AuthTokens): void {
+    setState({ ...state, tokens, status: "authenticated" });
+    persist();
+  }
+
+  function clearLocal(): void {
+    setState({ user: null, tokens: null, status: "anonymous" });
+    const storage = options.storage;
+    if (storage) void storage.del(persistKey);
+  }
+
+  function teardown(reason: TeardownReason): void {
+    clearLocal();
+    options.onTeardown?.(reason);
+  }
+
+  async function doRefresh(): Promise<string | null> {
+    const refreshToken = state.tokens?.refresh ?? null;
+    if (!cookieMode && refreshToken === null) {
+      teardown("expired");
+      return null;
+    }
+    refreshing = true;
+    try {
+      const r = await resolveApi().tokenRefresh(
+        cookieMode ? undefined : (refreshToken ?? undefined)
+      );
+      setTokens({ access: r.access, refresh: r.refresh });
+      return r.access;
+    } catch (error) {
+      const code = error instanceof StapelApiError ? error.code : "";
+      teardown(code === REFRESH_REVOKED ? "revoked" : "expired");
+      return null;
+    } finally {
+      refreshing = false;
+    }
+  }
+
+  function onAuthRefresh(): Promise<string | null> {
+    if (refreshing) return Promise.resolve(null);
+    if (inFlight) return inFlight;
+    inFlight = doRefresh().finally(() => {
+      inFlight = null;
+    });
+    return inFlight;
+  }
+
+  async function logout(): Promise<void> {
+    try {
+      await resolveApi().logout();
+    } catch {
+      // Best-effort — tear down locally regardless.
+    }
+    teardown("logout");
+  }
+
+  async function restore(): Promise<void> {
+    const storage = options.storage;
+    if (!storage) return;
+    const stored = (await storage.get(persistKey)) as
+      | { user: StapelUser | null; tokens: AuthTokens | null }
+      | undefined;
+    if (stored && (stored.tokens !== null || stored.user !== null)) {
+      setState({
+        user: stored.user,
+        tokens: stored.tokens,
+        status: stored.tokens !== null ? "authenticated" : "anonymous",
+      });
+    }
+  }
+
+  return {
+    getState: () => state,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getAccessToken: () => (cookieMode ? null : (state.tokens?.access ?? null)),
+    onAuthRefresh,
+    adopt,
+    setTokens,
+    logout,
+    restore,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "_comment": "Self-contained on purpose: standalone-buildable per frontend-standard §7. Mirrors the root tsconfig.base.json settings.",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "isolatedModules": true,
+    "isolatedDeclarations": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}