core/auth/ui/README.md

# auth-ui

`auth-ui` is the server-rendered login, registration, account, password-change, and OAuth login surface for the dodo stack. It proxies existing Ory Kratos browser flows and integrates Ory Hydra login/consent challenges.

## Local development

Go 1.22 or newer is required. From this directory:

```sh
make format        # rewrite all Go source with gofmt
make format-check  # report formatting drift without changing files
make test          # untagged unit/helper tests
make test-race     # untagged tests with the race detector
make vet           # untagged package vet
make check         # source-only format, unit, race, vet, and build checks
make build         # write ./server
```

`GO` and `GOFMT` may be overridden, for example `make GO=/path/to/go test`. `make check` does not install or launch Chromium, Kratos, or Hydra and does not download E2E runtimes.

The executable requires reachable Kratos and Hydra services. See `./server -h` for the current listener and upstream flags; browser registration is disabled unless `-enable-registration` is set.

## End-to-end tests

The tagged suite starts isolated native Kratos, Hydra, auth-ui, Playwright, and Chromium processes on loopback ports. Detailed pinned versions, cache locations, and troubleshooting are in [`e2e/README.md`](e2e/README.md).

```sh
make install-e2e-browser       # install the pinned managed Chromium
make install-e2e-browser-deps  # also install Linux host packages; may require privileges
make test-e2e                  # online-capable full suite; installs/checks Chromium first
make test-e2e-offline          # full suite using already populated caches only
```

Use a separate artifact destination when retaining a release run:

```sh
AUTH_UI_E2E_ARTIFACT_DIR="$(mktemp -d)" make test-e2e
```

The default Ory cache is `e2e/cache/`; the default retained run location is `e2e/artifacts/`. Screenshots, video, traces, session metadata, and service logs can contain synthetic passwords, cookies, OAuth challenges, authorization codes, or tokens. Treat all E2E artifacts as sensitive, keep them out of Git, restrict access, and delete them after review. `make clean-e2e-artifacts` removes only the default artifact directory, not an override or any cache.

## Browser behavior and assets

The product uses native HTML forms and full-page navigation. It ships no product JavaScript: labels, source order, links, buttons, browser validation, server feedback, and CSS focus styles are the complete interaction model. Login uses the native `username` and `current-password` autocomplete purposes; registration and password change use `new-password`.

All runtime styles are repository-owned in `static/base.css` and `static/main.css`. Pages do not load Pico, a web font, a CDN stylesheet, or another external frontend dependency. The UI remains usable when script execution is unavailable because no interaction depends on script.

## Current password policy

One shared Go validator is used by browser registration, browser password change, and `POST /identities`. A password must:

- contain at least **20 bytes** (this is a UTF-8 byte count, not a character count);
- contain at least one Unicode digit;
- contain at least one Unicode lowercase letter;
- contain at least one Unicode uppercase letter; and
- contain at least one ASCII space or one character from this exact ASCII punctuation allowlist:

```text
!"#$%&'()*+,-./:;<=>?@[\]^_{|}~
```

The forms intentionally have one password field, no confirmation field, and no HTML `minlength`, `maxlength`, or `pattern`, because those native constraints cannot exactly reproduce the shared byte/Unicode policy.

## OAuth consent

OAuth consent is automatic. After successful Hydra login, auth-ui accepts all scopes requested in the existing consent challenge and continues to the client callback; there is no consent page, scope selector, allow button, or reject button. This documents current behavior, not a recommendation or a new policy.

## Unavailable and deferred work

This UI does not provide account recovery/forgot-password, email verification, MFA, passkeys, social or passwordless login, account deletion, session management, current-password reauthentication, or interactive OAuth consent.

Security hardening is deliberately deferred and must not be inferred from the UX or E2E gates. [`FOLLOW_UP_SECURITY_ISSUES.md`](FOLLOW_UP_SECURITY_ISSUES.md) is a backlog covering TLS verification, redirect/`return_to` validation, logout CSRF, identity API authentication/exposure, request and response bounds, sensitive logging, cookie/response headers, and production-like security topology. Those items are not implemented by this release. Loopback E2E proves functional compatibility, not production transport or origin security.

Automated checks cover Chromium keyboard, semantics, responsive viewports, and a 640×360 reflow proxy. They are not evidence of physical-device behavior, a screen-reader pass, native autofill activation, or manual browser zoom at 200%.