@eifi1/ui-kit 0.28.1 → 0.30.0

package/dist/auth/reset-password-form.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/auth/reset-password-form.tsx"],"sourcesContent":["import { useEffect, useId, useRef, useState } from \"react\";\nimport type { ComponentPropsWithoutRef, FormEvent, ReactNode } from \"react\";\nimport { CheckCircle2, XCircle } from \"lucide-react\";\nimport { cn } from \"../lib/cn\";\nimport { useKitLabels } from \"../i18n/kit-labels\";\nimport { AlertBanner } from \"../components/alert-banner\";\nimport { LoadingState } from \"../components/loading-state\";\nimport { Button, EmptyState } from \"../components/ui\";\nimport { authErrorCode, englishRateLimited, isRateLimited, retryAfterSeconds } from \"./auth-errors\";\nimport { newPasswordProblem } from \"./form-rules\";\nimport { NewPasswordFields } from \"./new-password-fields\";\nimport {\n  FORM_HEADING_CLASS,\n  INTRO_CLASS,\n  OUTCOME_CLASS,\n  OutcomeMessage,\n  useFocusWhen,\n  useOncePerKey,\n  withQuery,\n} from \"./status-parts\";\nimport type { AuthHeadingLevel } from \"./status-parts\";\n\n/* ── Labels ──────────────────────────────────────────────────────────────── */\n\n/** Every string the form renders — the `resetPassword` namespace. keksdose's words\n *  (`auth.reset.*`), which kastlan took over. */\nexport interface ResetPasswordLabels {\n  /** The heading, on every state. */\n  title: string;\n  /** While the link is checked. */\n  checking: string;\n  /** Over the fields, given the account's address (when the check returned one). */\n  intro: (email: string) => string;\n  newPassword: string;\n  confirmPassword: string;\n  /** Under the confirmation while it differs. */\n  mismatch: string;\n  submit: string;\n  /** The new password was not saved, for a reason that is not the link. */\n  failed: string;\n  /** The page was opened without a `token`. */\n  noToken: string;\n  /** The link is unknown, spent or expired — one sentence, as the server gives one\n   *  code (`token_invalid`). */\n  invalid: string;\n  /** Under it. */\n  invalidHint: string;\n  /** The way forward from an invalid link: back to \"Forgot password\". */\n  requestNew: string;\n  /** Done. */\n  success: string;\n  /** Under it: a reset ends every session (§6.3). */\n  sessionsEnded: string;\n  /** The button out — to sign-in, with the address filled in. */\n  signIn: string;\n  /** 0.30.0: the save was throttled — HTTP 429 ({@link isRateLimited}) — given the\n   *  `Retry-After` wait in seconds, or `undefined` without one. OPTIONAL, like every key\n   *  added to a shipped interface; the provider's `resetPassword`, then English, fill\n   *  it. */\n  rateLimited?: (seconds?: number) => string;\n}\n\n/** `Required`: every key, the 0.30 one included, has its English here. */\nexport const DEFAULT_RESET_PASSWORD_LABELS: Required<ResetPasswordLabels> = {\n  title: \"Choose a new password\",\n  checking: \"Checking the link…\",\n  intro: (email) => `You’re setting a new password for ${email}.`,\n  newPassword: \"New password\",\n  confirmPassword: \"Repeat new password\",\n  mismatch: \"The passwords don’t match.\",\n  submit: \"Save password\",\n  failed: \"The password could not be changed.\",\n  noToken: \"This link is incomplete.\",\n  invalid: \"This link is invalid or has expired.\",\n  invalidHint: \"Links are valid for one hour and work only once. Just request a new one.\",\n  requestNew: \"Request a new link\",\n  success: \"Your password has been changed. You can sign in with it now.\",\n  sessionsEnded: \"Signed-in devices were signed out — you’ll need to sign in again there.\",\n  signIn: \"Go to sign in\",\n  rateLimited: englishRateLimited,\n};\n\n/* ── Types ───────────────────────────────────────────────────────────────── */\n\n/** What `onCheck` may resolve with — keksdose's `/password-reset/check` answer. */\nexport interface ResetPasswordCheck {\n  /** The account's address: named over the fields (\"You're setting a new password for\n   *  …\") and handed to the password manager, which files the new password under it. */\n  email?: string;\n  /** The app's notices over the fields, shown BEFORE the password is typed — keksdose's\n   *  \"your account is end-to-end encrypted: this restores your sign-in, not your data\". */\n  notices?: ReactNode;\n}\n\n/** What `onSubmit` hands over. */\nexport interface ResetPasswordValues {\n  token: string;\n  password: string;\n}\n\n/** What `onSubmit` resolves with — keksdose's `/password-reset/confirm` answer, which\n *  carries no tokens (§6.3). */\nexport interface ResetPasswordResult {\n  /** The account's address — the sign-in it leads to is filled in with it. */\n  email: string;\n  /** The app's outcomes, shown on the done state: keksdose's recovery-code notice for an\n   *  encrypted account, \"Your 2 personal access tokens were revoked\". */\n  notices?: ReactNode;\n}\n\ntype Phase =\n  | { kind: \"form\"; check: ResetPasswordCheck }\n  | { kind: \"invalid\" }\n  | { kind: \"done\"; result: ResetPasswordResult };\n\nexport interface ResetPasswordFormProps\n  extends Omit<ComponentPropsWithoutRef<\"div\">, \"onSubmit\" | \"children\" | \"title\"> {\n  /** The link's token — the app's `?token=` (keksdose, kastlan: `/reset-password?token=…`).\n   *  Empty: the link was cut short, and the page says so without asking anyone. */\n  token: string;\n  /**\n   * Check the link before the form shows (`/auth/password-reset/check`) — once per\n   * token, on mount. Checking does not use it up, so a reload is free. Resolve (with\n   * the address and any notices) for a live link; reject for a dead one, and the page\n   * says \"This link is invalid or has expired\" with the way to a new one.\n   */\n  onCheck: (token: string) => Promise<ResetPasswordCheck | void | undefined>;\n  /**\n   * The new password was submitted: send `/auth/password-reset/confirm`. Resolve with\n   * the account's address (and the app's notices) — no tokens: a reset is not a sign-in\n   * (§6.3). Reject with the client's error: `token_invalid` (the link expired or was\n   * used in another tab while the form was open) goes to the invalid state; anything\n   * else stays on the form with the password kept.\n   */\n  onSubmit: (values: ResetPasswordValues) => Promise<ResetPasswordResult>;\n  /** \"Go to sign in\" calls this with the address, for an app that routes in code.\n   *  Without it, the button is a link to `signInHref`. */\n  onSignIn?: (email: string) => void;\n  /** Where \"Go to sign in\" leads, with `?email=` added — read it into `SignInForm`'s\n   *  `defaultEmail`. Default `/login`. */\n  signInHref?: string;\n  /** \"Request a new link\" — the app's \"Forgot password\" page. Default\n   *  `/forgot-password`. */\n  forgotHref?: string;\n  /** The app's words for a failed save (the device offline), or `undefined` for the\n   *  kit's: `rateLimited` for a bare `429` (0.30.0), else `failed`. Not asked for\n   *  `token_invalid`, which is a state. */\n  describeError?: (error: unknown) => ReactNode | undefined;\n  /** The heading. Default `labels.title`; `null` draws none, for a page that puts it\n   *  in `AuthLayout`'s `title` instead. */\n  title?: ReactNode;\n  /** The heading's level. Default `h2`, under the page's `h1`. */\n  headingAs?: AuthHeadingLevel;\n  labels?: Partial<ResetPasswordLabels>;\n}\n\n/**\n * Redeem a password-reset link (`/reset-password?token=…`, docs/auth-harmonization.md\n * §6.3, §7) — keksdose's `ResetPasswordPage` (features/auth/reset-password-page.tsx),\n * which kastlan built its own on.\n *\n * **The link is checked first** (`onCheck`), and only then does the form appear: an\n * expired link should say so before someone types a new password twice, not after.\n *\n * **A reset is not a sign-in** (§6.3, §10.11). The confirm answers without tokens, so a\n * 2FA account cannot skip its second factor by way of its inbox, and the page ends on\n * \"Go to sign in\" with the address filled in — the person has just typed the new\n * password twice; signing in is one step. What else the reset did is said there:\n * every other session ended (the kit's line, true in all three apps), and the app's own\n * outcomes in `notices` — keksdose's recovery-code notice and its revoked API tokens.\n *\n * **The password** is chosen with the same fields as `RegisterForm` and `SignInForm`'s\n * set-password step ({@link NewPasswordFields}): the strength meter and its checklist as\n * advice, and only the two hard rules — at least 8 characters, at most 72 bytes (§8).\n * The submit waits for both and a matching confirmation.\n *\n * The form never sends a request itself (§8): the token and the password go to the\n * callbacks, and the page renders what they resolve with.\n */\nexport function ResetPasswordForm({\n  token,\n  onCheck,\n  onSubmit,\n  onSignIn,\n  signInHref = \"/login\",\n  forgotHref = \"/forgot-password\",\n  describeError,\n  title,\n  headingAs: Heading = \"h2\",\n  labels: labelsProp,\n  className,\n  ...rest\n}: ResetPasswordFormProps) {\n  const labels = useKitLabels(\"resetPassword\", DEFAULT_RESET_PASSWORD_LABELS, labelsProp);\n  // The phase belongs to the token it was reached with: a new token starts over at the\n  // check without a reset effect.\n  const [phase, setPhase] = useState<{ token: string; phase: Phase } | null>(null);\n  const current: Phase | \"checking\" =\n    token === \"\" ? { kind: \"invalid\" } : phase?.token === token ? phase.phase : \"checking\";\n\n  useOncePerKey(token === \"\" ? null : token, onCheck, (key, result) =>\n    setPhase({\n      token: key,\n      phase: result.ok ? { kind: \"form\", check: result.value ?? {} } : { kind: \"invalid\" },\n    }),\n  );\n\n  const [password, setPassword] = useState(\"\");\n  const [confirm, setConfirm] = useState(\"\");\n  const [pending, setPending] = useState(false);\n  const [failure, setFailure] = useState<ReactNode>(null);\n  const headingId = useId();\n  const passwordRef = useRef<HTMLInputElement>(null);\n  const doneRef = useRef<HTMLDivElement>(null);\n  const kind = current === \"checking\" ? \"checking\" : current.kind;\n\n  // The form arrives after the check: the field is where the person is going.\n  useEffect(() => {\n    if (kind === \"form\") passwordRef.current?.focus();\n  }, [kind]);\n  useFocusWhen(kind === \"done\", doneRef);\n\n  const heading =\n    title === null ? null : (\n      <Heading id={headingId} className={FORM_HEADING_CLASS}>\n        {title ?? labels.title}\n      </Heading>\n    );\n  const rootClass = cn(\"space-y-3\", className);\n\n  if (current === \"checking\") {\n    return (\n      <div {...rest} data-state=\"checking\" aria-busy className={rootClass}>\n        {heading}\n        <LoadingState size=\"sm\" label={labels.checking} />\n      </div>\n    );\n  }\n\n  if (current.kind === \"invalid\") {\n    return (\n      <div {...rest} data-state=\"invalid\" className={rootClass}>\n        {heading}\n        <EmptyState\n          tone=\"danger\"\n          icon={<XCircle />}\n          title={token === \"\" ? labels.noToken : labels.invalid}\n          hint={labels.invalidHint}\n          action={\n            <Button href={forgotHref} variant=\"brand\">\n              {labels.requestNew}\n            </Button>\n          }\n          className={OUTCOME_CLASS}\n        />\n      </div>\n    );\n  }\n\n  if (current.kind === \"done\") {\n    const { email, notices } = current.result;\n    return (\n      <div {...rest} data-state=\"done\" className={rootClass}>\n        {heading}\n        <OutcomeMessage icon={<CheckCircle2 className=\"text-[var(--success)]\" />} focusRef={doneRef}>\n          <p className={INTRO_CLASS}>{labels.success}</p>\n        </OutcomeMessage>\n        {notices}\n        <p className=\"text-xs text-[var(--text-muted)]\">{labels.sessionsEnded}</p>\n        {onSignIn ? (\n          <Button type=\"button\" variant=\"brand\" className=\"w-full\" onClick={() => onSignIn(email)}>\n            {labels.signIn}\n          </Button>\n        ) : (\n          <Button href={email ? withQuery(signInHref, \"email\", email) : signInHref} variant=\"brand\" className=\"w-full\">\n            {labels.signIn}\n          </Button>\n        )}\n      </div>\n    );\n  }\n\n  const { email, notices } = current.check;\n  const problem = newPasswordProblem(password, confirm);\n\n  const submit = (e: FormEvent) => {\n    e.preventDefault();\n    if (pending || problem !== null) return;\n    setFailure(null);\n    setPending(true);\n    Promise.resolve()\n      .then(() => onSubmit({ token, password }))\n      .then(\n        (result) => {\n          setPending(false);\n          setPassword(\"\");\n          setConfirm(\"\");\n          setPhase({ token, phase: { kind: \"done\", result } });\n        },\n        (error: unknown) => {\n          setPending(false);\n          if (authErrorCode(error) === \"token_invalid\") {\n            setPassword(\"\");\n            setConfirm(\"\");\n            setPhase({ token, phase: { kind: \"invalid\" } });\n            return;\n          }\n          // The app's words first, then the throttle's, then the kit's catch-all.\n          setFailure(\n            describeError?.(error) ??\n              (isRateLimited(error)\n                ? (labels.rateLimited ?? DEFAULT_RESET_PASSWORD_LABELS.rateLimited)(retryAfterSeconds(error))\n                : labels.failed),\n          );\n        },\n      );\n  };\n\n  return (\n    <div {...rest} data-state=\"form\" className={rootClass}>\n      <form className=\"space-y-3\" aria-labelledby={title === null ? undefined : headingId} onSubmit={submit}>\n        {heading}\n        {email ? <p className={INTRO_CLASS}>{labels.intro(email)}</p> : null}\n        {notices}\n        {/* Which account the new password is for, for the password manager: it files\n            the new password under this username instead of guessing (kastlan). */}\n        {email ? <input type=\"email\" name=\"username\" autoComplete=\"username\" value={email} readOnly hidden /> : null}\n        <NewPasswordFields\n          password={password}\n          confirm={confirm}\n          onPasswordChange={(next) => {\n            setPassword(next);\n            if (failure) setFailure(null);\n          }}\n          onConfirmChange={setConfirm}\n          busy={pending}\n          passwordRef={passwordRef}\n          text={{ password: labels.newPassword, confirm: labels.confirmPassword, mismatch: labels.mismatch }}\n        />\n        {failure != null && (\n          <AlertBanner tone=\"danger\" size=\"sm\" role=\"alert\">\n            {failure}\n          </AlertBanner>\n        )}\n        <Button type=\"submit\" className=\"w-full\" disabled={!pending && problem !== null} pending={pending}>\n          {labels.submit}\n        </Button>\n      </form>\n    </div>\n  );\n}\n"],"mappings":"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","names":["email","notices"]}

package/dist/auth/sign-in-form.d.ts

@@ -0,0 +1,295 @@
+import * as react from 'react';
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+
+/**
+ * What a sign-in call answers, in the kit's words — docs/auth-harmonization.md §5.1,
+ * keksdose's three shapes. The app maps its own HTTP answer to one of these and resolves
+ * with it; a refusal REJECTS (with whatever its client throws — {@link authErrorCode}
+ * reads the code out of it).
+ *
+ * | the server answers (keksdose) | resolve with |
+ * |---|---|
+ * | `TokenResponse` `{access_token, refresh_token, token_type, user}` | `{ kind: "signed-in" }`, after the app has stored the session |
+ * | `{requires_2fa: true, challenge_token}` | `{ kind: "2fa", challengeToken: challenge_token }` |
+ * | `{requires_password_change: true, challenge_token, encrypted}` | `{ kind: "password-change", challengeToken: challenge_token, extra: { encrypted } }` |
+ * | `401 {code: "invalid_credentials"}` | reject — let the client's error through |
+ *
+ * ```ts
+ * async function toAnswer(res: TokenResponse | TwoFactorChallenge | PasswordChangeChallenge): Promise<SignInAnswer> {
+ *   if ("requires_2fa" in res) return { kind: "2fa", challengeToken: res.challenge_token };
+ *   if ("requires_password_change" in res)
+ *     return { kind: "password-change", challengeToken: res.challenge_token, extra: { encrypted: res.encrypted } };
+ *   await onLoginSuccess(res); // store tokens, load /auth/me, switch language
+ *   return { kind: "signed-in" };
+ * }
+ * <SignInForm onSubmit={async (v) => toAnswer(await authApi.login(v))} … />
+ * ```
+ *
+ * The same mapping serves `/auth/login/2fa`, `/auth/login/set-password` and the passkey
+ * finish, which answer the same union.
+ */
+type SignInAnswer = {
+    kind: "signed-in";
+} | {
+    kind: "2fa";
+    challengeToken: string;
+} | {
+    kind: "password-change";
+    challengeToken: string;
+    /** The challenge's app fields, passed through untouched — keksdose's `encrypted`,
+     *  which its note on this step reads (`passwordChangeContent`). */
+    extra?: Readonly<Record<string, unknown>>;
+};
+/** The step on screen: the credentials, the second factor, or a new password. */
+type SignInStep = "credentials" | "2fa" | "password-change";
+/** What the person did when a call failed — {@link SignInFormProps.describeError}'s
+ *  second argument. */
+type SignInAction = "password" | "passkey" | "code" | "set-password";
+interface SignInCredentials {
+    /** Trimmed. Lower-casing is the server's (§3.1). */
+    email: string;
+    /** As typed, never trimmed. */
+    password: string;
+}
+interface SignInCodeValues {
+    challengeToken: string;
+    /** Digits only — {@link OneTimeCodeInput} drops the spaces of "123 456". A backup code
+     *  (`kind: "recovery"`) is trimmed and otherwise as typed: its dashes and case are the
+     *  server's to normalise, as kastlan's `_normalise_backup_code` does. */
+    code: string;
+    /**
+     * 0.30.0: `"recovery"` when the person typed one of their backup codes instead
+     * (`recoveryCode`); absent for the authenticator's code, as before. kastlan's
+     * `/auth/login/2fa` takes either in the same `code` and tells them apart itself; an
+     * app whose server takes a backup code elsewhere routes on this.
+     */
+    kind?: "recovery";
+}
+interface SignInNewPasswordValues {
+    challengeToken: string;
+    password: string;
+}
+/**
+ * Every string `SignInForm` renders — the `signIn` namespace of `<UiKitProvider
+ * labels>`, overridable per instance through `labels`. keksdose's words where it has
+ * them (`auth.*` in its catalogue).
+ */
+interface SignInLabels {
+    email: string;
+    password: string;
+    /** The submit button. */
+    submit: string;
+    /** The passkey button (`onPasskey`). */
+    passkey: string;
+    /** The link to `forgotHref`. */
+    forgotPassword: string;
+    /** Before the link to `registerHref`. */
+    noAccount: string;
+    /** The link to `registerHref`. */
+    register: string;
+    /** The ONE answer to an unknown address, a wrong password and a deactivated account
+     *  (`invalid_credentials`, §5.2). */
+    invalidCredentials: string;
+    /** Any other failed sign-in (the network, a 500). */
+    failed: string;
+    /** A failed or refused passkey sign-in. */
+    passkeyFailed: string;
+    /**
+     * The hint under `invalidCredentials` (§2.10), shown when `deactivatedContact` is
+     * given. A TEMPLATE: `{contact}` is replaced by the contact — a `mailto:` link for an
+     * address — so a language puts it where its grammar needs it.
+     */
+    deactivatedHint: string;
+    /** The hint under `invalidCredentials` when `emailTag` is given (§4.5), given the
+     *  typed address with the app's tag: "Signed up with ada+kastlan@example.com?". */
+    tagHint: (taggedAddress: string) => string;
+    /** The second-factor step's heading. */
+    twoFactorTitle: string;
+    twoFactorIntro: string;
+    /** The code field's label. */
+    code: string;
+    /** The code step's submit button. */
+    verify: string;
+    /** The code was refused. */
+    codeInvalid: string;
+    /** The set-a-new-password step's heading. */
+    setPasswordTitle: string;
+    setPasswordIntro: string;
+    newPassword: string;
+    confirmPassword: string;
+    passwordMismatch: string;
+    /** The set-a-new-password step's submit button. */
+    setPasswordSubmit: string;
+    setPasswordFailed: string;
+    /** A challenge was refused as `token_invalid` — it expired between the steps; the
+     *  form is back on the credentials. */
+    expired: string;
+    /** From the second and third step back to the credentials. */
+    backToSignIn: string;
+    /** The second-factor step's switch to a backup code (`recoveryCode`). */
+    useRecoveryCode?: string;
+    /** The switch back, from the backup-code field to the authenticator's code. */
+    useAuthenticatorCode?: string;
+    /** The backup-code field's label. */
+    recoveryCode?: string;
+    /** The step's intro while a backup code is asked for, in place of `twoFactorIntro`. */
+    recoveryIntro?: string;
+    /** Under the backup-code field, given how many letters and digits a code has. */
+    recoveryCodeHint?: (length: number) => string;
+    /** A refused backup code — wrong, or spent already (each one works once). */
+    recoveryCodeInvalid?: string;
+    /** Any step's request was throttled — HTTP 429 ({@link isRateLimited}) — given the
+     *  wait its `Retry-After` asks for, in seconds ({@link retryAfterSeconds}), or
+     *  `undefined` (or `0`) without one. */
+    rateLimited?: (seconds?: number) => string;
+}
+/** `Required`: every key, the 0.30 ones included, has its English here. */
+declare const DEFAULT_SIGN_IN_LABELS: Required<SignInLabels>;
+interface SignInFormProps extends Omit<ComponentPropsWithoutRef<"div">, "onSubmit" | "children"> {
+    /**
+     * The credentials step was submitted. Send them, and resolve with the answer
+     * ({@link SignInAnswer}) or reject with the client's error. The form never sends a
+     * request itself (§8): keksdose must see the password on its way, to refuse the same
+     * string as an encryption passphrase later.
+     *
+     * On `signed-in` the form's job is over — it stays busy while the app navigates.
+     */
+    onSubmit: (credentials: SignInCredentials) => Promise<SignInAnswer>;
+    /** The second factor was submitted (`/auth/login/2fa`). Resolves with the next answer
+     *  — keksdose may still require a new password after the code. */
+    onCode: (values: SignInCodeValues) => Promise<SignInAnswer>;
+    /** The new password was submitted (`/auth/login/set-password`). Resolves with the
+     *  answer, `signed-in` in practice; keksdose's `key_wrap_unchanged` note is the app's
+     *  to show from here. */
+    onSetPassword: (values: SignInNewPasswordValues) => Promise<SignInAnswer>;
+    /**
+     * The passkey button was pressed: run the ceremony (`/auth/passkey/login/begin|finish`)
+     * and resolve with its answer. It asks for NO email — a passkey is bound to the site,
+     * and the browser offers every one it holds (keksdose #126). Left out, no button: pass
+     * it only where `PublicKeyCredential` exists.
+     */
+    onPasskey?: () => Promise<SignInAnswer>;
+    /**
+     * Passkey autofill (conditional mediation). The email field is
+     * `autoComplete="username webauthn"`, so a pending `navigator.credentials.get({
+     * mediation: "conditional" })` lists the site's passkeys in its dropdown. The form
+     * calls this ONCE on mount; arm the request there and resolve with its answer when the
+     * person picks a passkey, or with `null` when nothing happens. The signal aborts on
+     * unmount — cancel the pending request then (keksdose: `armPasskeyAutofill(onDone,
+     * signal)` + `cancelPasskeyAutofill()`). A rejection is silent: the button stays the
+     * reliable path.
+     */
+    passkeyAutofill?: (signal: AbortSignal) => Promise<SignInAnswer | null | undefined>;
+    /** "Forgot your password?" goes here — the app's `/forgot-password`. Left out, no
+     *  link. */
+    forgotHref?: string;
+    /** "No account yet? Create account" goes here — `/register`. Left out, no line. */
+    registerHref?: string;
+    /** The email field's start value — the reset page ends on "Sign in" with the address
+     *  filled in (§6.3). */
+    defaultEmail?: string;
+    /**
+     * The app's address tag (`"kastlan"`, §4.5). After `invalid_credentials` the form also
+     * says "Signed up with you+kastlan@example.com? Use that address." — sign-in stays
+     * exact, and the server looks nothing up.
+     */
+    emailTag?: string;
+    /**
+     * Who a deactivated user writes to (§2.10): an address (drawn as a `mailto:` link) or
+     * the app's own node. Shown after `invalid_credentials` as "Account deactivated? Write
+     * to …". Left out, no hint.
+     */
+    deactivatedContact?: ReactNode;
+    /** Digits of the second factor. Default 6 (TOTP). */
+    codeLength?: number;
+    /**
+     * 0.30.0: offer a backup code on the second-factor step (kastlan's 0.29 adoption: its
+     * `/auth/login/2fa` takes one of the eight codes minted at 2FA setup, and the kit's
+     * step had no way to type one). A "Use a backup code" switch under the code field
+     * swaps the digits-only {@link OneTimeCodeInput} for a plain text field; the code goes
+     * to `onCode` with the same challenge and `kind: "recovery"`.
+     *
+     * `true` for a 16-character code (kastlan's `ABCD-EFGH-JKLM-NPQR`), or `{ length }`.
+     * The length counts letters and digits only — the dashes and spaces a printed code is
+     * grouped with don't count — and "Verify" waits for it. Left out, no switch.
+     */
+    recoveryCode?: boolean | {
+        length?: number;
+    };
+    /** App content at the top of the credentials step — a notice, a demo button. */
+    credentialsContent?: ReactNode;
+    /**
+     * App content on the second-factor step, under its intro. 0.30.0: pass a function and
+     * it gets the challenge token — kastlan kept its own copy of the token for a "lost
+     * your device?" link, which the step now hands over.
+     */
+    twoFactorContent?: ReactNode | ((challengeToken: string) => ReactNode);
+    /**
+     * App content on the set-a-new-password step, under its intro — keksdose's
+     * private-mode note ("Your encrypted data is untouched …"), which depends on the
+     * challenge: pass a function and it gets the challenge's `extra`.
+     */
+    passwordChangeContent?: ReactNode | ((extra: Readonly<Record<string, unknown>> | undefined) => ReactNode);
+    /**
+     * The app's own words for a failure, or `undefined` for the kit's: the device being
+     * offline, a throttle with its wait ("try again in an hour"). Asked first, for every
+     * failure; what it returns replaces the message, and the `invalid_credentials` hints
+     * still follow. A bare `429` needs none since 0.30.0: the kit says `rateLimited`.
+     */
+    describeError?: (error: unknown, action: SignInAction) => ReactNode | undefined;
+    /** The step changed — retitle the page (`AuthLayout`'s `title`) if the app wants. */
+    onStepChange?: (step: SignInStep) => void;
+    /** The level of the second and third step's heading. Default `h2`, under the page's
+     *  `h1`; one level under `AuthLayout`'s `headingAs` where that is embedded lower. */
+    headingAs?: "h2" | "h3" | "h4" | "h5" | "h6";
+    labels?: Partial<SignInLabels>;
+}
+/**
+ * Sign-in for every app (docs/auth-harmonization.md §5, §8): email and password, or a
+ * passkey; then the second factor when it is on; then a new password when an admin
+ * required one. keksdose's `LoginPage` and `ForcedPasswordChangeStep`
+ * (features/auth/login-page.tsx, forced-password-change.tsx), as one component.
+ *
+ * **It never sends a request.** Each step hands its input to a callback and renders the
+ * {@link SignInAnswer} it resolves with; a rejection is shown in the step it came from.
+ * The challenge token lives in this component's state only, as in keksdose, so a reload
+ * costs a fresh sign-in — no route, no storage.
+ *
+ * **One error for every wrong credential** (§2.10, §5.2): `invalid_credentials` shows one
+ * sentence, whatever was wrong, plus two hints UNDER it — "Account deactivated? Write to
+ * …" (`deactivatedContact`) and "Signed up with you+kastlan@…? Use that address."
+ * (`emailTag`). Any other failure says "Sign-in failed" and no hint: the hints answer a
+ * refused credential, not a network that is down. `describeError` puts the app's words
+ * on a failure the kit cannot know (a throttled attempt).
+ *
+ * **The steps.**
+ *  - Credentials: the email field is `username webauthn` (passkey autofill, see
+ *    `passkeyAutofill`), the password a `CurrentPasswordInput` (a password manager fills
+ *    it and never offers a new one). The submit is not disabled while the fields are
+ *    empty: a browser that autofills on load withholds the values until the first
+ *    interaction, and a disabled button would swallow that first click. The fields'
+ *    own `required` answers an empty submit instead. "Forgot your password?" sits under
+ *    the buttons, where someone whose password just failed is already looking
+ *    (keksdose #198).
+ *  - Second factor: {@link OneTimeCodeInput}, focused on arrival. "Verify" waits for the
+ *    whole code. A refused code stays here with its error; `token_invalid` (the
+ *    challenge expired) goes back to the credentials and says why. Kurvenschmiede has
+ *    no 2FA yet, and the step is here from the start, so adding it is backend work only
+ *    (§10.5). With `recoveryCode` (0.30.0) a switch under the field takes a backup code
+ *    instead, through the same `onCode` with `kind: "recovery"`.
+ *
+ * **A throttled request** (HTTP 429, {@link isRateLimited}) says "Too many attempts. Try
+ * again in 30 s." on any step (0.30.0) — the wait from its `Retry-After`, else "Wait a
+ * moment and try again." — after `describeError`, whose words still come first, and
+ * instead of "wrong password" or "invalid code", which would send the person to try
+ * another one.
+ *  - New password: new + confirm with the strength meter, the 8-character / 72-byte
+ *    rules and nothing else (§8). It reads as explained, not blocked (keksdose): the
+ *    person did nothing wrong.
+ *
+ * The password is dropped from state once the credentials are answered; "Back to sign in"
+ * returns to an empty password field.
+ */
+declare function SignInForm({ onSubmit, onCode, onSetPassword, onPasskey, passkeyAutofill, forgotHref, registerHref, defaultEmail, emailTag, deactivatedContact, codeLength, recoveryCode, credentialsContent, twoFactorContent, passwordChangeContent, describeError, onStepChange, headingAs: Heading, labels: labelsProp, className, ...rest }: SignInFormProps): react.JSX.Element;
+
+export { DEFAULT_SIGN_IN_LABELS, type SignInAction, type SignInAnswer, type SignInCodeValues, type SignInCredentials, SignInForm, type SignInFormProps, type SignInLabels, type SignInNewPasswordValues, type SignInStep };