@gopherium/react-auth 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,45 @@
+# @gopherium/react-auth
+
+Session authentication for React apps backed by gouncer's authkit.
+
+## Entry points
+
+- `@gopherium/react-auth` is the headless core: the auth API client,
+  `useSession`, `useLogout`, `sessionQueryKey`, the slot-based
+  `AuthGate`, `createAuthQueryClient`, and `isSessionRevoked`.
+- `@gopherium/react-auth/admin` is the user administration API client.
+- `@gopherium/react-auth/wpds` renders the WordPress Design System UI:
+  `LoginScreen` (brand prop), `AccountPanel`, `UsersScreen`,
+  `NewUserScreen`, and `usersNavItem`. Import
+  `@gopherium/react-auth/wpds/style.css` alongside it.
+- `@gopherium/react-auth/testing` is the msw harness: `server`,
+  `installTestEnvironment`, `seedSession`, `defaultUser`, and canned
+  handlers for the auth endpoints.
+
+## Mount
+
+```tsx
+const client = createAuthQueryClient()
+
+<QueryClientProvider client={client}>
+  <AuthGate loginScreen={(onLogin) => <LoginScreen brand="MyApp" onLogin={onLogin} />}>
+    <App />
+  </AuthGate>
+</QueryClientProvider>
+```
+
+## Consumer requirements
+
+- `react` and `@tanstack/react-query` are peer dependencies; the app
+  must own exactly one copy of each. With workspace or linked installs,
+  add both to your bundler's dedupe list.
+- The client calls same-origin `/api/auth/*` and `/api/users` paths. In
+  development, proxy `/api` to your backend so the `__Host-` session
+  cookie is first-party.
+- `/wpds` needs the `@wordpress/ui` peer and, on React 19, a
+  `@wordpress/element` patch stubbing the react-dom exports React 19
+  removed. See `patches/` in this package's repository directory.
+
+## License
+
+Apache-2.0. Copyright © 2026 Manuel 'SirLouen' Camargo.

package/dist/AuthGate.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import type { User } from './api';
+/**
+ * Guards its children behind a login session, rendering the given login
+ * screen until the user is authenticated.
+ * @param children - The application to reveal once a session is active.
+ * @param loginScreen - Renders the login UI, wired to the given login handler.
+ * @param loading - Shown while the session resolves.
+ * @param error - Shown when the session cannot be loaded.
+ * @returns The children, the login screen, or a status element.
+ */
+export declare function AuthGate({ children, loginScreen, loading, error, }: {
+    children: ReactNode;
+    loginScreen: (onLogin: (user: User) => void | Promise<void>) => ReactNode;
+    loading?: ReactNode;
+    error?: ReactNode;
+}): import("react").JSX.Element;

package/dist/AuthGate.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+// SPDX-License-Identifier: Apache-2.0
+import { useQueryClient } from '@tanstack/react-query';
+import { sessionQueryKey, useSession } from './session';
+/**
+ * Guards its children behind a login session, rendering the given login
+ * screen until the user is authenticated.
+ * @param children - The application to reveal once a session is active.
+ * @param loginScreen - Renders the login UI, wired to the given login handler.
+ * @param loading - Shown while the session resolves.
+ * @param error - Shown when the session cannot be loaded.
+ * @returns The children, the login screen, or a status element.
+ */
+export function AuthGate({ children, loginScreen, loading = _jsx("p", { role: "status", children: "Loading\u2026" }), error = _jsx("p", { role: "alert", children: "Something went wrong." }), }) {
+    const queryClient = useQueryClient();
+    const session = useSession();
+    if (session.data === undefined) {
+        if (session.isError) {
+            return _jsx(_Fragment, { children: error });
+        }
+        return _jsx(_Fragment, { children: loading });
+    }
+    if (session.data === null) {
+        return (_jsx(_Fragment, { children: loginScreen(async (user) => {
+                await queryClient.cancelQueries({ queryKey: sessionQueryKey });
+                queryClient.setQueryData(sessionQueryKey, user);
+            }) }));
+    }
+    return _jsx(_Fragment, { children: children });
+}

package/dist/admin/index.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+export declare const usersQueryKey: readonly ["users"];
+declare const userSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodString;
+    name: z.ZodString;
+    disabled: z.ZodBoolean;
+    created_at: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+export type User = z.infer<typeof userSchema>;
+export interface NewUser {
+    email: string;
+    name: string;
+    password: string;
+}
+/**
+ * EmailTakenError is thrown when a new user's email is already in use.
+ */
+export declare class EmailTakenError extends Error {
+}
+/**
+ * ValidationError is thrown when the backend rejects the submitted user
+ * details; its message is the backend's human-readable explanation.
+ */
+export declare class ValidationError extends Error {
+}
+/**
+ * Returns every user account.
+ * @param signal - Aborts the in-flight request.
+ * @returns The parsed list of users.
+ */
+export declare function fetchUsers(signal?: AbortSignal): Promise<User[]>;
+/**
+ * Creates a user account and returns it.
+ * @param input - The email, name, and password of the new account.
+ * @returns The created user.
+ */
+export declare function createUser(input: NewUser): Promise<User>;
+/**
+ * Sets whether a user may log in.
+ * @param id - The identifier of the user to update.
+ * @param disabled - Whether the account should be disabled.
+ */
+export declare function setUserDisabled(id: string, disabled: boolean): Promise<void>;
+export {};

package/dist/admin/index.js

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import { UnauthorizedError } from '../api';
+export const usersQueryKey = ['users'];
+const userSchema = z.object({
+    id: z.string(),
+    email: z.string(),
+    name: z.string(),
+    disabled: z.boolean(),
+    created_at: z.coerce.date(),
+});
+/**
+ * EmailTakenError is thrown when a new user's email is already in use.
+ */
+export class EmailTakenError extends Error {
+}
+/**
+ * ValidationError is thrown when the backend rejects the submitted user
+ * details; its message is the backend's human-readable explanation.
+ */
+export class ValidationError extends Error {
+}
+const errorSchema = z.object({ error: z.string() });
+/**
+ * Extracts the backend's explanation from a failed response body.
+ * @param response - The failed HTTP response.
+ * @param fallback - The message to use when the body is unreadable.
+ * @returns The message explaining the failure.
+ */
+async function errorMessage(response, fallback) {
+    try {
+        return errorSchema.parse(await response.json()).error;
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Returns every user account.
+ * @param signal - Aborts the in-flight request.
+ * @returns The parsed list of users.
+ */
+export async function fetchUsers(signal) {
+    const response = await fetch('/api/users', { signal });
+    if (response.status === 401) {
+        throw new UnauthorizedError('session expired');
+    }
+    if (!response.ok) {
+        throw new Error(`listing users failed with status ${response.status}`);
+    }
+    return z.array(userSchema).parse(await response.json());
+}
+/**
+ * Creates a user account and returns it.
+ * @param input - The email, name, and password of the new account.
+ * @returns The created user.
+ */
+export async function createUser(input) {
+    const response = await fetch('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(input),
+    });
+    if (response.status === 401) {
+        throw new UnauthorizedError('session expired');
+    }
+    if (response.status === 409) {
+        throw new EmailTakenError('email already in use');
+    }
+    if (response.status === 422) {
+        throw new ValidationError(await errorMessage(response, 'invalid user details'));
+    }
+    if (!response.ok) {
+        throw new Error(`creating user failed with status ${response.status}`);
+    }
+    return userSchema.parse(await response.json());
+}
+/**
+ * Sets whether a user may log in.
+ * @param id - The identifier of the user to update.
+ * @param disabled - Whether the account should be disabled.
+ */
+export async function setUserDisabled(id, disabled) {
+    const response = await fetch(`/api/users/${id}`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ disabled }),
+    });
+    if (response.status === 401) {
+        throw new UnauthorizedError('session expired');
+    }
+    if (!response.ok) {
+        throw new Error(`updating user failed with status ${response.status}`);
+    }
+}

package/dist/api.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+declare const userSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type User = z.infer<typeof userSchema>;
+/**
+ * InvalidCredentialsError is thrown when the backend rejects a login.
+ */
+export declare class InvalidCredentialsError extends Error {
+}
+/**
+ * UnauthorizedError is thrown when the backend rejects a request because
+ * the session is missing, expired, or revoked.
+ */
+export declare class UnauthorizedError extends Error {
+}
+/**
+ * RateLimitedError is thrown when the backend rejects a login for too many
+ * attempts.
+ */
+export declare class RateLimitedError extends Error {
+}
+/**
+ * Returns the logged-in user, or null when no session is active.
+ * @param signal - Aborts the in-flight request.
+ * @returns The current user, or null when unauthenticated.
+ */
+export declare function fetchSession(signal?: AbortSignal): Promise<User | null>;
+/**
+ * Logs in with the given credentials and returns the user.
+ * @param email - The account email address.
+ * @param password - The account password.
+ * @returns The authenticated user.
+ */
+export declare function login(email: string, password: string): Promise<User>;
+/**
+ * Ends the current session.
+ */
+export declare function logout(): Promise<void>;
+export {};

package/dist/api.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+const userSchema = z.object({
+    id: z.string(),
+    email: z.string(),
+    name: z.string(),
+});
+/**
+ * InvalidCredentialsError is thrown when the backend rejects a login.
+ */
+export class InvalidCredentialsError extends Error {
+}
+/**
+ * UnauthorizedError is thrown when the backend rejects a request because
+ * the session is missing, expired, or revoked.
+ */
+export class UnauthorizedError extends Error {
+}
+/**
+ * RateLimitedError is thrown when the backend rejects a login for too many
+ * attempts.
+ */
+export class RateLimitedError extends Error {
+}
+/**
+ * Returns the logged-in user, or null when no session is active.
+ * @param signal - Aborts the in-flight request.
+ * @returns The current user, or null when unauthenticated.
+ */
+export async function fetchSession(signal) {
+    const response = await fetch('/api/auth/session', { signal });
+    if (response.status === 401) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(`loading session failed with status ${response.status}`);
+    }
+    return userSchema.parse(await response.json());
+}
+/**
+ * Logs in with the given credentials and returns the user.
+ * @param email - The account email address.
+ * @param password - The account password.
+ * @returns The authenticated user.
+ */
+export async function login(email, password) {
+    const response = await fetch('/api/auth/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, password }),
+    });
+    if (response.status === 401) {
+        throw new InvalidCredentialsError('invalid credentials');
+    }
+    if (response.status === 429) {
+        throw new RateLimitedError('too many login attempts');
+    }
+    if (!response.ok) {
+        throw new Error(`login failed with status ${response.status}`);
+    }
+    return userSchema.parse(await response.json());
+}
+/**
+ * Ends the current session.
+ */
+export async function logout() {
+    const response = await fetch('/api/auth/logout', { method: 'POST' });
+    if (!response.ok) {
+        throw new Error(`logout failed with status ${response.status}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { InvalidCredentialsError, RateLimitedError, UnauthorizedError, fetchSession, login, logout, } from './api';
+export type { User } from './api';
+export { AuthGate } from './AuthGate';
+export { isSessionRevoked } from './probe';
+export { createAuthQueryClient } from './queryClient';
+export { sessionQueryKey, useLogout, useSession } from './session';

package/dist/index.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+export { InvalidCredentialsError, RateLimitedError, UnauthorizedError, fetchSession, login, logout, } from './api';
+export { AuthGate } from './AuthGate';
+export { isSessionRevoked } from './probe';
+export { createAuthQueryClient } from './queryClient';
+export { sessionQueryKey, useLogout, useSession } from './session';

package/dist/probe.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Reports whether the backend considers the session gone, distinguishing
+ * a revoked login from a transient outage after a stream failure.
+ * @param signal - Aborts the in-flight request.
+ * @returns True when the session is revoked, false when the backend still
+ * accepts it.
+ */
+export declare function isSessionRevoked(signal?: AbortSignal): Promise<boolean>;

package/dist/probe.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Reports whether the backend considers the session gone, distinguishing
+ * a revoked login from a transient outage after a stream failure.
+ * @param signal - Aborts the in-flight request.
+ * @returns True when the session is revoked, false when the backend still
+ * accepts it.
+ */
+export async function isSessionRevoked(signal) {
+    const response = await fetch('/api/auth/session', {
+        credentials: 'include',
+        signal,
+    });
+    return response.status === 401;
+}

package/dist/queryClient.d.ts

@@ -0,0 +1,9 @@
+import { QueryClient } from '@tanstack/react-query';
+import type { DefaultOptions } from '@tanstack/react-query';
+/**
+ * Builds a query client that drops the cached session whenever a query
+ * or mutation fails with an UnauthorizedError so the login screen takes over.
+ * @param defaultOptions - Query and mutation defaults, mainly for tests.
+ * @returns The configured query client.
+ */
+export declare function createAuthQueryClient(defaultOptions?: DefaultOptions): QueryClient;

package/dist/queryClient.js

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+import { MutationCache, QueryCache, QueryClient } from '@tanstack/react-query';
+import { UnauthorizedError } from './api';
+import { sessionQueryKey } from './session';
+/**
+ * Builds a query client that drops the cached session whenever a query
+ * or mutation fails with an UnauthorizedError so the login screen takes over.
+ * @param defaultOptions - Query and mutation defaults, mainly for tests.
+ * @returns The configured query client.
+ */
+export function createAuthQueryClient(defaultOptions) {
+    const queryClient = new QueryClient({
+        defaultOptions,
+        queryCache: new QueryCache({ onError: dropExpiredSession }),
+        mutationCache: new MutationCache({ onError: dropExpiredSession }),
+    });
+    /**
+     * Clears the cached session when the backend reports it gone.
+     * @param error - The failure reported by a query or mutation.
+     */
+    function dropExpiredSession(error) {
+        if (error instanceof UnauthorizedError) {
+            queryClient.setQueryData(sessionQueryKey, null);
+        }
+    }
+    return queryClient;
+}

package/dist/session.d.ts

@@ -0,0 +1,19 @@
+/**
+ * sessionQueryKey is the react-query key the login session is cached under.
+ */
+export declare const sessionQueryKey: readonly ["session"];
+/**
+ * Loads the current session as a react-query result.
+ * @returns The session query, whose data is the user or null.
+ */
+export declare function useSession(): import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    id: string;
+    email: string;
+    name: string;
+} | null>, Error>;
+/**
+ * Ends the current session and drops all cached data belonging to the
+ * signed-out user.
+ * @returns The logout mutation.
+ */
+export declare function useLogout(): import("@tanstack/react-query").UseMutationResult<void, Error, void, unknown>;

package/dist/session.js

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+import { hashKey, useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { fetchSession, logout } from './api';
+/**
+ * sessionQueryKey is the react-query key the login session is cached under.
+ */
+export const sessionQueryKey = ['session'];
+/**
+ * Loads the current session as a react-query result.
+ * @returns The session query, whose data is the user or null.
+ */
+export function useSession() {
+    return useQuery({
+        queryKey: sessionQueryKey,
+        queryFn: ({ signal }) => fetchSession(signal),
+    });
+}
+/**
+ * Ends the current session and drops all cached data belonging to the
+ * signed-out user.
+ * @returns The logout mutation.
+ */
+export function useLogout() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: logout,
+        onSuccess: async () => {
+            await queryClient.cancelQueries();
+            queryClient.setQueryData(sessionQueryKey, null);
+            queryClient.removeQueries({
+                predicate: (query) => query.queryHash !== hashKey(sessionQueryKey),
+            });
+        },
+    });
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,66 @@
+import '@testing-library/jest-dom/vitest';
+import type { QueryClient } from '@tanstack/react-query';
+import type { User } from '../api';
+export { http, HttpResponse } from 'msw';
+export declare const server: import("msw/node").SetupServer;
+/**
+ * Installs the msw server lifecycle and DOM cleanup as vitest hooks.
+ */
+export declare function installTestEnvironment(): void;
+/**
+ * defaultUser is the canned account tests sign in as.
+ */
+export declare const defaultUser: User;
+/**
+ * Seeds the cached session so components render signed in without a fetch.
+ * @param client - The query client under test.
+ * @param user - The signed-in user, or null for a signed-out state.
+ */
+export declare function seedSession(client: QueryClient, user?: User | null): void;
+/**
+ * Answers the session endpoint with the given user.
+ * @param user - The user the session belongs to.
+ * @returns The msw handler.
+ */
+export declare function sessionOk(user?: User): import("msw").HttpHandler;
+/**
+ * Answers the session endpoint as signed out.
+ * @returns The msw handler.
+ */
+export declare function sessionAnonymous(): import("msw").HttpHandler;
+/**
+ * Fails the session endpoint with a server error.
+ * @returns The msw handler.
+ */
+export declare function sessionFailure(): import("msw").HttpHandler;
+/**
+ * Accepts any login with the given user.
+ * @param user - The user the login authenticates.
+ * @returns The msw handler.
+ */
+export declare function loginOk(user?: User): import("msw").HttpHandler;
+/**
+ * Rejects logins as invalid credentials.
+ * @returns The msw handler.
+ */
+export declare function loginInvalid(): import("msw").HttpHandler;
+/**
+ * Rejects logins as rate limited.
+ * @returns The msw handler.
+ */
+export declare function loginRateLimited(): import("msw").HttpHandler;
+/**
+ * Fails logins with a server error.
+ * @returns The msw handler.
+ */
+export declare function loginFailure(): import("msw").HttpHandler;
+/**
+ * Accepts logouts.
+ * @returns The msw handler.
+ */
+export declare function logoutOk(): import("msw").HttpHandler;
+/**
+ * Fails logouts with a server error.
+ * @returns The msw handler.
+ */
+export declare function logoutFailure(): import("msw").HttpHandler;

package/dist/testing/index.js

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import { HttpResponse, http } from 'msw';
+import { setupServer } from 'msw/node';
+import { afterAll, afterEach, beforeAll } from 'vitest';
+import { sessionQueryKey } from '../session';
+export { http, HttpResponse } from 'msw';
+export const server = setupServer();
+/**
+ * Installs the msw server lifecycle and DOM cleanup as vitest hooks.
+ */
+export function installTestEnvironment() {
+    beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+    afterEach(() => {
+        cleanup();
+        server.resetHandlers();
+    });
+    afterAll(() => server.close());
+}
+/**
+ * defaultUser is the canned account tests sign in as.
+ */
+export const defaultUser = {
+    id: '0198b2f0-0000-7000-8000-000000000001',
+    email: 'grace@example.com',
+    name: 'Grace Hopper',
+};
+/**
+ * Seeds the cached session so components render signed in without a fetch.
+ * @param client - The query client under test.
+ * @param user - The signed-in user, or null for a signed-out state.
+ */
+export function seedSession(client, user = defaultUser) {
+    client.setQueryData(sessionQueryKey, user);
+}
+/**
+ * Answers the session endpoint with the given user.
+ * @param user - The user the session belongs to.
+ * @returns The msw handler.
+ */
+export function sessionOk(user = defaultUser) {
+    return http.get('/api/auth/session', () => HttpResponse.json(user));
+}
+/**
+ * Answers the session endpoint as signed out.
+ * @returns The msw handler.
+ */
+export function sessionAnonymous() {
+    return http.get('/api/auth/session', () => HttpResponse.json({ error: 'no session' }, { status: 401 }));
+}
+/**
+ * Fails the session endpoint with a server error.
+ * @returns The msw handler.
+ */
+export function sessionFailure() {
+    return http.get('/api/auth/session', () => HttpResponse.json({ error: 'internal error' }, { status: 500 }));
+}
+/**
+ * Accepts any login with the given user.
+ * @param user - The user the login authenticates.
+ * @returns The msw handler.
+ */
+export function loginOk(user = defaultUser) {
+    return http.post('/api/auth/login', () => HttpResponse.json(user));
+}
+/**
+ * Rejects logins as invalid credentials.
+ * @returns The msw handler.
+ */
+export function loginInvalid() {
+    return http.post('/api/auth/login', () => HttpResponse.json({ error: 'invalid credentials' }, { status: 401 }));
+}
+/**
+ * Rejects logins as rate limited.
+ * @returns The msw handler.
+ */
+export function loginRateLimited() {
+    return http.post('/api/auth/login', () => HttpResponse.json({ error: 'too many login attempts' }, { status: 429 }));
+}
+/**
+ * Fails logins with a server error.
+ * @returns The msw handler.
+ */
+export function loginFailure() {
+    return http.post('/api/auth/login', () => HttpResponse.json({ error: 'internal error' }, { status: 500 }));
+}
+/**
+ * Accepts logouts.
+ * @returns The msw handler.
+ */
+export function logoutOk() {
+    return http.post('/api/auth/logout', () => new HttpResponse(null, { status: 204 }));
+}
+/**
+ * Fails logouts with a server error.
+ * @returns The msw handler.
+ */
+export function logoutFailure() {
+    return http.post('/api/auth/logout', () => HttpResponse.json({ error: 'internal error' }, { status: 500 }));
+}

package/dist/wpds/AccountPanel.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Renders the signed-in user's identity with a logout control, or nothing
+ * without an active session.
+ * @param className - Extra class names for the surrounding stack.
+ * @returns The account panel element, or null when signed out.
+ */
+export declare function AccountPanel({ className }: {
+    className?: string;
+}): import("react").JSX.Element | null;

package/dist/wpds/AccountPanel.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// SPDX-License-Identifier: Apache-2.0
+import { Button, Stack, Text } from '@wordpress/ui';
+import { useLogout, useSession } from '../session';
+/**
+ * Renders the signed-in user's identity with a logout control, or nothing
+ * without an active session.
+ * @param className - Extra class names for the surrounding stack.
+ * @returns The account panel element, or null when signed out.
+ */
+export function AccountPanel({ className }) {
+    const user = useSession().data;
+    const signOut = useLogout();
+    if (!user) {
+        return null;
+    }
+    return (_jsxs(Stack, { direction: "column", gap: "sm", className: className, children: [_jsx(Text, { children: user.name }), _jsx(Button, { variant: "outline", disabled: signOut.isPending, onClick: () => signOut.mutate(), children: "Log out" }), signOut.isError ? (_jsx(Text, { role: "alert", children: "Logout failed, please try again." })) : null] }));
+}

package/dist/wpds/LoginScreen.d.ts

@@ -0,0 +1,11 @@
+import type { User } from '../api';
+/**
+ * Renders the login form and reports the authenticated user upward.
+ * @param brand - The product name shown above the form.
+ * @param onLogin - Called with the user after a successful login.
+ * @returns The login screen element.
+ */
+export declare function LoginScreen({ brand, onLogin, }: {
+    brand: string;
+    onLogin: (user: User) => void | Promise<void>;
+}): import("react").JSX.Element;

package/dist/wpds/LoginScreen.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// SPDX-License-Identifier: Apache-2.0
+import { useMutation } from '@tanstack/react-query';
+import { Button, Card, InputControl, Stack, Text } from '@wordpress/ui';
+import { useState } from 'react';
+import { InvalidCredentialsError, RateLimitedError, login } from '../api';
+/**
+ * Maps a login attempt error to the message shown to the user.
+ * @param error - The error thrown by the login attempt.
+ * @returns The message to display.
+ */
+function loginErrorMessage(error) {
+    if (error instanceof InvalidCredentialsError) {
+        return 'Invalid email or password.';
+    }
+    if (error instanceof RateLimitedError) {
+        return 'Too many attempts. Please wait a minute and try again.';
+    }
+    return 'Login failed, please try again.';
+}
+/**
+ * Renders the login form and reports the authenticated user upward.
+ * @param brand - The product name shown above the form.
+ * @param onLogin - Called with the user after a successful login.
+ * @returns The login screen element.
+ */
+export function LoginScreen({ brand, onLogin, }) {
+    const [email, setEmail] = useState('');
+    const [password, setPassword] = useState('');
+    const attempt = useMutation({
+        mutationFn: () => login(email.trim(), password),
+        onSuccess: (user) => onLogin(user),
+    });
+    return (_jsx("div", { className: "gopherium-login", children: _jsx(Card.Root, { className: "gopherium-login__card", children: _jsx(Card.Content, { children: _jsx("form", { onSubmit: (event) => {
+                        event.preventDefault();
+                        attempt.mutate();
+                    }, children: _jsxs(Stack, { direction: "column", gap: "lg", children: [_jsx(Text, { variant: "heading-lg", render: _jsx("h1", {}), children: brand }), _jsx(InputControl, { label: "Email", type: "email", value: email, onChange: (event) => setEmail(event.target.value) }), _jsx(InputControl, { label: "Password", type: "password", value: password, onChange: (event) => setPassword(event.target.value) }), _jsx(Button, { type: "submit", disabled: email.trim() === '' || password === '' || attempt.isPending, children: "Log in" }), attempt.isError ? (_jsx(Text, { role: "alert", children: loginErrorMessage(attempt.error) })) : null] }) }) }) }) }));
+}

package/dist/wpds/NewUserScreen.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Renders the new user form, creating an account and reporting success
+ * upward, typically for the app to navigate back to its user list.
+ * @param onCreated - Called after the account is created.
+ * @returns The new user screen element.
+ */
+export declare function NewUserScreen({ onCreated, }: {
+    onCreated?: () => void | Promise<void>;
+}): import("react").JSX.Element;

package/dist/wpds/NewUserScreen.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// SPDX-License-Identifier: Apache-2.0
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { Button, InputControl, Stack, Text } from '@wordpress/ui';
+import { useState } from 'react';
+import { EmailTakenError, ValidationError, createUser, usersQueryKey } from '../admin';
+/**
+ * Maps a creation failure to the message shown under the form, surfacing
+ * the backend's explanation for rejected input.
+ * @param error - The error thrown by the create mutation.
+ * @returns The human-readable failure message.
+ */
+function createErrorMessage(error) {
+    if (error instanceof EmailTakenError) {
+        return 'That email is already in use.';
+    }
+    if (error instanceof ValidationError) {
+        return error.message;
+    }
+    return 'The user could not be created.';
+}
+/**
+ * Renders the new user form, creating an account and reporting success
+ * upward, typically for the app to navigate back to its user list.
+ * @param onCreated - Called after the account is created.
+ * @returns The new user screen element.
+ */
+export function NewUserScreen({ onCreated, }) {
+    const queryClient = useQueryClient();
+    const [email, setEmail] = useState('');
+    const [name, setName] = useState('');
+    const [password, setPassword] = useState('');
+    const create = useMutation({
+        mutationFn: () => createUser({ email: email.trim(), name: name.trim(), password }),
+        onSuccess: async () => {
+            await queryClient.invalidateQueries({ queryKey: usersQueryKey });
+            await onCreated?.();
+        },
+    });
+    return (_jsxs(Stack, { direction: "column", gap: "lg", children: [_jsx(Text, { variant: "heading-lg", render: _jsx("h1", {}), children: "New user" }), _jsx("form", { onSubmit: (event) => {
+                    event.preventDefault();
+                    create.mutate();
+                }, children: _jsxs(Stack, { direction: "column", gap: "md", children: [_jsx(InputControl, { label: "Email", type: "email", autoComplete: "off", value: email, onChange: (event) => setEmail(event.target.value) }), _jsx(InputControl, { label: "Name", autoComplete: "off", value: name, onChange: (event) => setName(event.target.value) }), _jsx(InputControl, { label: "Password", type: "password", autoComplete: "new-password", value: password, onChange: (event) => setPassword(event.target.value) }), _jsx(Button, { type: "submit", disabled: email.trim() === '' ||
+                                name.trim() === '' ||
+                                password === '' ||
+                                create.isPending, children: "Create user" }), create.isError ? (_jsx(Text, { role: "alert", children: createErrorMessage(create.error) })) : null] }) })] }));
+}

package/dist/wpds/UsersScreen.d.ts

@@ -0,0 +1,11 @@
+import type { ReactElement } from 'react';
+/**
+ * Renders the user administration screen: the account list with status and
+ * disable controls, plus an optional control to create a new user.
+ * @param newUserRender - The navigation element the New user button renders
+ * as, typically the app router's link to its create form.
+ * @returns The users screen, or a loading or error message.
+ */
+export declare function UsersScreen({ newUserRender, }: {
+    newUserRender?: ReactElement<Record<string, unknown>>;
+}): import("react").JSX.Element;

package/dist/wpds/UsersScreen.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// SPDX-License-Identifier: Apache-2.0
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Badge, Button, Stack, Text, VisuallyHidden } from '@wordpress/ui';
+import { fetchUsers, setUserDisabled, usersQueryKey } from '../admin';
+import { useSession } from '../session';
+/**
+ * Renders one user row with status and a disable toggle, hidden for the
+ * signed-in account.
+ * @param user - The user the row describes.
+ * @param isSelf - Whether the row is the signed-in account.
+ * @returns The table row element.
+ */
+function UserRow({ user, isSelf }) {
+    const queryClient = useQueryClient();
+    const toggle = useMutation({
+        mutationFn: () => setUserDisabled(user.id, !user.disabled),
+        onSuccess: () => queryClient.invalidateQueries({ queryKey: usersQueryKey }),
+    });
+    return (_jsxs("tr", { children: [_jsx("td", { children: user.name }), _jsx("td", { children: user.email }), _jsx("td", { children: _jsx(Badge, { intent: user.disabled ? 'draft' : 'stable', children: user.disabled ? 'Disabled' : 'Active' }) }), _jsx("td", { children: isSelf ? null : (_jsxs(Stack, { direction: "column", gap: "xs", children: [_jsx(Button, { variant: "outline", "aria-label": `${user.disabled ? 'Enable' : 'Disable'} ${user.name}`, disabled: toggle.isPending, onClick: () => toggle.mutate(), children: user.disabled ? 'Enable' : 'Disable' }), toggle.isError ? _jsx(Text, { role: "alert", children: "Update failed." }) : null] })) })] }));
+}
+/**
+ * Renders the user administration screen: the account list with status and
+ * disable controls, plus an optional control to create a new user.
+ * @param newUserRender - The navigation element the New user button renders
+ * as, typically the app router's link to its create form.
+ * @returns The users screen, or a loading or error message.
+ */
+export function UsersScreen({ newUserRender, }) {
+    const currentUserId = useSession().data?.id;
+    const users = useQuery({
+        queryKey: usersQueryKey,
+        queryFn: ({ signal }) => fetchUsers(signal),
+    });
+    if (users.isPending) {
+        return _jsx(Text, { role: "status", children: "Loading users\u2026" });
+    }
+    if (users.isError) {
+        return _jsx(Text, { role: "alert", children: "Users could not be loaded." });
+    }
+    return (_jsxs(Stack, { direction: "column", gap: "lg", children: [_jsxs(Stack, { direction: "row", align: "center", gap: "md", children: [_jsx(Text, { variant: "heading-lg", render: _jsx("h1", {}), children: "Users" }), newUserRender ? _jsx(Button, { render: newUserRender, children: "New user" }) : null] }), _jsxs("table", { className: "gopherium-users", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Name" }), _jsx("th", { scope: "col", children: "Email" }), _jsx("th", { scope: "col", children: "Status" }), _jsx("th", { scope: "col", children: _jsx(VisuallyHidden, { children: "Actions" }) })] }) }), _jsx("tbody", { children: users.data.map((user) => (_jsx(UserRow, { user: user, isSelf: user.id === currentUserId }, user.id))) })] })] }));
+}

package/dist/wpds/index.d.ts

@@ -0,0 +1,5 @@
+export { AccountPanel } from './AccountPanel';
+export { LoginScreen } from './LoginScreen';
+export { usersNavItem } from './nav';
+export { NewUserScreen } from './NewUserScreen';
+export { UsersScreen } from './UsersScreen';

package/dist/wpds/index.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+export { AccountPanel } from './AccountPanel';
+export { LoginScreen } from './LoginScreen';
+export { usersNavItem } from './nav';
+export { NewUserScreen } from './NewUserScreen';
+export { UsersScreen } from './UsersScreen';

package/dist/wpds/nav.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentProps, ReactElement } from 'react';
+/**
+ * usersNavItem is the ready-made navigation entry for the user
+ * administration screen.
+ */
+export declare const usersNavItem: {
+    label: string;
+    to: string;
+    icon: ReactElement<ComponentProps<'svg'>>;
+};

package/dist/wpds/nav.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+const usersIcon = (_jsx("svg", { viewBox: "0 0 24 24", xmlns: "http://www.w3.org/2000/svg", fill: "currentColor", children: _jsx("path", { d: "M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z" }) }));
+/**
+ * usersNavItem is the ready-made navigation entry for the user
+ * administration screen.
+ */
+export const usersNavItem = { label: 'Users', to: '/users', icon: usersIcon };

package/dist/wpds/style.css

@@ -0,0 +1,33 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+
+.gopherium-login {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	min-height: 100vh;
+	padding: 24px;
+	box-sizing: border-box;
+}
+
+.gopherium-login__card {
+	width: 100%;
+	max-width: 360px;
+}
+
+.gopherium-users {
+	width: 100%;
+	border-collapse: collapse;
+	text-align: left;
+}
+
+.gopherium-users th,
+.gopherium-users td {
+	padding: 8px 12px;
+	border-bottom: 1px solid var(--wpds-color-stroke-surface-neutral);
+	vertical-align: middle;
+}
+
+.gopherium-users th {
+	font-size: var(--wpds-typography-font-size-sm);
+	color: var(--wpds-color-foreground-content-neutral-weak);
+}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@gopherium/react-auth",
+  "version": "0.1.0",
+  "description": "Session authentication for React apps backed by gouncer's authkit.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gopherium/gouncer.git",
+    "directory": "react-auth"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./wpds": {
+      "types": "./dist/wpds/index.d.ts",
+      "default": "./dist/wpds/index.js"
+    },
+    "./wpds/style.css": "./dist/wpds/style.css",
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.101.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@wordpress/ui": "^0.17.0",
+    "msw": "^2.15.0",
+    "react": "^19.2.7",
+    "vitest": "^4.1.10"
+  },
+  "peerDependenciesMeta": {
+    "@testing-library/jest-dom": {
+      "optional": true
+    },
+    "@testing-library/react": {
+      "optional": true
+    },
+    "@wordpress/ui": {
+      "optional": true
+    },
+    "msw": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.101.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.2.17",
+    "@vitejs/plugin-react": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@wordpress/ui": "^0.17.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-jsdoc": "^63.0.13",
+    "eslint-plugin-tsdoc": "^0.4.0",
+    "jsdom": "^29.1.1",
+    "msw": "^2.15.0",
+    "oxlint": "^1.71.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && cp src/wpds/style.css dist/wpds/style.css",
+    "cover": "vitest run --coverage",
+    "lint": "oxlint"
+  }
+}