@gopherium/react-auth 0.12.0 → 0.14.0

package/README.md

@@ -10,7 +10,10 @@ Session authentication for React apps backed by gouncer's authkit.
 - `@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
+  `NewUserScreen`, `usersNavItem`, `SetupCodeStep`, which asks for
+  the one-time setup code as Jenkins' "Unlock Jenkins" does, and
+  `SetupAccountStep`, the account rows of WordPress's installer with
+  its password strength meter. Import
   `@gopherium/react-auth/wpds/style.css` alongside it.
 - `@gopherium/react-auth/testing` is the msw harness: `server`,
   `installTestEnvironment`, `seedSession`, `defaultUser`, and canned
@@ -28,6 +31,38 @@ const client = createAuthQueryClient()
 </QueryClientProvider>
 ```
 
+## Setup wizard rows
+
+`SetupAccountStep` shows the wizard's own rows in `before`, above
+Name, and in `after`, below Your Email. They line up with the step's
+rows only when they use the same hooks:
+
+- `className="gopherium-setup__row"` on each row.
+- `render={<div />}` on `Field.Root`, so the row adds no gap of its
+  own.
+- `className="gopherium-setup__label"` on the row's label.
+- `className="gopherium-setup__checkbox"` on a `CheckboxControl`.
+- `className="gopherium-setup__help"` on a help line under the field.
+
+A checkbox row is a plain `<div className="gopherium-setup__row">`
+with a `Field.VisualLabel`, as the step's Confirm Password row is.
+
+```tsx
+<SetupAccountStep
+  code={code}
+  submitLabel="Install MyApp"
+  onCreated={onCreated}
+  before={
+    <Field.Root className="gopherium-setup__row" render={<div />}>
+      <Field.Label className="gopherium-setup__label">Site Title</Field.Label>
+      <div>
+        <Input value={title} onChange={(event) => setTitle(event.target.value)} />
+      </div>
+    </Field.Root>
+  }
+/>
+```
+
 ## Consumer requirements
 
 - `react` and `@tanstack/react-query` are peer dependencies; the app
@@ -37,6 +72,9 @@ const client = createAuthQueryClient()
   development, proxy `/api` to your backend so the `__Host-` session
   cookie is first-party.
 - `/wpds` needs the `@wordpress/ui` peer.
+- The account step loads zxcvbn, about 400 kB gzipped, as its own chunk
+  the first time it renders. Vite reports that chunk as larger than
+  500 kB.
 
 ## License
 

package/dist/account.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+/** The account the server answers for a listed or created user. */
+export declare const accountSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodString;
+    name: z.ZodString;
+    disabled: z.ZodBoolean;
+    role: z.ZodDefault<z.ZodString>;
+    created_at: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+/** Account is a user account as the server answers it. */
+export type Account = z.infer<typeof accountSchema>;

package/dist/account.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+/** The account the server answers for a listed or created user. */
+export const accountSchema = z.object({
+    id: z.string(),
+    email: z.string(),
+    name: z.string(),
+    disabled: z.boolean(),
+    role: z.string().default(''),
+    created_at: z.coerce.date(),
+});

package/dist/admin/index.d.ts

@@ -1,15 +1,8 @@
 import { z } from 'zod';
+import type { Account as User } from '../account.js';
 import { ValidationError } from '../api.js';
 export declare const usersQueryKey: readonly ["users"];
-declare const userSchema: z.ZodObject<{
-    id: z.ZodString;
-    email: z.ZodString;
-    name: z.ZodString;
-    disabled: z.ZodBoolean;
-    role: z.ZodDefault<z.ZodString>;
-    created_at: z.ZodCoercedDate<unknown>;
-}, z.core.$strip>;
-export type User = z.infer<typeof userSchema>;
+export type { Account as User } from '../account.js';
 export interface NewUser {
     email: string;
     name: string;

package/dist/admin/index.js

@@ -1,18 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 import { __ } from '@wordpress/i18n';
 import { z } from 'zod';
+import { accountSchema } from '../account.js';
 import { RateLimitedError, UnauthorizedError, ValidationError } from '../api.js';
 import { DOMAIN } from '../domain.js';
 import { resolveTransport } from '../transport.js';
 export const usersQueryKey = ['users'];
-const userSchema = z.object({
-    id: z.string(),
-    email: z.string(),
-    name: z.string(),
-    disabled: z.boolean(),
-    role: z.string().default(''),
-    created_at: z.coerce.date(),
-});
 const invitationSchema = z.discriminatedUnion('delivered', [
     z.object({ delivered: z.literal(true) }),
     z.object({ delivered: z.literal(false), activation_link: z.string().trim().min(1) }),
@@ -125,7 +118,7 @@ async function restFetchUsers(signal) {
     if (!response.ok) {
         throw new Error(`listing users failed with status ${response.status}`);
     }
-    return z.array(userSchema).parse(await response.json());
+    return z.array(accountSchema).parse(await response.json());
 }
 /**
  * Creates an account over REST.
@@ -147,7 +140,7 @@ async function restCreateUser(input) {
     if (!response.ok) {
         throw await writeError(response, __('invalid user details', DOMAIN), 'creating user');
     }
-    return userSchema.parse(await response.json());
+    return accountSchema.parse(await response.json());
 }
 /**
  * Sends an invitation over REST, answering the same shape whatever the

package/dist/api.d.ts

@@ -31,12 +31,31 @@ export declare class RateLimitedError extends Error {
  */
 export declare class InvalidTokenError extends Error {
 }
-/**
- * ValidationError is thrown when the backend rejects submitted details;
- * its message is the backend's human-readable explanation.
- */
+/** ValidationError is thrown when the backend rejects submitted details, with its message, code and meta. */
 export declare class ValidationError extends Error {
+    readonly code?: string;
+    readonly meta?: Record<string, unknown>;
+    /**
+     * Creates the error from the backend's refusal.
+     * @param message - The backend's human-readable explanation.
+     * @param refusal - The refusal's code and meta, when the backend sent them.
+     */
+    constructor(message: string, refusal?: {
+        code?: string;
+        meta?: Record<string, unknown>;
+    });
 }
+/**
+ * Reads the backend's refusal from a failed response body.
+ * @param response - The failed HTTP response.
+ * @param fallback - The message to use when the body is unreadable.
+ * @returns The refusal message with its optional code and meta.
+ */
+export declare function refusalOf(response: Response, fallback: string): Promise<{
+    message: string;
+    code?: string;
+    meta?: Record<string, unknown>;
+}>;
 /**
  * Returns the logged-in user, or null when no session is active.
  * @param signal - Aborts the in-flight request.

package/dist/api.js

@@ -34,23 +34,36 @@ export class RateLimitedError extends Error {
  */
 export class InvalidTokenError extends Error {
 }
-/**
- * ValidationError is thrown when the backend rejects submitted details;
- * its message is the backend's human-readable explanation.
- */
+/** ValidationError is thrown when the backend rejects submitted details, with its message, code and meta. */
 export class ValidationError extends Error {
+    code;
+    meta;
+    /**
+     * Creates the error from the backend's refusal.
+     * @param message - The backend's human-readable explanation.
+     * @param refusal - The refusal's code and meta, when the backend sent them.
+     */
+    constructor(message, refusal = {}) {
+        super(message);
+        this.code = refusal.code;
+        this.meta = refusal.meta;
+    }
 }
-const refusalSchema = z.object({ error: z.string(), code: z.string().optional() });
+const refusalSchema = z.object({
+    error: z.string(),
+    code: z.string().optional(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+});
 /**
  * Reads the backend's refusal from a failed response body.
  * @param response - The failed HTTP response.
  * @param fallback - The message to use when the body is unreadable.
- * @returns The refusal message and optional code.
+ * @returns The refusal message with its optional code and meta.
  */
-async function refusalOf(response, fallback) {
+export async function refusalOf(response, fallback) {
     try {
         const held = refusalSchema.parse(await response.json());
-        return { message: held.error, code: held.code };
+        return { message: held.error, code: held.code, meta: held.meta };
     }
     catch {
         return { message: fallback };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export type { Account } from './account.js';
 export { InvalidCredentialsError, InvalidTokenError, RateLimitedError, UnauthorizedError, ValidationError, acceptInvite, fetchSession, login, logout, requestPasswordReset, resetPassword, } from './api.js';
 export type { User } from './api.js';
 export { AuthGate } from './AuthGate.js';
@@ -8,5 +9,7 @@ export type { Catalog } from './languages.js';
 export { isSessionRevoked } from './probe.js';
 export { createAuthQueryClient } from './queryClient.js';
 export { adoptSession, sessionQueryKey, useLogout, useSession } from './session.js';
+export { SetupClosedError, SetupCodeError, SiteStartingError, checkSetupCode, createFirstAccount, isSetupOpen, } from './setup.js';
+export type { FirstAccount } from './setup.js';
 export { configureAuthTransport, resetAuthTransport } from './transport.js';
 export type { AuthTransport } from './transport.js';

package/dist/index.js

@@ -7,4 +7,5 @@ export { catalogFor } from './languages.js';
 export { isSessionRevoked } from './probe.js';
 export { createAuthQueryClient } from './queryClient.js';
 export { adoptSession, sessionQueryKey, useLogout, useSession } from './session.js';
+export { SetupClosedError, SetupCodeError, SiteStartingError, checkSetupCode, createFirstAccount, isSetupOpen, } from './setup.js';
 export { configureAuthTransport, resetAuthTransport } from './transport.js';

package/dist/languages/es-ES.json

@@ -1 +1 @@
-{ "": { "lang": "es-ES", "plural-forms": "nplurals=2; plural=(n != 1);" }, "Actions": ["Acciones"], "Active": ["Activo"], "Back to login": ["Volver al inicio de sesión"], "Disable": ["Desactivar"], "Disable %s": ["Desactivar a %s"], "Disabled": ["Desactivado"], "Done": ["Hecho"], "Enable": ["Activar"], "Enable %s": ["Activar a %s"], "Forgot your password?": ["¿Has olvidado tu contraseña?"], "Go to login": ["Ir al inicio de sesión"], "If that address has an account, a reset link is on its way.": ["Si esa dirección tiene una cuenta, le llegará un enlace para restablecerla."], "Invalid email or password.": ["Correo o contraseña no válidos."], "Loading users…": ["Cargando usuarios…"], "Loading…": ["Cargando…"], "Log in": ["Iniciar sesión"], "Log out": ["Cerrar sesión"], "Login failed, please try again.": ["No se pudo iniciar sesión, inténtalo de nuevo."], "Logout failed, please try again.": ["No se pudo cerrar sesión, inténtalo de nuevo."], "No mail server is configured. Deliver the activation link by hand.": ["No hay servidor de correo configurado. Entrega el enlace de activación a mano."], "Password": ["Contraseña"], "Send invitation": ["Enviar invitación"], "Send reset link": ["Enviar enlace de restablecimiento"], "Set password": ["Guardar contraseña"], "Something went wrong.": ["Algo ha ido mal."], "The invitation could not be sent.": ["No se pudo enviar la invitación."], "The password could not be set, please try again.": ["No se pudo guardar la contraseña, inténtalo de nuevo."], "The request failed, please try again.": ["No se pudo completar la petición, inténtalo de nuevo."], "This link is no longer valid. Ask for a new one.": ["Este enlace ya no es válido. Pide uno nuevo."], "This link is no longer valid. Ask the person who invited you for a new one.": ["Este enlace ya no es válido. Pide uno nuevo a quien te invitó."], "Too many attempts. Please wait a minute and try again.": ["Demasiados intentos. Espera un minuto e inténtalo de nuevo."], "Try again": ["Inténtalo de nuevo"], "Update failed.": ["No se pudo actualizar."], "Users could not be loaded.": ["No se pudieron cargar los usuarios."], "Your password is set. Sign in with it.": ["Tu contraseña está guardada. Inicia sesión con ella."], "admin section\u0004Users": ["Usuarios"], "button\u0004New user": ["Nuevo usuario"], "column\u0004Email": ["Correo"], "column\u0004Name": ["Nombre"], "column\u0004Status": ["Estado"], "field label\u0004Activation link": ["Enlace de activación"], "field label\u0004Email": ["Correo"], "field label\u0004Name": ["Nombre"], "invalid invitation details": ["datos de invitación no válidos"], "invalid password details": ["datos de contraseña no válidos"], "invalid user details": ["datos de usuario no válidos"], "page heading\u0004New user": ["Nuevo usuario"], "page heading\u0004Users": ["Usuarios"], "the account could not be updated": ["no se ha podido actualizar la cuenta"] }
+{ "": { "lang": "es-ES", "plural-forms": "nplurals=3; plural=((n == 1) ? 0 : ((n != 0 && n % 1000000 == 0) ? 1 : 2));" }, "Actions": ["Acciones"], "Active": ["Activo"], "Back to login": ["Volver al inicio de sesión"], "Caps lock is on.": ["El bloqueo de mayúsculas está activado."], "Confirm Password": ["Confirma la contraseña"], "Confirm use of weak password": ["Confirma el uso de una contraseña débil."], "Continue": ["Continuar"], "Disable": ["Desactivar"], "Disable %s": ["Desactivar a %s"], "Disabled": ["Desactivado"], "Done": ["Hecho"], "Double-check your email address before continuing.": ["Comprueba bien tu dirección de correo electrónico antes de continuar."], "Enable": ["Activar"], "Enable %s": ["Activar a %s"], "Go to login": ["Ir al inicio de sesión"], "Hide": ["Ocultar"], "Hide password": ["Ocultar la contraseña"], "Hint: The password should be at least %d character long. To make it stronger, use upper and lower case letters, numbers, and symbols like ! \" ? $ %% ^ & ).": ["Sugerencia: La contraseña debe ser de al menos %d carácter. Para hacerla más fuerte usa mayúsculas y minúsculas, números y símbolos como ! \" ? $ %% ^ y ).", "Sugerencia: La contraseña debe ser de al menos %d de caracteres. Para hacerla más fuerte usa mayúsculas y minúsculas, números y símbolos como ! \" ? $ %% ^ y ).", "Sugerencia: La contraseña debe ser de al menos %d caracteres. Para hacerla más fuerte usa mayúsculas y minúsculas, números y símbolos como ! \" ? $ %% ^ y )."], "If that address has an account, a reset link is on its way.": ["Si esa dirección tiene una cuenta, le llegará un enlace para restablecerla."], "Important:": ["Importante:"], "Invalid email or password.": ["Correo o contraseña no válidos."], "Loading users…": ["Cargando usuarios…"], "Loading…": ["Cargando…"], "Log in": ["Iniciar sesión"], "Log out": ["Cerrar sesión"], "Login failed, please try again.": ["No se pudo iniciar sesión, inténtalo de nuevo."], "Logout failed, please try again.": ["No se pudo cerrar sesión, inténtalo de nuevo."], "Lost your password?": ["¿Has olvidado tu contraseña?"], "No mail server is configured. Deliver the activation link by hand.": ["No hay servidor de correo configurado. Entrega el enlace de activación a mano."], "Password": ["Contraseña"], "Please copy the setup code from the file and paste it below.": ["Por favor, copia el código de configuración del archivo y pégalo abajo."], "Please provide a name.": ["Por favor, facilita un nombre."], "Send invitation": ["Enviar invitación"], "Send reset link": ["Enviar enlace de restablecimiento"], "Set password": ["Guardar contraseña"], "Setup code": ["Código de configuración"], "Show": ["Mostrar"], "Show password": ["Mostrar la contraseña"], "Something went wrong.": ["Algo ha ido mal."], "Sorry, that is not a valid email address. Email addresses look like <code>username@example.com</code>.": ["Lo siento, esa no es una dirección de correo electrónico válida. Las direcciones de correo electrónico deben parecerse a <code>usuario@example.com</code>."], "The account could not be created, please try again.": ["No se pudo crear la cuenta, inténtalo de nuevo."], "The invitation could not be sent.": ["No se pudo enviar la invitación."], "The password could not be set, please try again.": ["No se pudo guardar la contraseña, inténtalo de nuevo."], "The request failed, please try again.": ["No se pudo completar la petición, inténtalo de nuevo."], "The setup code file cannot be used. Please check it and try again.": ["No se puede usar el archivo del código de configuración. Por favor, revísalo e inténtalo de nuevo."], "The site is starting. Please wait a moment and try again.": ["El sitio se está iniciando. Por favor, espera un momento e inténtalo de nuevo."], "This link is no longer valid. Ask for a new one.": ["Este enlace ya no es válido. Pide uno nuevo."], "This link is no longer valid. Ask the person who invited you for a new one.": ["Este enlace ya no es válido. Pide uno nuevo a quien te invitó."], "This name is too long.": ["Este nombre es demasiado largo."], "This password is too long.": ["Esta contraseña es demasiado larga."], "To ensure this site is securely set up by its owner, a setup code has been written to a file on the server.": ["Para garantizar que la persona propietaria configure este sitio de forma segura, se ha escrito un código de configuración en un archivo del servidor."], "Too many attempts. Please try again later.": ["Demasiados intentos. Por favor, inténtalo de nuevo más tarde."], "Too many attempts. Please wait a minute and try again.": ["Demasiados intentos. Espera un minuto e inténtalo de nuevo."], "Try again": ["Inténtalo de nuevo"], "Unlock %s": ["Desbloquear %s"], "Update failed.": ["No se pudo actualizar."], "Users could not be loaded.": ["No se pudieron cargar los usuarios."], "You appear to have already set up this site.": ["Parece que ya has configurado este sitio."], "You will need this password to log in. Please store it in a secure location.": ["Necesitas esta contraseña para acceder. Por favor, guárdala en un lugar seguro."], "Your Email": ["Tu correo electrónico"], "Your password is set. Sign in with it.": ["Tu contraseña está guardada. Inicia sesión con ella."], "Your setup code appears to be invalid. Please copy it again from the setup code file.": ["Tu código de configuración parece que no es válido. Por favor, cópialo de nuevo del archivo del código de configuración."], "Your setup code has expired. A new one is waiting in the setup code file.": ["Tu código de configuración ha caducado. Hay uno nuevo esperando en el archivo del código de configuración."], "admin section\u0004Users": ["Usuarios"], "button\u0004New user": ["Nuevo usuario"], "column\u0004Email": ["Correo"], "column\u0004Name": ["Nombre"], "column\u0004Status": ["Estado"], "field label\u0004Activation link": ["Enlace de activación"], "field label\u0004Email": ["Correo"], "field label\u0004Name": ["Nombre"], "invalid invitation details": ["datos de invitación no válidos"], "invalid password details": ["datos de contraseña no válidos"], "invalid user details": ["datos de usuario no válidos"], "page heading\u0004New user": ["Nuevo usuario"], "page heading\u0004Users": ["Usuarios"], "password strength\u0004Medium": ["Medio"], "password strength\u0004Password strength unknown": ["Fortaleza de la contraseña desconocida"], "password strength\u0004Strong": ["Fuerte"], "password strength\u0004Very weak": ["Muy débil"], "password strength\u0004Weak": ["Débil"], "the account could not be updated": ["no se ha podido actualizar la cuenta"] }

package/dist/languages/languages/es-ES.json

@@ -1 +1 @@
-{"":{"lang":"es-ES","plural-forms":"nplurals=2; plural=(n != 1);"},"Actions":["Acciones"],"Active":["Activo"],"Back to login":["Volver al inicio de sesión"],"Disable":["Desactivar"],"Disable %s":["Desactivar a %s"],"Disabled":["Desactivado"],"Done":["Hecho"],"Enable":["Activar"],"Enable %s":["Activar a %s"],"Forgot your password?":["¿Has olvidado tu contraseña?"],"Go to login":["Ir al inicio de sesión"],"If that address has an account, a reset link is on its way.":["Si esa dirección tiene una cuenta, le llegará un enlace para restablecerla."],"Invalid email or password.":["Correo o contraseña no válidos."],"Loading users…":["Cargando usuarios…"],"Loading…":["Cargando…"],"Log in":["Iniciar sesión"],"Log out":["Cerrar sesión"],"Login failed, please try again.":["No se pudo iniciar sesión, inténtalo de nuevo."],"Logout failed, please try again.":["No se pudo cerrar sesión, inténtalo de nuevo."],"No mail server is configured. Deliver the activation link by hand.":["No hay servidor de correo configurado. Entrega el enlace de activación a mano."],"Password":["Contraseña"],"Send invitation":["Enviar invitación"],"Send reset link":["Enviar enlace de restablecimiento"],"Set password":["Guardar contraseña"],"Something went wrong.":["Algo ha ido mal."],"The invitation could not be sent.":["No se pudo enviar la invitación."],"The password could not be set, please try again.":["No se pudo guardar la contraseña, inténtalo de nuevo."],"The request failed, please try again.":["No se pudo completar la petición, inténtalo de nuevo."],"This link is no longer valid. Ask for a new one.":["Este enlace ya no es válido. Pide uno nuevo."],"This link is no longer valid. Ask the person who invited you for a new one.":["Este enlace ya no es válido. Pide uno nuevo a quien te invitó."],"Too many attempts. Please wait a minute and try again.":["Demasiados intentos. Espera un minuto e inténtalo de nuevo."],"Try again":["Inténtalo de nuevo"],"Update failed.":["No se pudo actualizar."],"Users could not be loaded.":["No se pudieron cargar los usuarios."],"Your password is set. Sign in with it.":["Tu contraseña está guardada. Inicia sesión con ella."],"admin section\u0004Users":["Usuarios"],"button\u0004New user":["Nuevo usuario"],"column\u0004Email":["Correo"],"column\u0004Name":["Nombre"],"column\u0004Status":["Estado"],"field label\u0004Activation link":["Enlace de activación"],"field label\u0004Email":["Correo"],"field label\u0004Name":["Nombre"],"invalid invitation details":["datos de invitación no válidos"],"invalid password details":["datos de contraseña no válidos"],"invalid user details":["datos de usuario no válidos"],"page heading\u0004New user":["Nuevo usuario"],"page heading\u0004Users":["Usuarios"],"the account could not be updated":["no se ha podido actualizar la cuenta"]}
+{"":{"lang":"es-ES","plural-forms":"nplurals=3; plural=((n == 1) ? 0 : ((n != 0 && n % 1000000 == 0) ? 1 : 2));"},"Actions":["Acciones"],"Active":["Activo"],"Back to login":["Volver al inicio de sesión"],"Caps lock is on.":["El bloqueo de mayúsculas está activado."],"Confirm Password":["Confirma la contraseña"],"Confirm use of weak password":["Confirma el uso de una contraseña débil."],"Continue":["Continuar"],"Disable":["Desactivar"],"Disable %s":["Desactivar a %s"],"Disabled":["Desactivado"],"Done":["Hecho"],"Double-check your email address before continuing.":["Comprueba bien tu dirección de correo electrónico antes de continuar."],"Enable":["Activar"],"Enable %s":["Activar a %s"],"Go to login":["Ir al inicio de sesión"],"Hide":["Ocultar"],"Hide password":["Ocultar la contraseña"],"Hint: The password should be at least %d character long. To make it stronger, use upper and lower case letters, numbers, and symbols like ! \" ? $ %% ^ & ).":["Sugerencia: La contraseña debe ser de al menos %d carácter. Para hacerla más fuerte usa mayúsculas y minúsculas, números y símbolos como ! \" ? $ %% ^ y ).","Sugerencia: La contraseña debe ser de al menos %d de caracteres. Para hacerla más fuerte usa mayúsculas y minúsculas, números y símbolos como ! \" ? $ %% ^ y ).","Sugerencia: La contraseña debe ser de al menos %d caracteres. Para hacerla más fuerte usa mayúsculas y minúsculas, números y símbolos como ! \" ? $ %% ^ y )."],"If that address has an account, a reset link is on its way.":["Si esa dirección tiene una cuenta, le llegará un enlace para restablecerla."],"Important:":["Importante:"],"Invalid email or password.":["Correo o contraseña no válidos."],"Loading users…":["Cargando usuarios…"],"Loading…":["Cargando…"],"Log in":["Iniciar sesión"],"Log out":["Cerrar sesión"],"Login failed, please try again.":["No se pudo iniciar sesión, inténtalo de nuevo."],"Logout failed, please try again.":["No se pudo cerrar sesión, inténtalo de nuevo."],"Lost your password?":["¿Has olvidado tu contraseña?"],"No mail server is configured. Deliver the activation link by hand.":["No hay servidor de correo configurado. Entrega el enlace de activación a mano."],"Password":["Contraseña"],"Please copy the setup code from the file and paste it below.":["Por favor, copia el código de configuración del archivo y pégalo abajo."],"Please provide a name.":["Por favor, facilita un nombre."],"Send invitation":["Enviar invitación"],"Send reset link":["Enviar enlace de restablecimiento"],"Set password":["Guardar contraseña"],"Setup code":["Código de configuración"],"Show":["Mostrar"],"Show password":["Mostrar la contraseña"],"Something went wrong.":["Algo ha ido mal."],"Sorry, that is not a valid email address. Email addresses look like <code>username@example.com</code>.":["Lo siento, esa no es una dirección de correo electrónico válida. Las direcciones de correo electrónico deben parecerse a <code>usuario@example.com</code>."],"The account could not be created, please try again.":["No se pudo crear la cuenta, inténtalo de nuevo."],"The invitation could not be sent.":["No se pudo enviar la invitación."],"The password could not be set, please try again.":["No se pudo guardar la contraseña, inténtalo de nuevo."],"The request failed, please try again.":["No se pudo completar la petición, inténtalo de nuevo."],"The setup code file cannot be used. Please check it and try again.":["No se puede usar el archivo del código de configuración. Por favor, revísalo e inténtalo de nuevo."],"The site is starting. Please wait a moment and try again.":["El sitio se está iniciando. Por favor, espera un momento e inténtalo de nuevo."],"This link is no longer valid. Ask for a new one.":["Este enlace ya no es válido. Pide uno nuevo."],"This link is no longer valid. Ask the person who invited you for a new one.":["Este enlace ya no es válido. Pide uno nuevo a quien te invitó."],"This name is too long.":["Este nombre es demasiado largo."],"This password is too long.":["Esta contraseña es demasiado larga."],"To ensure this site is securely set up by its owner, a setup code has been written to a file on the server.":["Para garantizar que la persona propietaria configure este sitio de forma segura, se ha escrito un código de configuración en un archivo del servidor."],"Too many attempts. Please try again later.":["Demasiados intentos. Por favor, inténtalo de nuevo más tarde."],"Too many attempts. Please wait a minute and try again.":["Demasiados intentos. Espera un minuto e inténtalo de nuevo."],"Try again":["Inténtalo de nuevo"],"Unlock %s":["Desbloquear %s"],"Update failed.":["No se pudo actualizar."],"Users could not be loaded.":["No se pudieron cargar los usuarios."],"You appear to have already set up this site.":["Parece que ya has configurado este sitio."],"You will need this password to log in. Please store it in a secure location.":["Necesitas esta contraseña para acceder. Por favor, guárdala en un lugar seguro."],"Your Email":["Tu correo electrónico"],"Your password is set. Sign in with it.":["Tu contraseña está guardada. Inicia sesión con ella."],"Your setup code appears to be invalid. Please copy it again from the setup code file.":["Tu código de configuración parece que no es válido. Por favor, cópialo de nuevo del archivo del código de configuración."],"Your setup code has expired. A new one is waiting in the setup code file.":["Tu código de configuración ha caducado. Hay uno nuevo esperando en el archivo del código de configuración."],"admin section\u0004Users":["Usuarios"],"button\u0004New user":["Nuevo usuario"],"column\u0004Email":["Correo"],"column\u0004Name":["Nombre"],"column\u0004Status":["Estado"],"field label\u0004Activation link":["Enlace de activación"],"field label\u0004Email":["Correo"],"field label\u0004Name":["Nombre"],"invalid invitation details":["datos de invitación no válidos"],"invalid password details":["datos de contraseña no válidos"],"invalid user details":["datos de usuario no válidos"],"page heading\u0004New user":["Nuevo usuario"],"page heading\u0004Users":["Usuarios"],"password strength\u0004Medium":["Medio"],"password strength\u0004Password strength unknown":["Fortaleza de la contraseña desconocida"],"password strength\u0004Strong":["Fuerte"],"password strength\u0004Very weak":["Muy débil"],"password strength\u0004Weak":["Débil"],"the account could not be updated":["no se ha podido actualizar la cuenta"]}

package/dist/setup.d.ts

@@ -0,0 +1,46 @@
+import type { Account } from './account.js';
+/** FirstAccount is what the setup account step sends. */
+export interface FirstAccount {
+    code: string;
+    email: string;
+    name: string;
+    password: string;
+}
+/** SetupCodeError is thrown when the setup code is wrong, has expired, or its file cannot be used. */
+export declare class SetupCodeError extends Error {
+    readonly reason: 'invalid' | 'expired' | 'file';
+    /**
+     * Creates the error for the reason the site gave.
+     * @param reason - Why the site refused the code.
+     */
+    constructor(reason: 'invalid' | 'expired' | 'file');
+}
+/** SetupClosedError is thrown when the site already has its first account. */
+export declare class SetupClosedError extends Error {
+}
+/** SiteStartingError is thrown when the site answers 503 while it starts. */
+export declare class SiteStartingError extends Error {
+    readonly retryAfter?: number;
+    /**
+     * Creates the error with the wait the site asked for.
+     * @param retryAfter - The seconds the site asked to wait, if it said.
+     */
+    constructor(retryAfter?: number);
+}
+/**
+ * Reports whether the site still waits for its first account.
+ * @param signal - Aborts the in-flight request.
+ * @returns True while the site has no account.
+ */
+export declare function isSetupOpen(signal?: AbortSignal): Promise<boolean>;
+/**
+ * Resolves when the site accepts the one-time setup code, spending nothing.
+ * @param code - The setup code as typed.
+ */
+export declare function checkSetupCode(code: string): Promise<void>;
+/**
+ * Creates the site's first account with the one-time setup code.
+ * @param input - The setup code and the account's details.
+ * @returns The created account.
+ */
+export declare function createFirstAccount(input: FirstAccount): Promise<Account>;

package/dist/setup.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import { accountSchema } from './account.js';
+import { RateLimitedError, ValidationError, refusalOf } from './api.js';
+import { resolveTransport } from './transport.js';
+/** SetupCodeError is thrown when the setup code is wrong, has expired, or its file cannot be used. */
+export class SetupCodeError extends Error {
+    reason;
+    /**
+     * Creates the error for the reason the site gave.
+     * @param reason - Why the site refused the code.
+     */
+    constructor(reason) {
+        super(`the setup code was refused as ${reason}`);
+        this.reason = reason;
+    }
+}
+/** SetupClosedError is thrown when the site already has its first account. */
+export class SetupClosedError extends Error {
+}
+/** SiteStartingError is thrown when the site answers 503 while it starts. */
+export class SiteStartingError extends Error {
+    retryAfter;
+    /**
+     * Creates the error with the wait the site asked for.
+     * @param retryAfter - The seconds the site asked to wait, if it said.
+     */
+    constructor(retryAfter) {
+        super('the site is starting');
+        this.retryAfter = retryAfter;
+    }
+}
+/** The setup flag the site answers. */
+const statusSchema = z.object({ open: z.boolean() });
+/** The form a Retry-After header takes when it names seconds. */
+const SECONDS = /^\d+$/;
+const setupRefusals = new Map([
+    [401, (refusal) => new SetupCodeError(refusal.code === 'setup_code_expired' ? 'expired' : 'invalid')],
+    [409, () => new SetupClosedError('the site already has its first account')],
+    [422, (refusal) => new ValidationError(refusal.message, refusal)],
+    [429, () => new RateLimitedError('too many attempts')],
+    [500, (refusal) => (refusal.code === 'setup_code_file' ? new SetupCodeError('file') : undefined)],
+    [503, (_, response) => new SiteStartingError(retryAfterOf(response))],
+]);
+/**
+ * Returns the seconds a refused response asks to wait.
+ * @param response - The refused HTTP response.
+ * @returns The seconds, or undefined when its Retry-After header names none.
+ */
+function retryAfterOf(response) {
+    const held = response.headers.get('Retry-After')?.trim() ?? '';
+    return SECONDS.test(held) ? Number(held) : undefined;
+}
+/**
+ * Returns the error a refused setup request throws.
+ * @param response - The refused HTTP response.
+ * @returns The error to throw.
+ */
+async function setupRefusal(response) {
+    const refusal = await refusalOf(response, 'the setup request was refused');
+    return (setupRefusals.get(response.status)?.(refusal, response) ??
+        new Error(`the setup request failed with status ${response.status}`));
+}
+/**
+ * Posts a setup request over REST.
+ * @param path - The setup route.
+ * @param body - The fields the route reads.
+ * @returns The accepted response.
+ */
+async function postSetup(path, body) {
+    const response = await fetch(path, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        throw await setupRefusal(response);
+    }
+    return response;
+}
+/**
+ * Reads the setup flag over REST.
+ * @param signal - Aborts the in-flight request.
+ * @returns True while the site has no account.
+ */
+async function restIsSetupOpen(signal) {
+    const response = await fetch('/api/auth/setup', { signal });
+    if (!response.ok) {
+        throw new Error(`loading the setup state failed with status ${response.status}`);
+    }
+    return statusSchema.parse(await response.json()).open;
+}
+/**
+ * Checks the setup code over REST.
+ * @param code - The setup code as typed.
+ */
+async function restCheckSetupCode(code) {
+    await postSetup('/api/auth/setup/code', { code });
+}
+/**
+ * Creates the first account over REST.
+ * @param input - The setup code and the account's details.
+ * @returns The created account.
+ */
+async function restCreateFirstAccount(input) {
+    const { code, email, name, password } = input;
+    const response = await postSetup('/api/auth/setup', { code, email, name, password });
+    return accountSchema.parse(await response.json());
+}
+/**
+ * Reports whether the site still waits for its first account.
+ * @param signal - Aborts the in-flight request.
+ * @returns True while the site has no account.
+ */
+export async function isSetupOpen(signal) {
+    return resolveTransport('isSetupOpen', restIsSetupOpen)(signal);
+}
+/**
+ * Resolves when the site accepts the one-time setup code, spending nothing.
+ * @param code - The setup code as typed.
+ */
+export async function checkSetupCode(code) {
+    await resolveTransport('checkSetupCode', restCheckSetupCode)(code);
+}
+/**
+ * Creates the site's first account with the one-time setup code.
+ * @param input - The setup code and the account's details.
+ * @returns The created account.
+ */
+export async function createFirstAccount(input) {
+    return resolveTransport('createFirstAccount', restCreateFirstAccount)(input);
+}

package/dist/testing/index.d.ts

@@ -2,6 +2,7 @@ import '@testing-library/jest-dom/vitest';
 import type { QueryClient } from '@tanstack/react-query';
 import type { User } from '../api.js';
 export { http, HttpResponse } from 'msw';
+export { createdAccount, firstAccountClosed, firstAccountCodeRefused, firstAccountOk, firstAccountRateLimited, firstAccountStarting, setupCodeClosed, setupCodeOk, setupCodeRateLimited, setupCodeRefused, setupCodeStarting, setupStatus, } from './setup.js';
 export declare const server: import("msw/node").SetupServer;
 /**
  * Installs the msw server lifecycle and DOM cleanup as vitest hooks.

package/dist/testing/index.js

@@ -6,6 +6,7 @@ import { setupServer } from 'msw/node';
 import { afterAll, afterEach, beforeAll } from 'vitest';
 import { sessionQueryKey } from '../session.js';
 export { http, HttpResponse } from 'msw';
+export { createdAccount, firstAccountClosed, firstAccountCodeRefused, firstAccountOk, firstAccountRateLimited, firstAccountStarting, setupCodeClosed, setupCodeOk, setupCodeRateLimited, setupCodeRefused, setupCodeStarting, setupStatus, } from './setup.js';
 export const server = setupServer();
 /**
  * Installs the msw server lifecycle and DOM cleanup as vitest hooks.

package/dist/testing/setup.d.ts

@@ -0,0 +1,63 @@
+import type { Account } from '../account.js';
+import type { SetupCodeError } from '../setup.js';
+/** createdAccount is the canned first account a setup creates. */
+export declare const createdAccount: Account;
+/**
+ * Answers the setup state.
+ * @param open - Whether the site still waits for its first account.
+ * @returns The msw handler.
+ */
+export declare function setupStatus(open: boolean): import("msw").HttpHandler;
+/**
+ * Accepts a setup code check.
+ * @returns The msw handler.
+ */
+export declare function setupCodeOk(): import("msw").HttpHandler;
+/**
+ * Refuses a setup code check for the given reason.
+ * @param reason - Why the site refuses the code.
+ * @returns The msw handler.
+ */
+export declare function setupCodeRefused(reason: SetupCodeError['reason']): import("msw").HttpHandler;
+/**
+ * Refuses a setup code check as already set up.
+ * @returns The msw handler.
+ */
+export declare function setupCodeClosed(): import("msw").HttpHandler;
+/**
+ * Refuses a setup code check as rate limited.
+ * @returns The msw handler.
+ */
+export declare function setupCodeRateLimited(): import("msw").HttpHandler;
+/**
+ * Answers a setup code check as a site that is still starting.
+ * @returns The msw handler.
+ */
+export declare function setupCodeStarting(): import("msw").HttpHandler;
+/**
+ * Creates the first account as the given account.
+ * @param account - The account the site answers.
+ * @returns The msw handler.
+ */
+export declare function firstAccountOk(account?: Account): import("msw").HttpHandler;
+/**
+ * Refuses the first account's setup code for the given reason.
+ * @param reason - Why the site refuses the code.
+ * @returns The msw handler.
+ */
+export declare function firstAccountCodeRefused(reason: SetupCodeError['reason']): import("msw").HttpHandler;
+/**
+ * Refuses the first account as already set up.
+ * @returns The msw handler.
+ */
+export declare function firstAccountClosed(): import("msw").HttpHandler;
+/**
+ * Refuses the first account as rate limited.
+ * @returns The msw handler.
+ */
+export declare function firstAccountRateLimited(): import("msw").HttpHandler;
+/**
+ * Answers the first account as a site that is still starting.
+ * @returns The msw handler.
+ */
+export declare function firstAccountStarting(): import("msw").HttpHandler;