From c2ea8348df75428acc70931ece83a7c6474e8a60 Mon Sep 17 00:00:00 2001
From: Ned Wolpert <ned.wolpert@gmail.com>
Date: Fri, 19 Jun 2026 11:02:32 -0700
Subject: [PATCH] mini-console: design + Slice 0 runnable skeleton
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Graduate mini-console from roadmap placeholder to a runnable, admin-only
skeleton, and add the design docs that scope the work.

Design docs (docs/design/):
- mini-console.md — full design: operator console + exercise harness, five
  new HTTP client libs + reuse of the existing mini-kms client, the security
  model, and a slice-by-slice roadmap.
- mini-console-slice0.md — the Slice 0 implementation plan.
DIRECTION.md records mini-kms's client as the deliberate socket-era
exception (relocation considered and declined).

Slice 0 (services/mini-console/):
- Loopback HTTP server (virtual-thread-per-request), paste-the-console-token
  login minting a mini-token SessionService session under a distinct
  mini-console-session cookie, and an honest Dashboard ("n/a — client not
  wired yet" for each service; calls nothing downstream).
- Reuses the family http/ router kit + JsonStore + AdminAuthenticator +
  Cookies; no-oracle login, double-submit CSRF, loopback bind, no secrets in
  logs, session store written 0600.
- Fires the trip-wire: deletes MiniConsole.IMPLEMENTED (guard-only) and
  MiniConsoleTest, replaced by real ConsoleServer/ConsoleConfig tests.
- build.gradle.kts -> application-conventions (deps: mini-token + jackson
  only). settings.gradle.kts stale "roadmap placeholder" comment fixed.

mini-client-common is intentionally deferred to Slice 1 (driven by its first
real consumer); /api + OpenAPI are Slice 8. No new authority.

./gradlew build green family-wide.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/DIRECTION.md                             |  14 +
 docs/design/mini-console-slice0.md            | 258 ++++++++++++
 docs/design/mini-console.md                   | 371 ++++++++++++++++++
 services/mini-console/README.md               | 150 +++----
 services/mini-console/build.gradle.kts        |  21 +-
 .../miniconsole/MiniConsole.java              |  17 -
 .../miniconsole/ServerMain.java               |  87 ++++
 .../miniconsole/pages/DashboardPage.java      |  67 ++++
 .../miniconsole/pages/Layout.java             |  65 +++
 .../miniconsole/pages/LoginPage.java          |  38 ++
 .../server/AdminAuthenticator.java            |  76 ++++
 .../miniconsole/server/ConsoleConfig.java     | 145 +++++++
 .../miniconsole/server/ConsoleHandlers.java   | 131 +++++++
 .../miniconsole/server/ConsoleServer.java     |  73 ++++
 .../miniconsole/server/ConsoleSession.java    |  58 +++
 .../miniconsole/server/Cookies.java           |  59 +++
 .../miniconsole/server/Csrf.java              |  48 +++
 .../miniconsole/server/http/ApiException.java |  56 +++
 .../miniconsole/server/http/HttpResponse.java |  67 ++++
 .../miniconsole/server/http/Json.java         |  51 +++
 .../server/http/RequestContext.java           | 118 ++++++
 .../miniconsole/server/http/Router.java       | 143 +++++++
 .../miniconsole/store/JsonStore.java          | 100 +++++
 .../miniconsole/MiniConsoleTest.java          |  14 -
 .../miniconsole/server/ConsoleConfigTest.java |  68 ++++
 .../miniconsole/server/ConsoleServerTest.java | 180 +++++++++
 settings.gradle.kts                           |   6 +-
 27 files changed, 2337 insertions(+), 144 deletions(-)
 create mode 100644 docs/design/mini-console-slice0.md
 create mode 100644 docs/design/mini-console.md
 delete mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/MiniConsole.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/ServerMain.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/DashboardPage.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/Layout.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/LoginPage.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/AdminAuthenticator.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleConfig.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleHandlers.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleServer.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleSession.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/Cookies.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/Csrf.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/ApiException.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/HttpResponse.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/Json.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/RequestContext.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/Router.java
 create mode 100644 services/mini-console/src/main/java/com/codeheadsystems/miniconsole/store/JsonStore.java
 delete mode 100644 services/mini-console/src/test/java/com/codeheadsystems/miniconsole/MiniConsoleTest.java
 create mode 100644 services/mini-console/src/test/java/com/codeheadsystems/miniconsole/server/ConsoleConfigTest.java
 create mode 100644 services/mini-console/src/test/java/com/codeheadsystems/miniconsole/server/ConsoleServerTest.java

diff --git a/docs/DIRECTION.md b/docs/DIRECTION.md
index 3322de7..66269e2 100644
--- a/docs/DIRECTION.md
+++ b/docs/DIRECTION.md
@@ -213,6 +213,20 @@ the reverse), so the dependency graph stays acyclic. mini-idp and mini-oidc enab
 `MINI{IDP,OIDC}_KMS_API_TOKEN` / `--kms-api-token-file` — and fall back to the plaintext store when
 it is absent.
 
+> **mini-kms's client is the family's deliberate "client" exception — and it stays under
+> `services/`.** It is the original **socket**-era client (`KmsClient` + its single `KmsClientException`
+> + the `KmsSigningKeyStore` adapter, alongside the two CLIs `client`/`kms-admin`), written before the
+> family settled on the later **HTTP** client-lib pattern. Its embeddable surface is exactly
+> `{KmsClient, KmsClientException, KmsSigningKeyStore}`, consumed today by mini-idp, mini-oidc, and
+> mini-ca. Relocating it into a `libs/mini-kms-client` was considered and is mechanically clean
+> (behavior-preserving, graph stays acyclic), but it was **declined**: the benefit is cosmetic parity
+> with a not-yet-built `libs/<svc>-client` convention, against real churn in three shipping services.
+> Should a future service (e.g. **mini-console**) actually establish a `libs/<svc>-client` convention,
+> mini-kms's client is the **first candidate** to follow it — at which point the `KmsClient` library
+> would move to `libs/mini-kms-client` (with the CLIs staying behind in `:services:mini-kms:client`)
+> and consumers would repoint. Until then, consuming `:services:mini-kms:client` directly is correct,
+> not an oversight.
+
 ### Bootstrap ordering (and why it is not actually circular)
 
 There is an apparent chicken-and-egg: **mini-kms** needs its passphrase; the **auth services** need
diff --git a/docs/design/mini-console-slice0.md b/docs/design/mini-console-slice0.md
new file mode 100644
index 0000000..fd0a135
--- /dev/null
+++ b/docs/design/mini-console-slice0.md
@@ -0,0 +1,258 @@
+# Slice 0 — mini-console skeleton: implementation plan
+
+Slice 0 is **pure server-rendered HTML** — no `/api`, no OpenAPI, no SwaggerUI, no client libs, no
+mini-policy (those are Slice 1/8). It compiles, runs, serves a login + Dashboard behind a console
+session, and ships the trip-wire.
+
+**Confirmed decisions (maintainer):** default port **8500**; login error re-renders `/login` at
+**200** (no oracle); short "runnable skeleton" README note now + full rewrite at Slice 8; CSRF via
+**double-submit cookie**. `libs/mini-client-common` is **deferred to Slice 1**.
+
+## Headline decision
+
+**Defer `libs/mini-client-common` to Slice 1. Do NOT create it in Slice 0.** Slice 0 has **zero**
+real downstream calls (no client lib exists; the Dashboard renders "n/a — client not wired yet").
+Landing `mini-client-common` now means shipping an **unconsumed abstraction** whose API (token
+resolver shape, HttpClient builder signature, error-collapse type) would be guessed rather than
+driven by its first real consumer (the directory client in Slice 1) — the "scaffold that looks
+finished" the family ethos forbids. Slice 0 needs only env/file **console-token** resolution, a
+~12-line `resolveToken` copied from mini-oidc's `ServerMain`, local to the console module. When
+Slice 1 writes `MiniDirectoryClient` and needs the same plumbing for the *downstream* token +
+HttpClient, that is when `mini-client-common` is extracted, against a real caller.
+
+## Assumptions
+
+1. Console login uses a **paste-the-console-token-into-a-form** model (not a Bearer header) — the
+   operator is a human in a browser; a form+session is the right UX and lets the rest of the console
+   rely on a session cookie rather than re-presenting the token per request.
+2. The console session reuses mini-token's `SessionService` over a `JsonStore`
+   `DocumentStore<Sessions>`, with a **distinct cookie name** `mini-console-session` (mini-token's
+   `DEFAULT_COOKIE_NAME` is `"mioidc_session"`, `SessionService.java:31` — the console must NOT share
+   it, or it collides with a co-hosted mini-oidc SSO session).
+3. CSRF: one state-changing POST pair matters in Slice 0 (`/login`, `/logout`). A minimal `Csrf`
+   helper (double-submit cookie) is included now since `/login` genuinely needs it.
+4. Console token env var `MINICONSOLE_ADMIN_TOKEN` + `--admin-token-file` (mirrors the family's
+   `MINI*_ADMIN_TOKEN` + `--admin-token-file`).
+5. Default port **8500** (one above mini-ca's 8499).
+
+---
+
+## 1. Module graduation — `services/mini-console/build.gradle.kts`
+
+```kotlin
+/*
+ * mini-console - the optional unified admin console over the mini- family.
+ *
+ * Slice 0: the runnable skeleton — a loopback HTTP server, a console-login session, and a Dashboard
+ * that honestly reports "client not wired yet" for each downstream service (no client libs exist
+ * yet). It invents NO new authority; later slices add the per-service client libraries + pages.
+ *
+ * Graduates from library-conventions to application-conventions (it is now runnable).
+ */
+
+plugins {
+    id("miniauth.application-conventions")
+}
+
+dependencies {
+    // The shared browser-session mechanism (SessionService) + the DocumentStore SPI the copied
+    // JsonStore implements. This is the ONLY family dependency Slice 0 genuinely needs.
+    implementation(project(":libs:mini-token"))
+    // JSON for the session store document (Sessions) and any future page DTOs.
+    implementation(libs.jackson.databind)
+    // JUnit 5 (jupiter + launcher) is supplied by the convention plugin.
+}
+
+application {
+    mainClass = "com.codeheadsystems.miniconsole.ServerMain"
+}
+```
+
+**Not present in Slice 0:** no `libs.jackson.yaml` (no OpenAPI until Slice 8), no `:libs:mini-policy`,
+no client libs, no bouncycastle. Only `mini-token` + `jackson.databind`.
+
+---
+
+## 2. File-by-file creation list — `src/main/java/com/codeheadsystems/miniconsole/`
+
+Base package `com.codeheadsystems.miniconsole`. "Copy" = lift verbatim from the cited source, rename
+package to `…miniconsole.*`, adjust imports. "Fresh" = new code.
+
+### `ServerMain.java` — fresh (model: mini-oidc `ServerMain.java:41-113`)
+- `main(String[] args)` → `run(args, System.getenv())`, catch + exit-1 on config error.
+- `run`: `ConsoleConfig.resolve(args, env)`; `resolveToken(env.get("MINICONSOLE_ADMIN_TOKEN"),
+  config.adminTokenFilePath(), …)`; `ConsoleServer.create(config, consoleToken, Clock.systemUTC())`;
+  `start()`; await shutdown latch.
+- `resolveToken(String fromEnv, Path file, String missing)` — copy verbatim from
+  `ServerMain.java:101-113` (env → file → throw; trim/strip; never argv, never logged).
+
+### `server/ConsoleConfig.java` — fresh, trimmed (model: mini-oidc `ServerConfig.java:42-245`)
+- Fields: `host`, `port`, `dataDir`, `adminTokenFilePath`, `secureCookies`, `sessionTtl`. Drop all
+  OIDC/KMS/argon knobs.
+- `resolve(String[] args, Map<String,String> env)`: flags `--host/--port/--data-dir/--admin-token-file/--secure-cookies/--session-ttl-seconds`;
+  envs `MINICONSOLE_HOST/PORT/DATA_DIR/ADMIN_TOKEN_FILE/SECURE_COOKIES/SESSION_TTL_SECONDS`.
+  `DEFAULT_HOST="127.0.0.1"`, `DEFAULT_PORT=8500`, session TTL 12h (`43_200`), `defaultDataDir` →
+  `$XDG_DATA_HOME/mini-console` or `~/.mini-console`.
+- Copy helpers `requireValue`/`envInt`/`defaultDataDir`/port-range check from `ServerConfig.java`.
+
+### `server/http/` kit — copy verbatim (package → `…miniconsole.server.http`)
+| File | Source |
+| --- | --- |
+| `Router.java` | mini-oidc `server/http/Router.java` |
+| `RequestContext.java` | `server/http/RequestContext.java` |
+| `HttpResponse.java` | `server/http/HttpResponse.java` |
+| `ApiException.java` | `server/http/ApiException.java` |
+| `Json.java` | `server/http/Json.java` (required: `HttpResponse.json` references `Json.toBytes`) |
+
+No `StaticResource.java` (Slice 0 serves no static assets).
+
+### `server/AdminAuthenticator.java` — copy verbatim (mini-oidc `AdminAuthenticator.java:19-67`)
+- Constant-time `MessageDigest.isEqual`. Add a `boolean matches(String presented)` for the
+  form-login path alongside the existing `requireAdmin(authorizationHeader)`. Preserve the
+  touch-the-buffer-on-null trick.
+
+### `server/ConsoleSession.java` — fresh, thin wrapper over `SessionService`
+- Construct as in `OidcServer.java:103-104`: `new SessionService(new JsonStore<>(dataDir.resolve("console-sessions.json"), Sessions.class), clock, sessionTtl)`.
+- SessionService API: `String create(subject, authTime)`, `Optional<BrowserSession> lookup(id)`,
+  `void destroy(id)`.
+- Methods: `establish()` → `create("console-admin", now)`; `isValid(id)` → `lookup(id).isPresent()`;
+  `end(id)` → `destroy(id)`.
+
+### `server/Cookies.java` — copy + adapt (mini-oidc `Cookies.java:17-47`)
+- **Critical change:** replace `SESSION = SessionService.DEFAULT_COOKIE_NAME` with
+  `SESSION = "mini-console-session"`. Keep `session(value, maxAge)` + `clearSession()`.
+
+### `server/Csrf.java` — fresh, minimal (double-submit)
+- `GET /login` mints a random base64url token, set in a short-lived HttpOnly `mini-console-csrf`
+  cookie and embedded in the form; `POST /login` requires `cookie == form field` (constant-time).
+- Methods: `String mint()`, `boolean verify(String expected, String presented)`.
+
+### `store/JsonStore.java` — copy verbatim (mini-oidc `store/JsonStore.java:34-105`)
+- Atomic temp-file → `ATOMIC_MOVE` → `0600` `DocumentStore<T>`. Backs `console-sessions.json`.
+
+### `pages/Layout.java` — fresh
+- `page(String title, String bodyHtml)` wrapping `<!DOCTYPE html>…<nav>` (Dashboard, Logout). Copy
+  the `escape(String)` entity-escaper from `LoginPages.java:109-115`. Never renders a secret.
+
+### `pages/LoginPage.java` — fresh (model: `LoginPages.login`, simplified — no WebAuthn JS)
+- `render(String csrf, boolean error)` → `<form method="post" action="/login">` with a hidden `csrf`
+  field + `<input type="password" name="token">` + submit. On error, one generic "Sign-in failed."
+
+### `pages/DashboardPage.java` — fresh (see §4)
+- `render(...)` → console self-status + the six-service placeholder grid ("n/a — client not wired
+  yet — Slice N").
+
+### `server/ConsoleHandlers.java` — fresh (model: `OidcHandlers` → `Router` assembly)
+- Holds `ConsoleSession`, `AdminAuthenticator`, `Cookies`, `Csrf`, `Clock`. `Router router()`
+  registers the §3 route table. Private `requireSession(ctx)` → redirect to `/login` if invalid.
+
+### `server/ConsoleServer.java` — fresh (composition root; model: `OidcServer.create` + bind)
+- `create(ConsoleConfig, String consoleToken, Clock)`: build the pieces, then bind exactly like
+  mini-oidc: `HttpServer.create(new InetSocketAddress(host, port), 0)`; `createContext("/", router)`;
+  `setExecutor(Executors.newVirtualThreadPerTaskExecutor())`. `start()/stop()/address()`.
+
+### Delete: `MiniConsole.java` — see §5.
+
+---
+
+## 3. Console-login flow + route table
+
+Paste-into-form + session (not token-per-request): the operator is a human in a browser. The console
+token is the bootstrap credential (constant-time compared, never logged), presented in a **password
+field over a POST body** (not URL, not header — never lands in access logs); the HttpOnly session
+cookie is the carry-forward.
+
+| Method | Path | Auth | Behavior / response |
+| --- | --- | --- | --- |
+| `GET` | `/login` | none | Render `LoginPage` + fresh CSRF (set `mini-console-csrf`). 200 HTML. |
+| `POST` | `/login` | CSRF | Verify CSRF (else 400). Constant-time token compare. Match → `establish()` → `Set-Cookie: mini-console-session` → **302 → `/`**. Mismatch → re-render `/login` with generic error, **200** (no oracle). |
+| `GET` | `/` | valid session | Dashboard. 200 HTML. Else 302 → `/login`. |
+| `GET` | `/health` | none | `200 {"status":"ok"}` — liveness, no client calls. |
+| `POST` | `/logout` | session + CSRF | `end(id)` → clear cookie → 302 → `/login`. |
+| (any) | unmatched | — | 404; wrong method on known path → 405. |
+
+No-oracle throughout: bad/missing token and CSRF failure collapse to a single generic outcome.
+
+---
+
+## 4. Dashboard with no clients yet (honest, not faked)
+
+- **Console self-status:** "mini-console — running" + bound address + session principal
+  ("console-admin") + a CSRF-protected Logout button.
+- **Placeholder service grid** — one row per service, rendered literally as
+  `mini-directory — n/a (client not wired yet — Slice 1)` etc., with the slice number where it lands.
+  Calls **nothing** downstream and fabricates no health — the honest seam. Each later slice flips its
+  row from "n/a" to a real `health()` result.
+
+---
+
+## 5. The trip-wire
+
+- `MiniConsole.IMPLEMENTED` is referenced **only** by `MiniConsoleTest` (no production caller) →
+  **delete `MiniConsole.java` entirely** rather than flip the flag to `true` (a `true` constant
+  nobody reads is dead code).
+- **Delete `MiniConsoleTest.java`** (the guard) — its job ("fail the moment real work begins") is
+  fulfilled; deleting it alongside the class, replaced by the §6 tests, is the trip-wire firing.
+- Replace the README's "flip `IMPLEMENTED`" framing with a short "Slice 0: runnable skeleton" note.
+
+---
+
+## 6. Tests — `src/test/java/com/codeheadsystems/miniconsole/`
+
+All against an in-process `ConsoleServer` on an **ephemeral port** (`--port 0`, read back via
+`address().getPort()`), driven with `java.net.http.HttpClient`. No OpenApiContractTest (Slice 8).
+
+1. **`ConsoleServerTest`**: `health_isPublic`; `dashboard_requiresSession` (302→/login);
+   `login_happyPath` (GET /login → capture CSRF → POST /login correct token+CSRF → 302→/, session
+   cookie set → GET / → 200 "mini-console"); `login_wrongToken_noOracle` (no session, generic);
+   `login_csrfReject` (400); `logout_clearsSession`; `dashboard_isHonest` (body contains "client not
+   wired yet").
+2. **`ConsoleConfigTest`**: resolve precedence (flag > env > default), port-range rejection,
+   data-dir resolution, unknown-flag rejection.
+3. **(optional) `CsrfTest`**: mint/verify round-trip + reject.
+
+The secret is never asserted by value; tests pass the token in the request body only.
+
+---
+
+## 7. settings.gradle.kts / catalog
+
+- `include("services:mini-console")` **already exists** — no include change. **Fix the stale
+  comment** that still calls mini-ca *and* mini-console "roadmap placeholder" (mini-ca shipped).
+- `gradle/libs.versions.toml`: **no version additions** — only `jackson` + `junit-jupiter`, both
+  present.
+
+---
+
+## 8. Verification
+
+```bash
+./gradlew build                              # full family CI gate, stays green
+./gradlew :services:mini-console:test        # module tests
+./gradlew :services:mini-console:installDist
+export MINICONSOLE_ADMIN_TOKEN="$(openssl rand -hex 32)"
+services/mini-console/build/install/mini-console/bin/mini-console --port 8500 --data-dir /tmp/mini-console &
+curl -s http://127.0.0.1:8500/health         # -> {"status":"ok"}
+curl -s -i http://127.0.0.1:8500/             # -> 302 Location: /login
+```
+
+**Done:** `./gradlew build` green family-wide with no regressions; `MiniConsole.java` +
+`MiniConsoleTest.java` gone, replaced by the §6 tests; `installDist` yields a `bin/mini-console`
+launcher binding loopback:8500, `/health` public, `/` → 302→/login without a session, and after a
+correct token paste an authenticated Dashboard that honestly says "client not wired yet." No secret
+in any log line.
+
+---
+
+## 9. PR framing
+
+> **Slice 0 graduates mini-console from roadmap placeholder to a runnable skeleton.** It **fires the
+> trip-wire by design:** deletes `MiniConsole.IMPLEMENTED` (referenced only by the guard test) and
+> `MiniConsoleTest`, replacing them with real `ConsoleServer`/`ConsoleConfig`/CSRF tests. Here: a
+> loopback HTTP server (virtual-thread-per-request), a paste-the-console-token login minting a
+> mini-token `SessionService` session under a **distinct** `mini-console-session` cookie, and a
+> Dashboard. **Deliberately NOT here (honest seams):** the Dashboard calls nothing downstream —
+> "n/a — client not wired yet (Slice N)" for each service. `libs/mini-client-common` is intentionally
+> deferred to Slice 1 (driven by its first real consumer). No OpenAPI/SwaggerUI (Slice 8). The
+> console adds **no new authority** — Slice 0 holds only its own bootstrap console token (env/file,
+> never argv, never logged).
diff --git a/docs/design/mini-console.md b/docs/design/mini-console.md
new file mode 100644
index 0000000..fbdeeb1
--- /dev/null
+++ b/docs/design/mini-console.md
@@ -0,0 +1,371 @@
+# mini-console — Design Document
+
+A design and module/API sketch for graduating `services/mini-console` from roadmap placeholder to a shipping, admin-only, optional **operator console + end-to-end exercise harness** over the mini- family. No working code here — interface sketches, layout, routes, and a slice-by-slice roadmap. Honest seams preserved throughout.
+
+*Revised 2026-06-19 to fold in maintainer decisions — see [Resolved decisions](#resolved-decisions-confirmed-with-maintainer) at the end.*
+
+## Decisions & assumptions
+
+1. **Five new HTTP client libs under `libs/`; mini-kms reuses its existing `:services:mini-kms:client`.** The five new clients are HTTP/JSON (directory, idp, oidc, ca, gateway). mini-kms is the family's deliberate **socket-era exception**: its `KmsClient` + `KmsSigningKeyStore` already live in `:services:mini-kms:client` and are consumed by mini-idp/mini-oidc/mini-ca today. Relocating it into a `libs/mini-kms-client` was designed and independently reviewed — mechanically clean and behavior-preserving — but **declined** by the maintainer (cosmetic parity for real churn in three shipping services); the exception is now recorded in `docs/DIRECTION.md`. mini-console therefore depends on `:services:mini-kms:client` directly, exactly as the other consumers do. If a `libs/<svc>-client` convention later hardens, mini-kms's client is the first candidate to follow it. See §3.4.
+2. **A shared `libs/mini-client-common` IS warranted.** All five HTTP clients need the same: env/file token resolver, a `java.net.http.HttpClient` builder bound to loopback, JSON (de)serialization via a shared `JsonMapper`, bearer-header injection, and the no-oracle error collapse. That is squarely the documented `mini-common` extraction shape. We introduce `libs/mini-client-common` rather than copy the plumbing five times. It depends on nothing in the family except the catalog Jackson.
+3. **Client libs share model DTOs by COPYING, not by depending on a service's `server`.** Depending on `:services:mini-directory` (an application module) from a lib would couple a lib to a front door and risk cycles. Each client lib copies the handful of wire records it needs (`Account`, `Group`, `Role`, `GrantSpec`, `ResolvedPrincipal`, token responses, CA records) into its own `com.codeheadsystems.<svc>.client.model` package — the same "deliberate copy until mini-common exists" stance the family already takes for `JsonStore`/`AdminAuthenticator`. The records are small, stable, and Jackson-bound by parameter name. Dependency direction is strictly **console → client-libs → mini-client-common → (catalog)**; no client lib depends on any service module. Acyclic.
+4. **mini-console binds loopback and holds downstream admin tokens in memory only.** It is a privileged aggregator: to call six admin APIs it must hold up to six downstream admin tokens (plus its own console token). All are resolved env/file, never argv, never logged, held as `char[]`/`byte[]` where the API allows, zeroed on shutdown. This is the one genuinely new concentration of secrets in the family and it is called out explicitly in §6.
+5. **Server-rendered HTML, no JS toolchain; the `/api` OpenAPI surface is KEPT (confirmed).** mini-console's *operator UI* is HTML-only (no openapi.yaml for the HTML pages). A small read-only JSON `/api` surface (health rollups + harness results) **is included**, with an `openapi.yaml` + `OpenApiContractTest`, so the console honors the family contract-test pattern.
+6. **mini-idp/mini-oidc/mini-ca currently ship NO client module** (confirmed) — each HTTP client is a fresh extraction. mini-directory and mini-gateway likewise. Only mini-kms has a client today.
+
+---
+
+## 1. Architecture overview
+
+mini-console sits *above* every service as a pure client of surfaces that already exist. It introduces **no new authority** — every mutation it performs is one the operator could perform by curling an admin API with the same downstream admin token. It is a convenience and verification layer, never a source of truth, never a new trust boundary's holder of identity data.
+
+Two faces, one process:
+
+- **Operator console (read/mutate):** server-rendered HTML pages that browse and edit directory identities, trigger key rotations, read audit/issuance logs, and manage KMS key groups — each backed by a client lib call to the owning service's admin API.
+- **Exercise harness (verify):** scripted end-to-end flows that drive the family the way a real client would (issue an m2m token, run OIDC code+PKCE, mint/renew/revoke a cert, hit gateway `/verify`, rotate a signing key) and **verify the result offline** (signature against JWKS, claim checks, chain validation), reporting pass/fail without ever logging a secret.
+
+```
+                            ┌────────────────────────────────────────────────┐
+   operator (browser,       │                  mini-console                  │
+   loopback only) ─────────▶│  server/  (HttpServer, loopback, console token)│
+                            │  ├─ pages/   operator HTML (CSRF on POST)       │
+                            │  ├─ harness/ end-to-end flows + offline verify  │
+                            │  └─ config/  ConsoleConfig (env/file tokens)    │
+                            └───┬─────┬─────┬─────┬─────┬─────┬───────────────┘
+                                │     │     │     │     │     │   (each = one client lib)
+                ┌───────────────┘     │     │     │     │     └───────────────┐
+                ▼                     ▼     ▼     ▼     ▼                     ▼
+        mini-directory-client  idp-client oidc-client  kms client    ca-client gateway-client
+                │                     │     │     │   (existing, under │              │
+                ▼                     ▼     ▼     ▼    services/)       ▼              ▼
+          mini-directory        mini-idp  mini-oidc  mini-kms          mini-ca   mini-gateway
+          (admin HTTP)          (HTTP)    (HTTP)     (socket)          (HTTP)    (HTTP /verify)
+
+   five HTTP client libs ──depend on──▶ libs/mini-client-common (token resolver, HttpClient, JSON, no-oracle)
+   mini-console reuses the existing :services:mini-kms:client (KmsClient + KmsSigningKeyStore) as-is
+   dependency direction is one-way and acyclic:
+       mini-console ─▶ {*-client} ─▶ mini-client-common | mini-token ─▶ (catalog)
+       the HTTP clients copy their DTOs and depend on NO service module; mini-kms's client stays
+       the documented socket-era exception under services/ (see docs/DIRECTION.md)
+```
+
+**Data flow (operator mutate example — assign a role to a service account):** browser GET `/identities/{id}` → console renders form with a CSRF token → operator POSTs `/identities/{id}/roles` (CSRF validated) → console calls `MiniDirectoryClient.assignRole(id, roleId)` with the *directory* admin token → directory mutates → console re-renders the resolved-principal preview by calling `resolve(id)`. mini-console persisted nothing.
+
+**Data flow (harness verify example — m2m token):** operator clicks "Run: issue + verify m2m token" → harness calls `MiniIdpClient.token(clientId, secret)` → fetches JWKS via `MiniIdpClient.jwks()` → verifies the JWS signature **offline** with mini-token's `JwsClaimsVerifier`/`TokenVerifier` (reused, not re-implemented) → asserts `iss`/`aud`/`exp`/`grants` → renders a green/red result row. The secret used is never echoed back to the page or the log.
+
+---
+
+## 2. Module layout
+
+### 2.1 The console module (`services/mini-console`, base package `com.codeheadsystems.miniconsole`)
+
+Graduates to `miniauth.application-conventions`. Composition root in `server/`; I/O-free logic (harness verification, route policy) kept transport-free so it is unit-testable without a socket.
+
+```
+services/mini-console/
+├── build.gradle.kts                 # application-conventions; mainClass = …miniconsole.ServerMain
+└── src/main/java/com/codeheadsystems/miniconsole/
+    ├── ServerMain.java              # entry point: parse config, build server, start
+    ├── server/
+    │   ├── ConsoleServer.java       # composition root: HttpServer (loopback), vthread executor, wires handlers + all 6 clients
+    │   ├── ConsoleConfig.java       # --port/--data-dir + resolveConsoleToken + per-downstream URL/token resolution (env/file, never argv)
+    │   ├── AdminAuthenticator.java  # bearer guard for the console-login token (constant-time, copied family pattern)
+    │   ├── ConsoleSession.java      # mini-token SessionService over a JsonStore (own store + own cookie name); see §6
+    │   ├── ConsoleHandlers.java     # the route table → page renderers / harness triggers
+    │   ├── Cookies.java             # console session cookie helpers (distinct name, NOT the shared SSO cookie)
+    │   ├── Csrf.java                # per-page CSRF token mint/verify, bound to the console session (mini-oidc pattern)
+    │   ├── store/                   # JsonStore (atomic 0600) backing the console session store
+    │   ├── http/                    # the reused Router/Route kit (copied family http/ package)
+    │   └── openapi/                 # OpenApiDocument + SwaggerUiPage for the /api JSON surface (KEPT — see §7)
+    ├── pages/                       # server-rendered HTML — hand-rolled, mini-oidc LoginPages style
+    │   ├── Layout.java              # shared chrome (nav, escaping helpers); NEVER renders a secret
+    │   ├── DashboardPage.java
+    │   ├── IdentitiesPages.java     # list/detail/edit + resolution preview
+    │   ├── KeysPages.java           # signing-key rotation (idp/oidc) + KMS key-group mgmt
+    │   ├── AuditPages.java          # issuance/rotation/revocation logs
+    │   ├── CertificatesPages.java   # mini-ca issuance log + revocation list + issue/renew/revoke
+    │   └── HarnessPages.java        # the exercise harness screen + result rows
+    └── harness/                     # I/O-free exercise/verify engine (transport-free core)
+        ├── Exercise.java            # one named flow: run(clients) → ExerciseResult
+        ├── ExerciseResult.java      # record(name, Status PASS|FAIL|SKIP, List<Step> steps, redactedDetail)
+        ├── ExerciseRegistry.java    # the catalog of flows
+        └── flows/                   # M2mTokenFlow, OidcCodePkceFlow, CertLifecycleFlow, GatewayVerifyFlow, KeyRotationFlow
+```
+
+### 2.2 The client libraries (under `libs/`)
+
+```
+libs/
+├── mini-client-common/             # NEW — shared HTTP/token/JSON plumbing for all HTTP clients
+│   └── …/client/common/            # base package com.codeheadsystems.miniclient.common
+│       ├── TokenResolver.java       # env-var | file → char[] (the resolveToken mechanism, parameterized by var name)
+│       ├── HttpTransport.java       # java.net.http.HttpClient bound to loopback, bearer injection, JSON in/out
+│       ├── Json.java                # shared JsonMapper.builder()…build() (Jackson 3.x)
+│       └── ClientException.java     # the single generic client-side error (no-oracle collapse)
+├── mini-directory-client/          # NEW — com.codeheadsystems.minidirectory.client
+├── mini-idp-client/                # NEW — com.codeheadsystems.miniidp.client
+├── mini-oidc-client/               # NEW — com.codeheadsystems.minioidc.client
+├── mini-ca-client/                 # NEW — com.codeheadsystems.minica.client
+├── mini-gateway-client/            # NEW — com.codeheadsystems.minigateway.client
+├── mini-token/                     # (existing — harness reuses its JwsClaimsVerifier/TokenVerifier/JWKS model)
+└── mini-policy/                    # (existing)
+```
+mini-kms is **not** in this list: it keeps its existing `:services:mini-kms:client` (`KmsClient` + `KmsSigningKeyStore`) — the documented socket-era exception, consumed directly. See §3.4 and `docs/DIRECTION.md`.
+
+Each HTTP client lib uses `miniauth.library-conventions`, depends on `:libs:mini-client-common` + `libs.jackson.databind`, and copies only the wire records it needs into its own `…client.model` subpackage.
+
+### 2.3 settings.gradle.kts + catalog wiring
+
+Add to `settings.gradle.kts` (the console line already exists; add the libs):
+
+```kotlin
+// --- Libraries (shared, no transport) ---
+include("libs:mini-token")
+include("libs:mini-policy")
+include("libs:mini-client-common")
+include("libs:mini-directory-client")
+include("libs:mini-idp-client")
+include("libs:mini-oidc-client")
+include("libs:mini-ca-client")
+include("libs:mini-gateway-client")
+```
+(mini-kms keeps its existing `include("services:mini-kms:client")` — not relocated.)
+
+Move `services:mini-console` out of the "roadmap placeholders" comment block (mini-ca already shipped, so that comment is stale anyway — fix it in passing).
+
+**Catalog:** no new versions needed. Everything resolves through existing `libs.jackson.databind`, `libs.jackson.yaml` (only if OpenAPI kept), `libs.bouncycastle-pkix` (harness chain validation for mini-ca). No inline versions anywhere.
+
+mini-console's `build.gradle.kts`:
+
+```kotlin
+plugins { id("miniauth.application-conventions") }
+dependencies {
+    implementation(project(":libs:mini-directory-client"))
+    implementation(project(":libs:mini-idp-client"))
+    implementation(project(":libs:mini-oidc-client"))
+    implementation(project(":libs:mini-ca-client"))
+    implementation(project(":libs:mini-gateway-client"))
+    implementation(project(":services:mini-kms:client"))   // existing KmsClient (+ KmsSigningKeyStore) — the socket-era exception, not relocated
+    implementation(project(":libs:mini-token"))            // offline JWS/JWKS verify in the harness
+    implementation(project(":libs:mini-policy"))           // render/check grant decisions
+    implementation(libs.jackson.databind)
+    implementation(libs.jackson.yaml)                      // only if /api openapi.yaml is kept
+    implementation(libs.bouncycastle.pkix)                 // X.509 chain validation in CertLifecycleFlow
+}
+application { mainClass = "com.codeheadsystems.miniconsole.ServerMain" }
+```
+
+---
+
+## 3. The client libraries — interface sketches
+
+All clients: constructed from a base URL (loopback) + a token supplier; admin calls send `Authorization: Bearer <token>`; **every** failure collapses to a single `ClientException` (no status/body distinction surfaced to callers — no oracle); secrets passed as `char[]`/`byte[]` and never placed in exception messages or logs. Records are Jackson-bound by parameter name (`-parameters`).
+
+### 3.1 `mini-directory-client` — `com.codeheadsystems.minidirectory.client`
+Copies: `Account`, `Group`, `Role`, `GrantSpec`, `ResolvedPrincipal` (into `…client.model`). Admin bearer (`MINIDIR_ADMIN_TOKEN` held by console).
+
+```java
+public interface MiniDirectoryClient {
+  // Accounts (HUMAN | SERVICE_ACCOUNT)
+  Account createAccount(NewAccount spec);                 // returns secret ONCE for SERVICE_ACCOUNT (char[] in NewSecret)
+  Account getAccount(String id);
+  List<Account> listAccounts();
+  Account updateAccount(String id, AccountPatch patch);
+  void    deleteAccount(String id);
+  // Groups / Roles CRUD
+  Group createGroup(NewGroup g);   List<Group> listGroups();  void deleteGroup(String id);
+  Role  createRole(NewRole r);     List<Role>  listRoles();   void deleteRole(String id);
+  // Assignment
+  void assignRoleToAccount(String accountId, String roleId);
+  void removeRoleFromAccount(String accountId, String roleId);
+  void addAccountToGroup(String accountId, String groupId);
+  void removeAccountFromGroup(String accountId, String groupId);
+  void assignRoleToGroup(String groupId, String roleId);
+  // The defining call
+  ResolvedPrincipal resolve(String accountId);            // GET /admin/principals/{id}/resolution
+  // No-oracle credential check (service accounts)
+  AuthOutcome authenticate(String accountId, char[] secret);   // PASS/FAIL only; secret zeroed by impl
+}
+```
+
+### 3.2 `mini-idp-client` — `com.codeheadsystems.miniidp.client`
+Copies: `TokenResponse` (`access_token`, `token_type`, `expires_in`), `Jwks` (reuse mini-token's JWKS model rather than copy — depend on `:libs:mini-token` for the model only). Token endpoint is **public** (client-credentials); admin/JWKS as applicable.
+
+```java
+public interface MiniIdpClient {
+  TokenResponse token(String clientId, char[] clientSecret);   // POST /oauth/token (client_credentials)
+  Jwks jwks();                                                  // GET the JWKS for offline verify
+  RotationResult rotateSigningKey();                           // admin: POST /admin/keys/rotate → {activeKid} (endpoint EXISTS today)
+  List<Revocation> revocations();   void revoke(String jti, String reason);  // admin: token denylist
+  List<AuditEntry> audit();                                    // admin: GET /admin/audit
+  HealthStatus health();                                        // GET /health
+}
+```
+
+### 3.3 `mini-oidc-client` — `com.codeheadsystems.minioidc.client`
+Copies: `DiscoveryDocument`, `TokenResponse` (id+access+refresh), `ClientRegistration`/`RegisteredClient`. Mix of public (discovery/jwks/token/userinfo) + admin (client registration).
+
+```java
+public interface MiniOidcClient {
+  DiscoveryDocument discovery();                       // GET /.well-known/openid-configuration
+  Jwks jwks();                                          // GET /jwks.json
+  RegisteredClient registerClient(ClientRegistration r);// admin: register an OIDC client
+  // Authorization-code + PKCE: the harness needs to construct /authorize URLs and exchange codes.
+  URI authorizeUrl(AuthorizeRequest req);               // builds the /authorize URL incl. code_challenge(S256)
+  TokenResponse exchangeCode(String code, String codeVerifier, String redirectUri, String clientId);
+  TokenResponse refresh(String refreshToken, String clientId);
+  UserInfo userInfo(String accessToken);                // GET /userinfo (bearer = the just-issued access token)
+  RotationResult rotateSigningKey();                    // admin: POST /admin/keys/rotate (NEW endpoint — added to mini-oidc, mirrors mini-idp)
+  HealthStatus health();
+}
+```
+Note: the full browser passkey ceremony is **not** automatable headlessly from a pure HTTP client; the OIDC harness flow uses a pre-seeded test session/consent shortcut where available, and is otherwise marked SKIP with an honest reason (see §5). The client lib exposes the protocol calls; it does not embed pk-auth.
+
+### 3.4 mini-kms — **reuse the existing `:services:mini-kms:client` as-is** (documented exception)
+`KmsClient` already exposes both planes — data (`encrypt`/`decrypt`/`reEncrypt`/`generateDataKey`/`health`) and control (`createKeyGroup`/`rotateKeyGroup`/`listKeyGroups`/`disableVersion`/`enableVersion`/`destroyVersion`) — so mini-console consumes it directly; nothing is wrapped or re-implemented. Relocating `KmsClient` + `KmsSigningKeyStore` into a `libs/mini-kms-client` was designed and independently reviewed: it is mechanically clean and behavior-preserving, but the maintainer **declined** it — the benefit is cosmetic parity with a not-yet-built `libs/<svc>-client` convention, against real churn in three shipping services (mini-idp/mini-oidc/mini-ca) plus a split-package or import-rewrite cost. mini-kms's client is recorded as the deliberate **socket-era exception** in `docs/DIRECTION.md`, and is the first candidate to move *if* that convention later hardens.
+
+```java
+// the existing KmsClient API under :services:mini-kms:client — used as-is, nothing re-implemented
+KmsClient connectTcp(String host, int port, String token);   // also connectUnix(Path, token)
+boolean health();
+// data plane (API token):     generateDataKey / encrypt / decrypt / reEncrypt
+// control plane (admin token): createKeyGroup / rotateKeyGroup / listKeyGroups
+//                              disableVersion / enableVersion / destroyVersion
+```
+
+The two mini-kms tokens (`MINIKMS_API_TOKEN` + `MINIKMS_ADMIN_TOKEN`) are resolved env/file by the console exactly as the CLI does.
+
+### 3.5 `mini-ca-client` — `com.codeheadsystems.minica.client`
+Copies: `IssueRequest` (CSR PEM), `Certificate` (leaf PEM), `RevocationEntry`, `IssuanceLogEntry`. Public: `/ca`, `/revocations`, `/health`. Admin: issue/renew/revoke/log.
+
+```java
+public interface MiniCaClient {
+  String caCertificatePem();                       // GET /ca (public trust anchor)
+  List<RevocationEntry> revocations();             // GET /revocations (public)
+  Certificate issue(String csrPem, Duration ttl);  // admin: POST CSR → leaf
+  Certificate renew(String csrPem);                // admin
+  void revoke(String serial, String reason);       // admin
+  List<IssuanceLogEntry> issuanceLog();            // admin
+  HealthStatus health();
+}
+```
+
+### 3.6 `mini-gateway-client` — `com.codeheadsystems.minigateway.client`
+Copies: nothing material (header-driven). Public-ish `/verify` (the proxy calls it; console calls it as the proxy would, to exercise it).
+
+```java
+public interface MiniGatewayClient {
+  VerifyOutcome verify(VerifyRequest req);   // sends X-Forwarded-Method/Uri + Cookie|Authorization
+                                             // → 200(+X-Auth-Subject/Scope/Source) | 302 | 401 | 403
+  HealthStatus health();
+}
+// VerifyOutcome maps the status to AUTHORIZED / REDIRECT_LOGIN / UNAUTHENTICATED / FORBIDDEN — no body oracle.
+```
+
+### 3.7 mini-common overlap & whether a shared client lib is warranted
+**Warranted — yes.** The env/file token resolver and the loopback `HttpClient`/JSON plumbing are exactly two of the documented `mini-common` candidates (ServerConfig secret resolution; and HTTP plumbing is the natural client-side twin). Rather than copy them into five clients, `libs/mini-client-common` holds them once. This is the *client-side* counterpart to the still-deferred server-side `mini-common` — the doc updates note that when server-side `mini-common` lands, `TokenResolver` can be unified with `ServerConfig.resolveToken`. Dependency direction stays one-way (clients → client-common → catalog); no cycle.
+
+---
+
+## 4. Console pages (operator mode)
+
+Server-rendered HTML, hand-rolled in the mini-oidc `LoginPages` spirit. **CSRF token on every state-changing POST** (minted per page render, validated on submit — mini-oidc's pattern). Loopback only, behind the console admin token (a session cookie set after the operator presents the token, OR the token on each request). All output HTML-escaped via a `Layout` helper; **no page ever renders a downstream secret** (the once-only service-account secret is shown exactly once at creation, with a copy-and-dismiss banner, never re-fetchable and never logged).
+
+| Screen | Route(s) | Backing client call(s) |
+| --- | --- | --- |
+| Dashboard | `GET /` | health() across all six |
+| Identities — list | `GET /identities` | `listAccounts/listGroups/listRoles` |
+| Identities — detail + resolution preview | `GET /identities/{id}` | `getAccount` + `resolve(id)` |
+| Identities — create/edit | `GET/POST /identities`, `POST /identities/{id}` | `createAccount/updateAccount` (secret shown once) |
+| Identities — assignment | `POST /identities/{id}/roles`, `/groups` | assign/remove role/group |
+| Identities — delete | `POST /identities/{id}/delete` | `deleteAccount` |
+| Keys — signing keys | `GET /keys`, `POST /keys/{issuer}/rotate` | `rotateSigningKey()` on idp/oidc (`POST /admin/keys/rotate`) + JWKS readback to confirm new kid |
+| Keys — KMS key groups | `GET /keys/kms`, `POST /keys/kms/{name}/{op}` | KmsClient control plane: create/rotate/disable/enable/destroy |
+| Audit | `GET /audit` | issuance/rotation/revocation logs (idp/oidc/token) |
+| Certificates | `GET /certificates` | `issuanceLog()` + `revocations()` |
+| Certificates — issue/renew/revoke | `POST /certificates/...` | `issue/renew/revoke` |
+| Harness | `GET /harness`, `POST /harness/{flow}/run` | see §5 |
+
+All POST routes carry a hidden `_csrf` field; the handler rejects a missing/mismatched token with a generic 400 before any client call. Destructive ops (`destroy` key version, `delete` account, `revoke` cert) render a confirm step.
+
+---
+
+## 5. Exercise / test harness (test mode)
+
+The harness is an **I/O-free engine** (`harness/`) given the wired clients; each flow returns an `ExerciseResult(name, Status, steps, redactedDetail)`. **"Pass" is defined per flow as a cryptographic/state assertion verified offline**, not just an HTTP 200. Results render as green/red rows with per-step detail; **no step ever records a secret** — tokens/secrets are replaced with `«redacted»` and only non-secret facts (kid, sub, exp, serial, status code) are shown.
+
+| Flow | Drives | "Pass" = (verified offline) |
+| --- | --- | --- |
+| **M2mTokenFlow** | `idp.token(client,secret)` → `idp.jwks()` | JWS signature verifies against JWKS via mini-token's `TokenVerifier`; `iss`/`aud`/`exp` valid; `grants` matches directory `resolve()` |
+| **OidcCodePkceFlow** | build `/authorize` (S256) → `exchangeCode(verifier)` → `userInfo` → `refresh` | id_token signature verifies against `/jwks.json`; `nonce`/`aud`/`auth_time` present; refresh rotates (old refused → no-oracle `invalid_grant`). *Passkey step is SKIP with reason "headless WebAuthn not driven" unless a test credential is seeded.* |
+| **CertLifecycleFlow** | generate keypair+CSR locally → `ca.issue` → `ca.renew` → `ca.revoke` | issued leaf chains to `ca.caCertificatePem()` (Bc PKIX `CertPathValidator`); serial appears in `revocations()` after revoke |
+| **GatewayVerifyFlow** | `gateway.verify` with (a) no creds, (b) valid bearer, (c) insufficient scope | (a) → 302/401, (b) → 200 + `X-Auth-Subject`, (c) → 403. Asserts all three branches |
+| **KeyRotationFlow** | rotate a signing key → re-fetch JWKS | new `kid` present in JWKS; retired `kid` retained (in-flight tokens still verify); a token minted pre-rotation still verifies |
+
+`ExerciseRegistry` lists them; the Harness page runs one or all and shows a summary line (`4 passed, 1 skipped, 0 failed`). The engine is unit-testable against in-memory fakes of the six clients (mirrors how the services test their SPIs), so the harness has real tests independent of a running family.
+
+---
+
+## 6. Security model
+
+- **Adds no new authority.** Every action equals an operator curling a downstream admin API with the same token. mini-console stores **no identity, no grants, no keys** — only its own login-session/CSRF state, persisted in an atomic-`0600` `JsonStore` (`console-sessions.json`).
+- **Console auth:** its own bootstrap token from `MINICONSOLE_ADMIN_TOKEN` env or `--admin-token-file` (never argv, never logged), validated constant-time (`MessageDigest.isEqual`) via the copied `AdminAuthenticator`. Loopback bind by default; any LAN exposure is an explicit operator decision behind TLS.
+- **Console session (confirmed):** after the operator presents the console token once, mini-console establishes a login session using **mini-token's `SessionService` mechanism over its OWN `JsonStore`-backed store** (`console-sessions.json`, atomic `0600` in `--data-dir`) — a separate namespace from the family SSO session, with a **distinct cookie name** (not `SessionService.DEFAULT_COOKIE_NAME`, to avoid colliding with a mini-oidc cookie on a shared host). Session state persists across restarts; CSRF tokens are bound to the session.
+- **Downstream tokens (the one new secret concentration):** mini-console must hold up to six downstream admin/API tokens to do its job. Each is resolved env/file (`MINIDIR_ADMIN_TOKEN`, `MINIIDP_ADMIN_TOKEN`, `MINIOIDC_ADMIN_TOKEN`, `MINIKMS_API_TOKEN`+`MINIKMS_ADMIN_TOKEN`, `MINICA_ADMIN_TOKEN`), held as `char[]`/`byte[]`, never argv, never logged, zeroed on shutdown. The README states plainly that running mini-console means concentrating these tokens in one loopback process — a deliberate operator trade-off, mitigated by loopback default.
+- **No oracles anywhere:** client libs collapse all failures to one `ClientException`; the console renders a single generic error; the harness reports FAIL without distinguishing why in a way that leaks (it shows the *expected* assertion that failed, not downstream internals).
+- **No secrets in logs, including fetched ones:** the once-only service-account secret and any minted token are shown in the UI exactly where needed and replaced with `«redacted»` everywhere else; access logs record method/path/status only (family rule).
+- **CSRF** on every state-changing browser POST; **PKCE S256** mandatory in the OIDC harness flow.
+
+---
+
+## 7. Build & test plan
+
+- **Convention change:** flip mini-console from `library-conventions` → `application-conventions`, add `mainClass`, add the client-lib deps. Each new `libs/*-client` uses `library-conventions`; `mini-client-common` likewise. mini-kms is consumed via its existing `:services:mini-kms:client` (not relocated — see §3.4).
+- **mini-oidc rotation endpoint (new):** add `POST /admin/keys/rotate` to mini-oidc mirroring mini-idp's existing handler, plus an `openapi.yaml`/`OpenApiContractTest` entry and a unit test asserting the new kid appears in `/jwks.json` with the retired kid retained.
+- **The trip-wire:** flip `MiniConsole.IMPLEMENTED = true` and **delete** `MiniConsoleTest` (the guard), replacing it with real tests. This is the designed trip-wire — the moment `IMPLEMENTED` flips, the old guard fails, forcing real tests in. Call this out in the first slice's PR.
+- **Real tests:** (a) each client lib against an in-memory fake server or the real service booted in-test (mirrors mini-oidc's KMS-backed test that boots real mini-kms); (b) the harness engine against in-memory client fakes; (c) `ConsoleHandlers` route + CSRF tests against a live in-process `HttpServer`.
+- **Contract test:** an `OpenApiContractTest` for the `/api` JSON surface, asserting documented paths resolve on the live console — same pattern as the other services.
+- **Green gate:** `./gradlew build` from root must stay green. New modules compile + test under the one wrapper/catalog/conventions. No inline versions; Jackson 3.x (`tools.jackson.*`); `System.Logger`; `-parameters` (inherited).
+
+---
+
+## 8. Implementation roadmap (vertical slices, dependency order)
+
+Each slice is independently shippable and leaves the build green. Recommended ordering — establish the shared plumbing, then land the simplest read-only vertical end-to-end (client lib + page + harness flow) before the mutating ones:
+
+1. **Slice 0 — `mini-client-common` + console skeleton (server, config, http router, AdminAuthenticator, console-login session via mini-token `SessionService` over `JsonStore`, Layout, Dashboard page, console token).** Flip `IMPLEMENTED`, delete the guard test, add real skeleton tests. Dashboard shows `health()` of services that have a client yet (none → all "n/a"). Ships the trip-wire.
+2. **Slice 1 — `mini-directory-client` + Identities pages (read-only: list + detail + resolution preview).** The richest, most-used surface; read-only first. Verifies the client/page/CSRF kit end to end.
+3. **Slice 2 — Identities mutations (create/edit/assign/delete) + the once-only-secret banner.** Adds CSRF-guarded POSTs.
+4. **Slice 3 — `mini-idp-client` + `mini-token` reuse + M2mTokenFlow (harness).** First exercise flow; proves offline JWS-vs-JWKS verification. Audit page (idp side) lands here.
+5. **Slice 4 — mini-kms reuse (`:services:mini-kms:client`) + Keys page (KMS key groups + issuer signing-key rotation) + KeyRotationFlow.** Includes adding `POST /admin/keys/rotate` to mini-oidc (mini-idp already has it). Control-plane key-group mgmt + rotation verification.
+6. **Slice 5 — `mini-ca-client` + Certificates page + CertLifecycleFlow.** Adds Bc PKIX chain validation.
+7. **Slice 6 — `mini-oidc-client` + OidcCodePkceFlow (passkey step honestly SKIP) + client registration page.**
+8. **Slice 7 — `mini-gateway-client` + GatewayVerifyFlow (200/401/403/302 branches).**
+9. **Slice 8 — optional `/api` JSON surface + `OpenApiContractTest` + SwaggerUiPage; harness "run all" summary; README rewrite.**
+
+**Recommended first slice: Slice 0 + Slice 1 together** — they prove the whole vertical (shared plumbing → client lib → server-rendered page) on the read-only directory surface, ship the `IMPLEMENTED` trip-wire honestly, and add zero mutation risk. Everything after is additive.
+
+---
+
+## 9. Documentation updates
+
+- **`docs/DIRECTION.md`:** move mini-console out of "Future tracks (explicitly not scheduled)" into the roadmap as the active track; update the component-catalog row (Status: shipping/in-progress); add a short subsection describing the client-lib layer + `mini-client-common` and explicitly noting it adds no new authority. Update the `mini-common` section to note the client-side `TokenResolver`/HTTP plumbing now live in `mini-client-common` and should converge with server-side `mini-common` when that lands. Record the new mini-oidc rotation endpoint. (The mini-kms client relocation was considered and **declined** — the deliberate-exception note is already recorded in DIRECTION.md's signing-key-wrapping section; no change to mini-kms is needed.)
+- **mini-oidc rotation endpoint:** document the new `POST /admin/keys/rotate` in mini-oidc's section + `openapi.yaml` (mirrors mini-idp's existing endpoint).
+- **Root `CLAUDE.md`:** update the layout table (mini-console: service/shipping; add the five `libs/*-client` + `mini-client-common` rows), add a `# Service: mini-console` section mirroring the others (architecture, the page/harness split, the security model, the "no new authority" statement, the downstream-token concentration caveat), and update the `settings.gradle.kts` include list. Fix the stale "roadmap placeholders" comment (mini-ca already shipped). mini-kms's section is unchanged (its client stays put — the documented socket-era exception).
+- **`services/mini-console/README.md`:** replace the placeholder doc with a real teaching README — the two faces (operator console + exercise harness), the screen/route list, the harness flows and what "pass" means, the security model (loopback, console token, downstream-token concentration, no-oracle/no-secret-logging), and runnable `installDist` instructions. Remove the "roadmap placeholder" framing.
+- **`settings.gradle.kts` header comment:** update the layout map (mini-console no longer a placeholder; new libs listed).
+
+---
+
+## Resolved decisions (confirmed with maintainer)
+
+1. **Token model:** held-token — mini-console holds its own console-login token plus each downstream admin/API token (env/file, never argv, never logged, zeroed on shutdown), with the loopback caveat stated plainly in the README. (Not per-downstream passthrough.)
+2. **Console login session:** reuse mini-token's `SessionService` mechanism over the console's **own** `JsonStore`-backed store, with a **distinct cookie name** (not the shared SSO cookie) to avoid collision on a shared host. Console stays free of the family SSO session file.
+3. **State persistence:** session/CSRF state persists in an atomic-`0600` `JsonStore` (`console-sessions.json`) under `--data-dir`.
+4. **`/api` OpenAPI surface:** kept, with an `OpenApiContractTest` — the console honors the family contract-test pattern.
+5. **Signing-key rotation endpoint:** there is an admin HTTP trigger. mini-idp already exposes `POST /admin/keys/rotate`; **mini-oidc gains the same endpoint** (a small, additive cross-service change), so `rotateSigningKey()` is callable on both issuers from the Keys page.
+6. **mini-kms client relocation: declined — keep as-is.** `KmsClient` + `KmsSigningKeyStore` stay in `:services:mini-kms:client`; mini-console consumes that module directly, like mini-idp/mini-oidc/mini-ca. The relocation into `libs/mini-kms-client` was designed and independently reviewed (mechanically clean, behavior-preserving) but judged cosmetic-and-speculative against real churn in three shipping services. mini-kms's client is documented as the deliberate **socket-era exception** in `docs/DIRECTION.md`, and is the first candidate to follow a `libs/<svc>-client` convention *if* one ever hardens.
+
+No open questions remain. Two follow-on notes to carry into implementation: (a) the console session cookie **must** use a name distinct from `SessionService.DEFAULT_COOKIE_NAME`; (b) the mini-oidc rotation endpoint is a genuine (if small) addition to another service — land it with its own contract-test + unit test in Slice 4.
+
+**Recommended first slice: Slice 0 + Slice 1** (shared client plumbing + console skeleton with the `IMPLEMENTED` trip-wire and console-login session, then the read-only Identities vertical), landing one full client-lib → page path with zero mutation risk and a green `./gradlew build`.
diff --git a/services/mini-console/README.md b/services/mini-console/README.md
index 599bcc1..18a323e 100644
--- a/services/mini-console/README.md
+++ b/services/mini-console/README.md
@@ -1,115 +1,59 @@
 # Mini Console
 
-**mini-console** is a *reserved* slot for an optional, unified **admin UI** over the whole `mini-`
-family — one place to inspect mini-directory identities, rotate mini-token signing keys, review
-audit logs, and manage mini-kms key groups, instead of curling each service's admin API by hand.
+**mini-console** is the optional unified **admin console** over the whole `mini-` family — one place
+to inspect mini-directory identities, rotate mini-token signing keys, review audit logs, and manage
+mini-kms key groups, instead of curling each service's admin API by hand. It is also an **exercise
+harness** for smoke-testing a deployment end to end. It adds **no new authority** — it is a client of
+admin surfaces that already exist.
+
+> **Status: Slice 0 — runnable skeleton.** This is the first implemented slice. It is a real,
+> runnable server (loopback HTTP, a paste-the-token login that mints a session, a Dashboard) — but
+> **the data layer is intentionally stubbed**: no per-service client libraries exist yet, so the
+> Dashboard honestly reports `n/a — client not wired yet` for each of the six services. Later slices
+> add the client libs + pages (identities, keys, audit, certificates) and the exercise harness. The
+> full design is in [`docs/design/mini-console.md`](../../docs/design/mini-console.md); the Slice 0
+> plan is in [`docs/design/mini-console-slice0.md`](../../docs/design/mini-console-slice0.md). A
+> proper teaching README replaces this one once the screens exist.
+
+## What's here in Slice 0
+
+- A loopback `HttpServer` (one virtual thread per request), bound `127.0.0.1` by default.
+- **Console login:** the operator pastes the bootstrap console token into a form; it is compared in
+  constant time (never logged), and on success the console mints a **mini-token `SessionService`**
+  session stored in an atomic-`0600` `console-sessions.json`. The session cookie is the
+  console-specific `mini-console-session` (deliberately **not** the family SSO cookie, so the two
+  never collide on a shared host). Every page but `/login` and `/health` requires a valid session.
+- **CSRF** (double-submit cookie) on the login and logout POSTs.
+- A **Dashboard** that lists the six services, each marked "client not wired yet" — it calls nothing
+  downstream and fabricates no data (the honest seam).
+
+## Run it locally
+
+The bootstrap console token comes from an env var or a file, **never a CLI arg, and is never
+logged**. Loopback by default.
 
-> **Roadmap placeholder — there is no logic here yet.** This module deliberately contains no UI and
-> no server code. It exists so the umbrella build and `docs/DIRECTION.md` can refer to mini-console
-> as a real, compiling module *before* any of it is written. If you came here to learn how a service
-> in this family works, read one of the shipping services instead — **[mini-kms](../mini-kms)** and
-> **[mini-idp](../mini-idp)** are the most heavily commented, and **[mini-directory](../mini-directory)**,
-> **[mini-oidc](../mini-oidc)**, **[mini-gateway](../mini-gateway)**, and **[mini-ca](../mini-ca)**
-> round out the set.
-
-## Table of contents
-
-- [Why it's a placeholder](#why-its-a-placeholder)
-- [What's actually in the module today](#whats-actually-in-the-module-today)
-- [Intended scope (when it gets built)](#intended-scope-when-it-gets-built)
-- [Where it would fit in the family](#where-it-would-fit-in-the-family)
-- [Building & testing](#building--testing)
-
-## Why it's a placeholder
-
-The family ethos (see the root `CLAUDE.md`) is that **scaffolds say so** — a placeholder must not
-masquerade as a half-built service that *looks* finished. mini-console is the purest form of that
-rule: it claims the name and the base package `com.codeheadsystems.miniconsole`, compiles, and
-passes one trivial guard test, and that is **all** it does. Reserving the module now means:
-
-- the single aggregator build (`./gradlew build`) already knows about it, so wiring it up later is
-  additive rather than structural;
-- `docs/DIRECTION.md` and the layout table in `CLAUDE.md` can list it as a real Gradle project; and
-- nobody mistakes an empty directory for "lost" code — the placeholder is explicit and self-documenting.
-
-It is a **plain library** (`miniauth.library-conventions`, *not* `application-conventions`) precisely
-because there is nothing to run. The day it grows a transport, it graduates to the application plugin
-like the other front doors.
-
-## What's actually in the module today
-
-Two files, both honest about the module's status:
-
-```
-services/mini-console/
-├── build.gradle.kts                                   # library-conventions; no deps beyond JUnit
-└── src/
-    ├── main/java/com/codeheadsystems/miniconsole/MiniConsole.java       # IMPLEMENTED = false
-    └── test/java/com/codeheadsystems/miniconsole/MiniConsoleTest.java   # asserts NOT implemented
-```
-
-`MiniConsole` is a final, non-instantiable class exposing a single flag:
-
-```java
-public static final boolean IMPLEMENTED = false;
-```
-
-and `MiniConsoleTest` is the guard that keeps everyone honest:
-
-```java
-@Test
-void isStillARoadmapPlaceholder() {
-  // This guard flips to a real assertion when mini-console starts being implemented.
-  assertFalse(MiniConsole.IMPLEMENTED);
-}
-```
-
-When real work begins, flipping `IMPLEMENTED` to `true` makes this test fail — a deliberate
-trip-wire that forces whoever starts the implementation to replace the placeholder guard with real
-tests, so the module can never quietly drift from "placeholder" to "half-built."
-
-## Intended scope (when it gets built)
-
-A single, optional, **admin-only** console that composes the existing services' admin APIs — it would
-*invent no new authority of its own*, only present what the services already expose:
-
-- **Identities** — browse and edit mini-directory's humans, service accounts, groups, and roles, and
-  preview a principal's resolved grants (the `/admin/principals/{id}/resolution` view).
-- **Keys** — trigger and review mini-token signing-key rotation across the issuers, and manage
-  mini-kms key groups (create / rotate / disable / destroy).
-- **Audit** — read the issuance / rotation / revocation audit logs the services keep.
-- **Certificates** — review mini-ca's issuance log and revocation list.
-
-Like the rest of the family it would bind to **loopback by default**, gate everything behind a
-bootstrap admin token resolved from env/file (never argv, never logged), and keep **no secrets in
-logs**. It is explicitly **not scheduled** — see the *Future tracks* note in `docs/DIRECTION.md`.
-
-## Where it would fit in the family
-
-mini-console sits *above* the services as a pure consumer of their admin surfaces — it is a client,
-not a new source of truth:
-
-```
-                        ┌─────────────────────────────────────────────┐
-                        │              mini-console (UI)               │   ← roadmap; reads/calls
-                        └───┬──────────┬──────────┬──────────┬─────────┘     existing admin APIs only
-                            │          │          │          │
-                    mini-directory  mini-idp   mini-oidc   mini-kms / mini-ca
-                    (identities)   (m2m tokens)(human SSO) (keys / certs)
+```bash
+export MINICONSOLE_ADMIN_TOKEN="$(openssl rand -hex 32)"
+./gradlew :services:mini-console:installDist
+services/mini-console/build/install/mini-console/bin/mini-console --port 8500 --data-dir ~/.mini-console
+# Sign in at http://127.0.0.1:8500/login  (health check: http://127.0.0.1:8500/health)
 ```
 
-Because it would only call APIs that already exist, mini-console adds **no** new trust boundary —
-which is exactly why it can wait until the services beneath it have settled.
-
 ## Building & testing
 
 It participates in the one aggregator build like every other module:
 
 ```bash
-./gradlew build                          # compiles mini-console + runs its single guard test
-./gradlew :services:mini-console:test    # just this module's test
+./gradlew build                          # compiles mini-console + runs its tests (the CI gate)
+./gradlew :services:mini-console:test    # just this module's tests
 ```
 
-There is nothing to install or run (no `application` plugin, no `installDist`). This README will be
-replaced with a real teaching document — endpoints, screens, the security model — if and when
-mini-console is actually implemented.
+## Security model (Slice 0)
+
+- **No new authority.** The console stores no identity, no grants, no keys — only its own
+  login-session state. Every later action will equal an operator curling a downstream admin API.
+- **Loopback bind by default;** any LAN exposure is an explicit operator decision behind a TLS
+  reverse proxy with `--secure-cookies`.
+- **No secrets in logs.** The console token travels only in the login POST body; the access log
+  records method/path/status only. **No oracle:** a wrong token and a missing token are
+  indistinguishable, and a CSRF failure collapses to one generic error.
diff --git a/services/mini-console/build.gradle.kts b/services/mini-console/build.gradle.kts
index c70ea0d..9a5cde2 100644
--- a/services/mini-console/build.gradle.kts
+++ b/services/mini-console/build.gradle.kts
@@ -1,17 +1,26 @@
 /*
- * mini-console - unified admin UI (ROADMAP PLACEHOLDER).
+ * mini-console - the optional unified admin console over the mini- family.
  *
- * Reserved for an optional single admin UI over the family: inspect mini-directory identities,
- * rotate mini-token signing keys, review audit logs, manage mini-kms key groups. There is NO
- * logic here yet — this module only claims the name and package. See docs/DIRECTION.md.
+ * Slice 0: the runnable skeleton — a loopback HTTP server, a console-login session, and a Dashboard
+ * that honestly reports "client not wired yet" for each downstream service (no client libs exist
+ * yet). It invents NO new authority; later slices add the per-service client libraries + pages.
  *
- * A plain library (no `application` plugin) precisely because there is nothing to run.
+ * Graduates from library-conventions to application-conventions (it is now runnable).
  */
 
 plugins {
-    id("miniauth.library-conventions")
+    id("miniauth.application-conventions")
 }
 
 dependencies {
+    // The shared browser-session mechanism (SessionService) + the DocumentStore SPI the copied
+    // JsonStore implements. This is the ONLY family dependency Slice 0 genuinely needs.
+    implementation(project(":libs:mini-token"))
+    // JSON for the session store document (Sessions) and the /health body.
+    implementation(libs.jackson.databind)
     // JUnit 5 (jupiter + launcher) is supplied by the convention plugin.
 }
+
+application {
+    mainClass = "com.codeheadsystems.miniconsole.ServerMain"
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/MiniConsole.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/MiniConsole.java
deleted file mode 100644
index 80dd82e..0000000
--- a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/MiniConsole.java
+++ /dev/null
@@ -1,17 +0,0 @@
-package com.codeheadsystems.miniconsole;
-
-/**
- * Placeholder for mini-console, a future optional unified admin UI over the family.
- *
- * <p><b>Roadmap only.</b> This module deliberately contains no UI or server logic. It reserves the
- * name and package so the umbrella build and the direction doc can refer to it as a real,
- * compiling module before any code exists. See {@code docs/DIRECTION.md}.
- */
-public final class MiniConsole {
-
-  /** Marks this module as a not-yet-implemented roadmap track. */
-  public static final boolean IMPLEMENTED = false;
-
-  private MiniConsole() {
-  }
-}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/ServerMain.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/ServerMain.java
new file mode 100644
index 0000000..ef60ab3
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/ServerMain.java
@@ -0,0 +1,87 @@
+package com.codeheadsystems.miniconsole;
+
+import com.codeheadsystems.miniconsole.server.ConsoleConfig;
+import com.codeheadsystems.miniconsole.server.ConsoleServer;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.time.Clock;
+import java.util.Map;
+import java.util.concurrent.CountDownLatch;
+
+/**
+ * mini-console entry point — the optional unified admin console over the mini- family.
+ *
+ * <p>Startup mirrors the siblings: resolve {@link ConsoleConfig}, resolve the bootstrap console token
+ * (env/file, never argv, never logged), build {@link ConsoleServer}, then bind loopback and serve.
+ *
+ * <p><b>Loopback / TLS.</b> The server binds {@code 127.0.0.1} by default. Exposing it on a LAN is an
+ * explicit operator decision and MUST be done behind a TLS-terminating reverse proxy, with
+ * {@code --secure-cookies} enabled.
+ */
+public final class ServerMain {
+
+  static final String ENV_ADMIN_TOKEN = "MINICONSOLE_ADMIN_TOKEN";
+
+  private ServerMain() {
+  }
+
+  /** @param args CLI arguments (see {@link ConsoleConfig}). */
+  public static void main(final String[] args) {
+    try {
+      run(args, System.getenv());
+    } catch (final IllegalArgumentException | IllegalStateException e) {
+      System.err.println("Configuration error: " + e.getMessage());
+      System.exit(64);
+    } catch (final IOException e) {
+      System.err.println("I/O error: " + e.getMessage());
+      System.exit(74);
+    }
+  }
+
+  private static void run(final String[] args, final Map<String, String> env) throws IOException {
+    final ConsoleConfig config = ConsoleConfig.resolve(args, env);
+    final String consoleToken = resolveToken(env.get(ENV_ADMIN_TOKEN), config.adminTokenFilePath(),
+        "no console token configured: set " + ENV_ADMIN_TOKEN + " or provide --admin-token-file");
+
+    final ConsoleServer server = ConsoleServer.create(config, consoleToken, Clock.systemUTC());
+
+    final CountDownLatch shutdown = new CountDownLatch(1);
+    Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+      server.stop();
+      shutdown.countDown();
+    }, "miniconsole-shutdown"));
+
+    server.start();
+    System.out.println("mini-console is running on http://" + server.address().getHostString()
+        + ":" + server.address().getPort());
+    System.out.println("data dir: " + config.dataDir());
+    System.out.println("Sign in at http://" + server.address().getHostString() + ":"
+        + server.address().getPort() + "/login");
+    System.out.println("Press Ctrl-C to stop.");
+    awaitShutdown(shutdown);
+  }
+
+  private static String resolveToken(final String fromEnv, final Path file, final String missingMessage)
+      throws IOException {
+    if (fromEnv != null && !fromEnv.isBlank()) {
+      return fromEnv.trim();
+    }
+    if (file != null) {
+      final String fromFile = Files.readString(file, StandardCharsets.UTF_8).strip();
+      if (!fromFile.isEmpty()) {
+        return fromFile;
+      }
+    }
+    throw new IllegalStateException(missingMessage);
+  }
+
+  private static void awaitShutdown(final CountDownLatch shutdown) {
+    try {
+      shutdown.await();
+    } catch (final InterruptedException e) {
+      Thread.currentThread().interrupt();
+    }
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/DashboardPage.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/DashboardPage.java
new file mode 100644
index 0000000..1a322a4
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/DashboardPage.java
@@ -0,0 +1,67 @@
+package com.codeheadsystems.miniconsole.pages;
+
+import java.util.List;
+
+/**
+ * The Dashboard — the one authenticated page in Slice 0.
+ *
+ * <p>It proves the server renders an authenticated page while being <b>honest about what is not yet
+ * built</b>: it calls nothing downstream and fabricates no health data. Each family service is shown
+ * with a literal "n/a — client not wired yet" status plus the slice that will wire it. As later
+ * slices add a client library, its row flips from this placeholder to a real {@code health()} result.
+ * This is the honest seam the family ethos requires — a placeholder that says so.
+ */
+public final class DashboardPage {
+
+  /** One service row: display name and the slice number that wires its client. */
+  private record Service(String name, int slice) {
+  }
+
+  // The six downstream services and the slice where each gets a client + page (see the roadmap in
+  // docs/design/mini-console.md). None are wired in Slice 0.
+  private static final List<Service> SERVICES = List.of(
+      new Service("mini-directory", 1),
+      new Service("mini-idp", 3),
+      new Service("mini-kms", 4),
+      new Service("mini-ca", 5),
+      new Service("mini-oidc", 6),
+      new Service("mini-gateway", 7));
+
+  private DashboardPage() {
+  }
+
+  /**
+   * @param boundAddress the host:port the console is bound to (for the self-status line).
+   * @param csrf         the CSRF token for the logout form (escaped here).
+   * @return a complete HTML document.
+   */
+  public static String render(final String boundAddress, final String csrf) {
+    final StringBuilder rows = new StringBuilder();
+    for (final Service service : SERVICES) {
+      rows.append("<tr><td>").append(Layout.escape(service.name()))
+          .append("</td><td class=\"muted\">n/a — client not wired yet (Slice ")
+          .append(service.slice()).append(")</td></tr>");
+    }
+
+    final String nav = """
+        <form method="post" action="/logout" style="margin:0">
+          <input type="hidden" name="csrf" value="$CSRF">
+          <button type="submit">Sign out</button>
+        </form>
+        """.replace("$CSRF", Layout.escape(csrf));
+
+    final String body = """
+        <p>mini-console is running on <code>$ADDR</code>, signed in as <code>console-admin</code>.</p>
+        <p class="muted">This console adds no new authority — it is a client of admin surfaces that
+        already exist. The data layer below is intentionally stubbed in this slice.</p>
+        <table>
+          <thead><tr><th>Service</th><th>Status</th></tr></thead>
+          <tbody>$ROWS</tbody>
+        </table>
+        """
+        .replace("$ADDR", Layout.escape(boundAddress))
+        .replace("$ROWS", rows.toString());
+
+    return Layout.page("Dashboard", nav, body);
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/Layout.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/Layout.java
new file mode 100644
index 0000000..edaf0a6
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/Layout.java
@@ -0,0 +1,65 @@
+package com.codeheadsystems.miniconsole.pages;
+
+/**
+ * The shared HTML chrome for every console page: a minimal, dependency-free document with a nav bar.
+ *
+ * <p>Hand-rolled in the spirit of mini-oidc's {@code LoginPages} — no template engine, no JS build,
+ * no client-side framework. Every dynamic value a page interpolates MUST be passed through
+ * {@link #escape} first; a page <b>never</b> renders a secret (the console holds tokens, but no page
+ * shows them).
+ */
+public final class Layout {
+
+  private Layout() {
+  }
+
+  /**
+   * Wrap a page body in the shared document chrome.
+   *
+   * @param title   the page title (shown in {@code <title>} and the header; escaped).
+   * @param navHtml already-built nav markup (e.g. a logout form), or empty string for the login page.
+   * @param bodyHtml the already-built, already-escaped page body markup.
+   * @return a complete HTML document.
+   */
+  public static String page(final String title, final String navHtml, final String bodyHtml) {
+    return """
+        <!DOCTYPE html>
+        <html lang="en"><head><meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <title>$TITLE — mini-console</title>
+        <style>
+          body { font-family: system-ui, sans-serif; max-width: 52rem; margin: 2rem auto; padding: 0 1rem; color: #1a1a1a; }
+          header { display: flex; justify-content: space-between; align-items: center; border-bottom: 1px solid #ddd; padding-bottom: .5rem; }
+          h1 { font-size: 1.3rem; margin: 0; }
+          table { border-collapse: collapse; width: 100%; margin-top: 1rem; }
+          th, td { text-align: left; padding: .4rem .6rem; border-bottom: 1px solid #eee; }
+          .muted { color: #888; }
+          button { font: inherit; padding: .4rem .8rem; cursor: pointer; }
+          input[type=password] { font: inherit; padding: .4rem; width: 100%; box-sizing: border-box; }
+          .err { color: #b00020; }
+        </style></head>
+        <body>
+        <header><h1>$TITLE</h1>$NAV</header>
+        $BODY
+        </body></html>
+        """
+        .replace("$TITLE", escape(title))
+        .replace("$NAV", navHtml)
+        .replace("$BODY", bodyHtml);
+  }
+
+  /**
+   * HTML-escape a value for safe interpolation into element text or an attribute. Copied verbatim
+   * from mini-oidc's {@code LoginPages.escape}.
+   *
+   * @param value the raw value (may be null → empty string).
+   * @return the entity-escaped value.
+   */
+  public static String escape(final String value) {
+    if (value == null) {
+      return "";
+    }
+    return value.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+        .replace("\"", "&quot;").replace("'", "&#39;");
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/LoginPage.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/LoginPage.java
new file mode 100644
index 0000000..1d9da18
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/pages/LoginPage.java
@@ -0,0 +1,38 @@
+package com.codeheadsystems.miniconsole.pages;
+
+/**
+ * The console sign-in page: a single form into which the operator pastes the bootstrap console
+ * token.
+ *
+ * <p>Modeled on mini-oidc's {@code LoginPages.login} but drastically simpler — there is no WebAuthn
+ * ceremony, just a password-typed field POSTed to {@code /login}. The token travels in the POST body
+ * (never a URL or header), so it never lands in the access log. A hidden CSRF field carries the
+ * double-submit token. On a failed attempt the page shows a single generic message — it never
+ * distinguishes a wrong token from a missing one (no oracle).
+ */
+public final class LoginPage {
+
+  private LoginPage() {
+  }
+
+  /**
+   * @param csrf  the freshly-minted CSRF token to embed (also set as the {@code mini-console-csrf}
+   *              cookie by the handler); escaped here.
+   * @param error whether to show the generic sign-in-failed message.
+   * @return a complete HTML document.
+   */
+  public static String render(final String csrf, final boolean error) {
+    final String body = """
+        <p>Sign in with your console admin token.</p>
+        $ERR
+        <form method="post" action="/login">
+          <input type="hidden" name="csrf" value="$CSRF">
+          <p><input type="password" name="token" placeholder="console admin token" autofocus></p>
+          <p><button type="submit">Sign in</button></p>
+        </form>
+        """
+        .replace("$ERR", error ? "<p class=\"err\">Sign-in failed.</p>" : "")
+        .replace("$CSRF", Layout.escape(csrf));
+    return Layout.page("Sign in", "", body);
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/AdminAuthenticator.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/AdminAuthenticator.java
new file mode 100644
index 0000000..183da7a
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/AdminAuthenticator.java
@@ -0,0 +1,76 @@
+package com.codeheadsystems.miniconsole.server;
+
+import com.codeheadsystems.miniconsole.server.http.ApiException;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+
+/**
+ * Guards the console with a single bootstrap console credential (a token), validated in constant
+ * time.
+ *
+ * <p>This mirrors the family's {@code AdminAuthenticator}: the expected token is resolved once at
+ * startup from an env var or a file (never a CLI flag, never logged), and presented tokens are
+ * compared with {@link MessageDigest#isEqual} so a match can't be recovered byte-by-byte via timing.
+ *
+ * <p>The console is a human-in-a-browser tool, so the token is presented by being <b>pasted into the
+ * login form</b> rather than sent as a {@code Authorization: Bearer} header — {@link #matches} is the
+ * form-login path. {@link #requireAdmin} is kept for any future header-guarded endpoint. After a
+ * successful paste the console mints a {@code SessionService} session, and the session cookie (not
+ * the token) authorizes subsequent requests.
+ */
+public final class AdminAuthenticator {
+
+  private final byte[] expectedToken;
+
+  /**
+   * @param expectedToken the console token a login must present; must be non-empty.
+   */
+  public AdminAuthenticator(final String expectedToken) {
+    if (expectedToken == null || expectedToken.isEmpty()) {
+      throw new IllegalArgumentException("console token must not be empty");
+    }
+    this.expectedToken = expectedToken.getBytes(StandardCharsets.UTF_8);
+  }
+
+  /**
+   * Constant-time compare a presented token (e.g. pasted into the login form) against the expected
+   * console token.
+   *
+   * @param presented the token the operator supplied (may be null/blank).
+   * @return true iff it matches the expected token.
+   */
+  public boolean matches(final String presented) {
+    if (presented == null || presented.isEmpty()) {
+      // Constant-time-ish: still touch the expected buffer so a missing token is not faster.
+      MessageDigest.isEqual(expectedToken, new byte[expectedToken.length]);
+      return false;
+    }
+    return MessageDigest.isEqual(expectedToken, presented.getBytes(StandardCharsets.UTF_8));
+  }
+
+  /**
+   * Require a valid console bearer token on the request, or throw 401. Unused by Slice 0's
+   * form-login flow, but kept so a future header-guarded endpoint follows the family pattern.
+   *
+   * @param authorizationHeader the raw {@code Authorization} header value (may be null).
+   * @throws ApiException 401 if the header is missing, malformed, or the token does not match.
+   */
+  public void requireAdmin(final String authorizationHeader) {
+    if (!matches(bearerToken(authorizationHeader))) {
+      throw ApiException.unauthorized();
+    }
+  }
+
+  private static String bearerToken(final String authorizationHeader) {
+    if (authorizationHeader == null) {
+      return null;
+    }
+    final String prefix = "Bearer ";
+    if (authorizationHeader.length() <= prefix.length()
+        || !authorizationHeader.regionMatches(true, 0, prefix, 0, prefix.length())) {
+      return null;
+    }
+    final String token = authorizationHeader.substring(prefix.length()).trim();
+    return token.isEmpty() ? null : token;
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleConfig.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleConfig.java
new file mode 100644
index 0000000..1b2674e
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleConfig.java
@@ -0,0 +1,145 @@
+package com.codeheadsystems.miniconsole.server;
+
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.time.Duration;
+import java.util.Map;
+
+/**
+ * Resolved server configuration for the admin console. Values come from CLI flags (highest
+ * priority), then environment variables, then per-user defaults — mirroring the family's other
+ * {@code ServerConfig}s, trimmed to what a console needs (it has no issuer/argon/KMS knobs in
+ * Slice 0).
+ *
+ * <pre>
+ *   --host H                  MINICONSOLE_HOST                loopback bind host (default 127.0.0.1)
+ *   --port N                  MINICONSOLE_PORT                TCP port (default 8500)
+ *   --data-dir PATH           MINICONSOLE_DATA_DIR            directory for the session store
+ *   --admin-token-file PATH   MINICONSOLE_ADMIN_TOKEN_FILE    file holding the console token (alt: MINICONSOLE_ADMIN_TOKEN env)
+ *   --secure-cookies          MINICONSOLE_SECURE_COOKIES      set the Secure flag on cookies (use behind TLS)
+ *   --session-ttl-seconds N   MINICONSOLE_SESSION_TTL_SECONDS console-login session lifetime (default 43200 = 12h)
+ * </pre>
+ */
+public final class ConsoleConfig {
+
+  /** Default loopback bind host. */
+  public static final String DEFAULT_HOST = "127.0.0.1";
+  /** Default TCP port (one above mini-ca's 8499). */
+  public static final int DEFAULT_PORT = 8500;
+  /** Default console-login session lifetime (12 hours). */
+  public static final int DEFAULT_SESSION_TTL_SECONDS = 43_200;
+
+  private final String host;
+  private final int port;
+  private final Path dataDir;
+  private final Path adminTokenFilePath;
+  private final boolean secureCookies;
+  private final Duration sessionTtl;
+
+  ConsoleConfig(final String host, final int port, final Path dataDir, final Path adminTokenFilePath,
+                final boolean secureCookies, final Duration sessionTtl) {
+    this.host = host;
+    this.port = port;
+    this.dataDir = dataDir;
+    this.adminTokenFilePath = adminTokenFilePath;
+    this.secureCookies = secureCookies;
+    this.sessionTtl = sessionTtl;
+  }
+
+  /** Resolve configuration from CLI args and the environment. */
+  public static ConsoleConfig resolve(final String[] args, final Map<String, String> env) {
+    String host = env.get("MINICONSOLE_HOST");
+    Integer port = envInt(env, "MINICONSOLE_PORT");
+    String dataDir = env.get("MINICONSOLE_DATA_DIR");
+    String adminTokenFile = env.get("MINICONSOLE_ADMIN_TOKEN_FILE");
+    boolean secureCookies = "true".equalsIgnoreCase(env.get("MINICONSOLE_SECURE_COOKIES"));
+    Integer sessionTtl = envInt(env, "MINICONSOLE_SESSION_TTL_SECONDS");
+
+    for (int i = 0; i < args.length; i++) {
+      final String arg = args[i];
+      switch (arg) {
+        case "--host" -> host = requireValue(args, ++i, arg);
+        case "--port" -> port = Integer.parseInt(requireValue(args, ++i, arg));
+        case "--data-dir" -> dataDir = requireValue(args, ++i, arg);
+        case "--admin-token-file" -> adminTokenFile = requireValue(args, ++i, arg);
+        case "--secure-cookies" -> secureCookies = true;
+        case "--session-ttl-seconds" -> sessionTtl = Integer.parseInt(requireValue(args, ++i, arg));
+        default -> throw new IllegalArgumentException("unknown argument: " + arg);
+      }
+    }
+
+    final String resolvedHost = host != null && !host.isBlank() ? host : DEFAULT_HOST;
+    final int resolvedPort = port != null ? port : DEFAULT_PORT;
+    if (resolvedPort < 0 || resolvedPort > 65535) {
+      throw new IllegalArgumentException("port must be in 0..65535");
+    }
+
+    return new ConsoleConfig(
+        resolvedHost, resolvedPort,
+        dataDir != null ? Paths.get(dataDir) : defaultDataDir(env),
+        adminTokenFile != null ? Paths.get(adminTokenFile) : null,
+        secureCookies,
+        Duration.ofSeconds(positiveOr(sessionTtl, DEFAULT_SESSION_TTL_SECONDS)));
+  }
+
+  /** @return the loopback bind host. */
+  public String host() {
+    return host;
+  }
+
+  /** @return the TCP port (0 binds an ephemeral port — useful in tests). */
+  public int port() {
+    return port;
+  }
+
+  /** @return the directory holding the console session store. */
+  public Path dataDir() {
+    return dataDir;
+  }
+
+  /** @return the file the console token may be read from, or null (then the env var is required). */
+  public Path adminTokenFilePath() {
+    return adminTokenFilePath;
+  }
+
+  /** @return whether to set the {@code Secure} flag on cookies (enable behind TLS). */
+  public boolean secureCookies() {
+    return secureCookies;
+  }
+
+  /** @return the console-login session lifetime. */
+  public Duration sessionTtl() {
+    return sessionTtl;
+  }
+
+  private static int positiveOr(final Integer value, final int fallback) {
+    if (value == null) {
+      return fallback;
+    }
+    if (value < 1) {
+      throw new IllegalArgumentException("session TTL must be at least 1 second");
+    }
+    return value;
+  }
+
+  private static Path defaultDataDir(final Map<String, String> env) {
+    final String xdg = env.get("XDG_DATA_HOME");
+    if (xdg != null && !xdg.isBlank()) {
+      return Paths.get(xdg, "mini-console");
+    }
+    final String home = env.getOrDefault("HOME", System.getProperty("user.home", "."));
+    return Paths.get(home, ".mini-console");
+  }
+
+  private static Integer envInt(final Map<String, String> env, final String key) {
+    final String value = env.get(key);
+    return value == null ? null : Integer.valueOf(value.trim());
+  }
+
+  private static String requireValue(final String[] args, final int index, final String flag) {
+    if (index >= args.length) {
+      throw new IllegalArgumentException("flag " + flag + " requires a value");
+    }
+    return args[index];
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleHandlers.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleHandlers.java
new file mode 100644
index 0000000..4c19e78
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleHandlers.java
@@ -0,0 +1,131 @@
+package com.codeheadsystems.miniconsole.server;
+
+import com.codeheadsystems.miniconsole.pages.DashboardPage;
+import com.codeheadsystems.miniconsole.pages.LoginPage;
+import com.codeheadsystems.miniconsole.server.http.ApiException;
+import com.codeheadsystems.miniconsole.server.http.HttpResponse;
+import com.codeheadsystems.miniconsole.server.http.RequestContext;
+import com.codeheadsystems.miniconsole.server.http.Router;
+import java.util.Map;
+
+/**
+ * The Slice 0 route table: a public health check, a paste-the-token login that mints a session, an
+ * authenticated Dashboard, and logout.
+ *
+ * <p>Auth model: the console token is the bootstrap credential, presented once by being pasted into
+ * the {@code /login} form (constant-time compared, never logged). On success the console mints a
+ * {@link ConsoleSession} and the {@link Cookies#SESSION} cookie carries it forward; every page but
+ * {@code /login} and {@code /health} requires a valid session, else a browser-friendly 302 to
+ * {@code /login} (no 401 body, no oracle). State-changing POSTs ({@code /login}, {@code /logout})
+ * carry a double-submit {@link Csrf} token.
+ */
+public final class ConsoleHandlers {
+
+  /** How long the short-lived CSRF cookie lives (long enough to submit the form). */
+  private static final long CSRF_TTL_SECONDS = 3600;
+
+  private final ConsoleSession session;
+  private final AdminAuthenticator auth;
+  private final Cookies cookies;
+  private final Csrf csrf;
+  private final long sessionTtlSeconds;
+
+  /**
+   * @param session           the console-login session store.
+   * @param auth              the console-token constant-time comparator.
+   * @param cookies           the cookie builder (console-specific names).
+   * @param csrf              the double-submit CSRF helper.
+   * @param sessionTtlSeconds the session cookie {@code Max-Age}.
+   */
+  public ConsoleHandlers(final ConsoleSession session, final AdminAuthenticator auth,
+                         final Cookies cookies, final Csrf csrf, final long sessionTtlSeconds) {
+    this.session = session;
+    this.auth = auth;
+    this.cookies = cookies;
+    this.csrf = csrf;
+    this.sessionTtlSeconds = sessionTtlSeconds;
+  }
+
+  /** @return the router with the Slice 0 routes registered. */
+  public Router router() {
+    return new Router()
+        .route("GET", "/health", this::health)
+        .route("GET", "/login", this::loginForm)
+        .route("POST", "/login", this::loginSubmit)
+        .route("GET", "/", this::dashboard)
+        .route("POST", "/logout", this::logout);
+  }
+
+  /** Public liveness — no session required, no downstream calls. */
+  private HttpResponse health(final RequestContext context) {
+    return HttpResponse.json(200, Map.of("status", "ok"));
+  }
+
+  /** Render the sign-in form with a fresh CSRF token (set as the matching cookie). */
+  private HttpResponse loginForm(final RequestContext context) {
+    final String token = csrf.mint();
+    return HttpResponse.html(LoginPage.render(token, false))
+        .header("Set-Cookie", cookies.csrf(token, CSRF_TTL_SECONDS));
+  }
+
+  /**
+   * Validate CSRF, then constant-time compare the pasted token. On success mint a session and
+   * redirect to the Dashboard; on failure re-render the login page with a single generic message
+   * (no oracle: a wrong token and a missing one are indistinguishable).
+   */
+  private HttpResponse loginSubmit(final RequestContext context) {
+    final Map<String, String> form = context.formParams();
+    if (!csrf.verify(context.cookie(Cookies.CSRF), form.get("csrf"))) {
+      throw ApiException.badRequest("invalid or missing CSRF token");
+    }
+    if (!auth.matches(form.get("token"))) {
+      // Re-render at 200 with a fresh CSRF token; reveal nothing about why it failed.
+      final String token = csrf.mint();
+      return HttpResponse.html(LoginPage.render(token, true))
+          .header("Set-Cookie", cookies.csrf(token, CSRF_TTL_SECONDS));
+    }
+    final String sessionId = session.establish();
+    return HttpResponse.redirect("/")
+        .header("Set-Cookie", cookies.session(sessionId, sessionTtlSeconds));
+  }
+
+  /** The authenticated Dashboard; 302 to /login without a valid session. */
+  private HttpResponse dashboard(final RequestContext context) {
+    final HttpResponse redirect = requireSession(context);
+    if (redirect != null) {
+      return redirect;
+    }
+    // A fresh CSRF token for the logout form (double-submit).
+    final String token = csrf.mint();
+    final String host = context.header("Host");
+    final String address = host != null ? host : "loopback";
+    return HttpResponse.html(DashboardPage.render(address, token))
+        .header("Set-Cookie", cookies.csrf(token, CSRF_TTL_SECONDS));
+  }
+
+  /** Destroy the session and clear the cookie; requires a valid session + CSRF. */
+  private HttpResponse logout(final RequestContext context) {
+    final HttpResponse redirect = requireSession(context);
+    if (redirect != null) {
+      return redirect;
+    }
+    if (!csrf.verify(context.cookie(Cookies.CSRF), context.formParams().get("csrf"))) {
+      throw ApiException.badRequest("invalid or missing CSRF token");
+    }
+    session.end(context.cookie(Cookies.SESSION));
+    return HttpResponse.redirect("/login")
+        .header("Set-Cookie", cookies.clearSession());
+  }
+
+  /**
+   * @return a 302-to-login response if there is no valid session, else null (caller proceeds). The
+   *     browser-friendly equivalent of a 401 — no body, no detail.
+   */
+  private HttpResponse requireSession(final RequestContext context) {
+    final String sessionId = context.cookie(Cookies.SESSION);
+    if (sessionId == null || !session.isValid(sessionId)) {
+      return HttpResponse.redirect("/login");
+    }
+    return null;
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleServer.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleServer.java
new file mode 100644
index 0000000..71fe214
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleServer.java
@@ -0,0 +1,73 @@
+package com.codeheadsystems.miniconsole.server;
+
+import com.codeheadsystems.miniconsole.server.http.Router;
+import com.sun.net.httpserver.HttpServer;
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.time.Clock;
+import java.util.concurrent.Executors;
+
+/**
+ * Assembles the admin console and exposes it through a loopback {@link HttpServer}.
+ *
+ * <p>This is the composition root. It wires the console-login session ({@link ConsoleSession} over an
+ * atomic-{@code 0600} JSON store), the constant-time token comparator ({@link AdminAuthenticator}),
+ * the cookie/CSRF helpers, and the route table ({@link ConsoleHandlers}), then binds loopback and
+ * serves each request on a virtual thread — exactly as the family's other servers do.
+ *
+ * <p>The console adds no new authority: Slice 0 holds only its own bootstrap console token and a
+ * session store; the Dashboard calls nothing downstream.
+ */
+public final class ConsoleServer {
+
+  private final HttpServer httpServer;
+  private final ConsoleConfig config;
+
+  private ConsoleServer(final HttpServer httpServer, final ConsoleConfig config) {
+    this.httpServer = httpServer;
+    this.config = config;
+  }
+
+  /**
+   * Build a server from configuration and the resolved console token.
+   *
+   * @param config       the resolved configuration.
+   * @param consoleToken the bootstrap console token guarding login (resolved from env/file).
+   * @param clock        the clock shared by the session store.
+   * @return a built, not-yet-started server.
+   * @throws IOException if the listening socket cannot be opened.
+   */
+  public static ConsoleServer create(final ConsoleConfig config, final String consoleToken,
+                                     final Clock clock) throws IOException {
+    final ConsoleSession session = new ConsoleSession(config.dataDir(), clock, config.sessionTtl());
+    final ConsoleHandlers handlers = new ConsoleHandlers(
+        session, new AdminAuthenticator(consoleToken), new Cookies(config.secureCookies()),
+        new Csrf(), config.sessionTtl().toSeconds());
+    final Router router = handlers.router();
+
+    final HttpServer http = HttpServer.create(new InetSocketAddress(config.host(), config.port()), 0);
+    http.createContext("/", router);
+    http.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
+    return new ConsoleServer(http, config);
+  }
+
+  /** Start serving (non-blocking; the JDK server runs its own threads). */
+  public void start() {
+    httpServer.start();
+  }
+
+  /** Stop serving, allowing in-flight exchanges a moment to finish. */
+  public void stop() {
+    httpServer.stop(1);
+  }
+
+  /** @return the actual bound address (useful when the configured port was 0/ephemeral). */
+  public InetSocketAddress address() {
+    return httpServer.getAddress();
+  }
+
+  /** @return the configuration this server was built from. */
+  public ConsoleConfig config() {
+    return config;
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleSession.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleSession.java
new file mode 100644
index 0000000..d7f5d33
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/ConsoleSession.java
@@ -0,0 +1,58 @@
+package com.codeheadsystems.miniconsole.server;
+
+import com.codeheadsystems.miniconsole.store.JsonStore;
+import com.codeheadsystems.minitoken.session.SessionService;
+import com.codeheadsystems.minitoken.session.Sessions;
+import java.nio.file.Path;
+import java.time.Clock;
+import java.time.Duration;
+
+/**
+ * The console-login session: a thin wrapper over mini-token's {@link SessionService} so the console
+ * reuses the family's proven, file-backed session mechanism rather than inventing a second one.
+ *
+ * <p>Two deliberate differences from mini-oidc's use of the same machinery:
+ * <ul>
+ *   <li>It is backed by the console's <b>own</b> store ({@code console-sessions.json}), a separate
+ *       namespace from the family SSO session file — the console is the sole writer of its store.</li>
+ *   <li>The session cookie uses the console-specific {@link Cookies#SESSION} name, never the shared
+ *       SSO cookie, so the two can't collide on a co-hosted setup.</li>
+ * </ul>
+ *
+ * <p>The console has a single principal: the operator who presented the bootstrap console token. We
+ * record it as {@code "console-admin"} (a fixed subject — no identity data is stored).
+ */
+public final class ConsoleSession {
+
+  /** The fixed subject recorded for the authenticated operator (no identity data is stored). */
+  public static final String SUBJECT = "console-admin";
+
+  private final SessionService sessions;
+  private final Clock clock;
+
+  /**
+   * @param dataDir    the directory the {@code console-sessions.json} store lives in.
+   * @param clock      the clock for session expiry.
+   * @param sessionTtl the lifetime new console sessions are created with.
+   */
+  public ConsoleSession(final Path dataDir, final Clock clock, final Duration sessionTtl) {
+    this.sessions = new SessionService(
+        new JsonStore<>(dataDir.resolve("console-sessions.json"), Sessions.class), clock, sessionTtl);
+    this.clock = clock;
+  }
+
+  /** @return a fresh session id to set as the {@code mini-console-session} cookie. */
+  public String establish() {
+    return sessions.create(SUBJECT, clock.instant().getEpochSecond());
+  }
+
+  /** @return whether the cookie value names a live, unexpired console session. */
+  public boolean isValid(final String sessionId) {
+    return sessions.lookup(sessionId).isPresent();
+  }
+
+  /** Destroy the session behind this cookie value (logout). */
+  public void end(final String sessionId) {
+    sessions.destroy(sessionId);
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/Cookies.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/Cookies.java
new file mode 100644
index 0000000..2e8ce6d
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/Cookies.java
@@ -0,0 +1,59 @@
+package com.codeheadsystems.miniconsole.server;
+
+/**
+ * Builds the {@code Set-Cookie} values for the console-login session and the CSRF token, with the
+ * security attributes the console relies on.
+ *
+ * <ul>
+ *   <li><b>HttpOnly</b> — JavaScript can never read the session id (XSS can't exfiltrate it).</li>
+ *   <li><b>SameSite=Lax</b> — withheld from cross-site POSTs (CSRF defense in depth, alongside the
+ *       per-form double-submit CSRF token).</li>
+ *   <li><b>Secure</b> — set when configured (behind TLS). Off by default so the loopback HTTP flow
+ *       works; any LAN exposure MUST run behind a TLS reverse proxy with this enabled.</li>
+ *   <li><b>Path=/</b>, and a {@code Max-Age} matching the session lifetime.</li>
+ * </ul>
+ *
+ * <p>Adapted from mini-oidc's {@code Cookies}. <b>The one deliberate change:</b> the cookie name is
+ * the console-specific {@code mini-console-session}, NOT mini-token's shared
+ * {@code SessionService.DEFAULT_COOKIE_NAME} ({@code "mioidc_session"}) — so a console cookie can
+ * never collide with a co-hosted mini-oidc SSO session cookie on a shared host.
+ */
+public final class Cookies {
+
+  /** The console-login session cookie name — distinct from the family SSO cookie. */
+  public static final String SESSION = "mini-console-session";
+
+  /** The double-submit CSRF cookie name (paired with a matching hidden form field). */
+  public static final String CSRF = "mini-console-csrf";
+
+  private final boolean secure;
+
+  public Cookies(final boolean secure) {
+    this.secure = secure;
+  }
+
+  /** @return a {@code Set-Cookie} value establishing the session for {@code maxAgeSeconds}. */
+  public String session(final String value, final long maxAgeSeconds) {
+    return build(SESSION, value, maxAgeSeconds);
+  }
+
+  /** @return a {@code Set-Cookie} value that immediately clears the session cookie (logout). */
+  public String clearSession() {
+    return build(SESSION, "", 0);
+  }
+
+  /** @return a {@code Set-Cookie} value carrying a fresh CSRF token (short-lived). */
+  public String csrf(final String value, final long maxAgeSeconds) {
+    return build(CSRF, value, maxAgeSeconds);
+  }
+
+  private String build(final String name, final String value, final long maxAge) {
+    final StringBuilder cookie = new StringBuilder()
+        .append(name).append('=').append(value)
+        .append("; Path=/; HttpOnly; SameSite=Lax; Max-Age=").append(maxAge);
+    if (secure) {
+      cookie.append("; Secure");
+    }
+    return cookie.toString();
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/Csrf.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/Csrf.java
new file mode 100644
index 0000000..79e0dc9
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/Csrf.java
@@ -0,0 +1,48 @@
+package com.codeheadsystems.miniconsole.server;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.SecureRandom;
+import java.util.Base64;
+
+/**
+ * Minimal stateless CSRF protection using the <b>double-submit cookie</b> pattern.
+ *
+ * <p>On a form render the console mints a random token, sets it in a short-lived HttpOnly
+ * {@code mini-console-csrf} cookie ({@link Cookies#csrf}) and embeds the same value in a hidden form
+ * field. On the matching POST the handler requires the cookie value and the form field to be equal
+ * (compared in constant time). Because a cross-site attacker can neither read nor set the cookie for
+ * the console's origin, they cannot forge a request whose field matches the cookie.
+ *
+ * <p>Stateless (no server-side store) is sufficient and simplest for a loopback admin tool; a
+ * server-side pending-token store would be the heavier alternative. Slice 0 protects exactly the
+ * {@code /login} and {@code /logout} POSTs; the same helper carries forward to Slice 2's mutations.
+ */
+public final class Csrf {
+
+  private static final Base64.Encoder BASE64URL = Base64.getUrlEncoder().withoutPadding();
+
+  private final SecureRandom secureRandom = new SecureRandom();
+
+  /** @return a fresh 256-bit base64url CSRF token. */
+  public String mint() {
+    final byte[] bytes = new byte[32];
+    secureRandom.nextBytes(bytes);
+    return BASE64URL.encodeToString(bytes);
+  }
+
+  /**
+   * Constant-time equality of the cookie value and the submitted form field.
+   *
+   * @param expected  the value from the {@code mini-console-csrf} cookie (may be null).
+   * @param presented the value from the hidden form field (may be null).
+   * @return true iff both are present and equal.
+   */
+  public boolean verify(final String expected, final String presented) {
+    if (expected == null || expected.isEmpty() || presented == null || presented.isEmpty()) {
+      return false;
+    }
+    return MessageDigest.isEqual(
+        expected.getBytes(StandardCharsets.UTF_8), presented.getBytes(StandardCharsets.UTF_8));
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/ApiException.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/ApiException.java
new file mode 100644
index 0000000..e46b4d2
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/ApiException.java
@@ -0,0 +1,56 @@
+package com.codeheadsystems.miniconsole.server.http;
+
+/**
+ * An exception carrying an HTTP status and a machine-readable error code, rendered as a JSON
+ * error body by the router.
+ *
+ * <p>The {@code error}/{@code error_description} shape mirrors the family's other services. Auth and
+ * CSRF failures collapse to a single generic outcome with no distinguishing detail (no oracle). A
+ * verbatim copy of mini-oidc's {@code server/http/ApiException}, trimmed to the statics Slice 0 uses.
+ */
+public final class ApiException extends RuntimeException {
+
+  private final int status;
+  private final String error;
+
+  /**
+   * @param status      the HTTP status code.
+   * @param error       the short machine-readable error code.
+   * @param description a human-readable description (must not leak secrets or auth-failure detail).
+   */
+  public ApiException(final int status, final String error, final String description) {
+    super(description);
+    this.status = status;
+    this.error = error;
+  }
+
+  /** @return the HTTP status code. */
+  public int status() {
+    return status;
+  }
+
+  /** @return the machine-readable error code. */
+  public String error() {
+    return error;
+  }
+
+  /** 400 with {@code invalid_request}. */
+  public static ApiException badRequest(final String description) {
+    return new ApiException(400, "invalid_request", description);
+  }
+
+  /** 401 with {@code unauthorized} for a missing/invalid credential. */
+  public static ApiException unauthorized() {
+    return new ApiException(401, "unauthorized", "authentication required");
+  }
+
+  /** 404 with {@code not_found}. */
+  public static ApiException notFound(final String description) {
+    return new ApiException(404, "not_found", description);
+  }
+
+  /** 409 with {@code conflict} (e.g. an id that already exists). */
+  public static ApiException conflict(final String description) {
+    return new ApiException(409, "conflict", description);
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/HttpResponse.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/HttpResponse.java
new file mode 100644
index 0000000..ba6c292
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/HttpResponse.java
@@ -0,0 +1,67 @@
+package com.codeheadsystems.miniconsole.server.http;
+
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * A fully-formed HTTP response: status, content type, body bytes, and any extra headers (e.g.
+ * {@code Location} for a redirect and one or more {@code Set-Cookie}s).
+ *
+ * <p>Handlers return one of these and the {@link Router} writes it to the exchange. Keeping it an
+ * immutable value (rather than writing to the exchange inside each handler) keeps handlers pure and
+ * testable. {@link #header} returns a copy with the header appended, so {@code Set-Cookie} can
+ * appear more than once. A verbatim copy of mini-oidc's {@code server/http/HttpResponse}.
+ *
+ * @param status      the HTTP status code.
+ * @param contentType the {@code Content-Type} header value.
+ * @param body        the response body bytes (never null; empty for no-content / redirects).
+ * @param headers     extra response headers, in order (name/value pairs; repeats allowed).
+ */
+public record HttpResponse(int status, String contentType, byte[] body, List<Header> headers) {
+
+  /** A single response header (name + value). */
+  public record Header(String name, String value) {
+  }
+
+  public HttpResponse {
+    headers = headers == null ? List.of() : List.copyOf(headers);
+  }
+
+  /** A JSON response from an already-serialized value. */
+  public static HttpResponse json(final int status, final Object value) {
+    return new HttpResponse(status, "application/json", Json.toBytes(value), List.of());
+  }
+
+  /** A 204 No Content response. */
+  public static HttpResponse noContent() {
+    return new HttpResponse(204, "application/json", new byte[0], List.of());
+  }
+
+  /** A response with an explicit content type and raw bytes (e.g. HTML, CSS). */
+  public static HttpResponse raw(final int status, final String contentType, final byte[] body) {
+    return new HttpResponse(status, contentType, body, List.of());
+  }
+
+  /** A text response. */
+  public static HttpResponse text(final int status, final String contentType, final String body) {
+    return new HttpResponse(status, contentType, body.getBytes(StandardCharsets.UTF_8), List.of());
+  }
+
+  /** An HTML response (200). */
+  public static HttpResponse html(final String body) {
+    return text(200, "text/html; charset=utf-8", body);
+  }
+
+  /** A 302 redirect to {@code location} (the browser-flow workhorse). */
+  public static HttpResponse redirect(final String location) {
+    return new HttpResponse(302, "text/plain", new byte[0], List.of(new Header("Location", location)));
+  }
+
+  /** @return a copy of this response with an extra header appended (e.g. {@code Set-Cookie}). */
+  public HttpResponse header(final String name, final String value) {
+    final List<Header> next = new ArrayList<>(headers);
+    next.add(new Header(name, value));
+    return new HttpResponse(status, contentType, body, next);
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/Json.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/Json.java
new file mode 100644
index 0000000..b413b01
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/Json.java
@@ -0,0 +1,51 @@
+package com.codeheadsystems.miniconsole.server.http;
+
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.SerializationFeature;
+import tools.jackson.databind.json.JsonMapper;
+
+/**
+ * Shared Jackson {@link ObjectMapper} plus tiny (de)serialization helpers for the HTTP layer.
+ *
+ * <p>One mapper is reused for every JSON response body. It pretty-prints so responses are readable
+ * when poked at with {@code curl}. A verbatim copy of mini-oidc's {@code server/http/Json}; in
+ * Slice 0 only the {@code /health} liveness body and router error bodies are JSON (the pages are
+ * HTML).
+ */
+public final class Json {
+
+  /** The shared mapper (thread-safe once configured). Jackson 3: built via the immutable builder. */
+  public static final ObjectMapper MAPPER = JsonMapper.builder()
+      .enable(SerializationFeature.INDENT_OUTPUT)
+      .build();
+
+  private Json() {
+  }
+
+  /** Serialize a value to JSON bytes. */
+  public static byte[] toBytes(final Object value) {
+    try {
+      return MAPPER.writeValueAsBytes(value);
+    } catch (final JacksonException e) {
+      throw new IllegalStateException("failed to serialize response", e);
+    }
+  }
+
+  /**
+   * Parse JSON bytes into the given type, mapping any parse failure to a 400.
+   *
+   * @throws ApiException (400 {@code invalid_request}) if the body is missing or malformed.
+   */
+  public static <T> T parse(final byte[] body, final Class<T> type) {
+    if (body == null || body.length == 0) {
+      throw ApiException.badRequest("request body is required");
+    }
+    try {
+      return MAPPER.readValue(body, type);
+    } catch (final JacksonException e) {
+      // Jackson 3: parse failures are unchecked JacksonException (no longer checked IOException).
+      throw ApiException.badRequest("malformed JSON request body");
+    }
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/RequestContext.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/RequestContext.java
new file mode 100644
index 0000000..74226f3
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/RequestContext.java
@@ -0,0 +1,118 @@
+package com.codeheadsystems.miniconsole.server.http;
+
+import com.sun.net.httpserver.HttpExchange;
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.net.URLDecoder;
+import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Per-request view handed to a handler: the underlying exchange plus the matched path parameters
+ * and convenience accessors for the body, headers, cookies, and form fields.
+ *
+ * <p>This keeps {@link com.sun.net.httpserver.HttpExchange} at arm's length so handlers deal in
+ * small, testable accessors rather than the raw servlet-like API. A verbatim copy of mini-oidc's
+ * {@code server/http/RequestContext}.
+ */
+public final class RequestContext {
+
+  /** Hard cap on a request body we will buffer (1 MiB) — bounds memory per request. */
+  private static final int MAX_BODY_BYTES = 1 << 20;
+
+  private final HttpExchange exchange;
+  private final Map<String, String> pathParams;
+  private byte[] cachedBody;
+
+  RequestContext(final HttpExchange exchange, final Map<String, String> pathParams) {
+    this.exchange = exchange;
+    this.pathParams = pathParams;
+  }
+
+  /** @return the matched path parameter, or null if absent. */
+  public String pathParam(final String name) {
+    return pathParams.get(name);
+  }
+
+  /** @return a request header value, or null if absent. */
+  public String header(final String name) {
+    return exchange.getRequestHeaders().getFirst(name);
+  }
+
+  /** @return the decoded query-string parameters. */
+  public Map<String, String> queryParams() {
+    return parseUrlEncoded(exchange.getRequestURI().getRawQuery());
+  }
+
+  /** @return a single query parameter, or null if absent. */
+  public String queryParam(final String name) {
+    return queryParams().get(name);
+  }
+
+  /** @return the value of a request cookie, or null if absent. */
+  public String cookie(final String name) {
+    final String header = header("Cookie");
+    if (header == null) {
+      return null;
+    }
+    for (final String part : header.split(";")) {
+      final String pair = part.trim();
+      final int eq = pair.indexOf('=');
+      if (eq > 0 && pair.substring(0, eq).equals(name)) {
+        return pair.substring(eq + 1);
+      }
+    }
+    return null;
+  }
+
+  /** @return the full request body bytes (read once, then cached). */
+  public byte[] body() {
+    if (cachedBody == null) {
+      try {
+        // Bounded read: never buffer more than the cap, so an oversized (or slow-trickled) body
+        // cannot exhaust the heap. readNBytes(cap + 1) stops at cap + 1 bytes; if we got that
+        // many, the body is over the limit and we reject it before parsing.
+        final byte[] read = exchange.getRequestBody().readNBytes(MAX_BODY_BYTES + 1);
+        if (read.length > MAX_BODY_BYTES) {
+          throw new ApiException(413, "payload_too_large",
+              "request body exceeds the " + MAX_BODY_BYTES + "-byte limit");
+        }
+        cachedBody = read;
+      } catch (final IOException e) {
+        throw new UncheckedIOException(e);
+      }
+    }
+    return cachedBody;
+  }
+
+  /**
+   * Parse an {@code application/x-www-form-urlencoded} body into a map.
+   *
+   * <p>Used by the login/logout POSTs, whose fields (the pasted token, the CSRF token) arrive as a
+   * form. Percent-decoding is applied to both names and values.
+   */
+  public Map<String, String> formParams() {
+    return parseUrlEncoded(new String(body(), StandardCharsets.UTF_8));
+  }
+
+  private static Map<String, String> parseUrlEncoded(final String raw) {
+    final Map<String, String> params = new HashMap<>();
+    if (raw == null || raw.isBlank()) {
+      return params;
+    }
+    for (final String pair : raw.split("&")) {
+      final int eq = pair.indexOf('=');
+      if (eq < 0) {
+        params.put(decode(pair), "");
+      } else {
+        params.put(decode(pair.substring(0, eq)), decode(pair.substring(eq + 1)));
+      }
+    }
+    return params;
+  }
+
+  private static String decode(final String value) {
+    return URLDecoder.decode(value, StandardCharsets.UTF_8);
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/Router.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/Router.java
new file mode 100644
index 0000000..7668ee5
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/server/http/Router.java
@@ -0,0 +1,143 @@
+package com.codeheadsystems.miniconsole.server.http;
+
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpHandler;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.lang.System.Logger;
+import java.lang.System.Logger.Level;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A tiny method + path router over the JDK's {@link HttpExchange}.
+ *
+ * <p>The built-in {@code HttpServer} only matches longest-prefix contexts and has no notion of
+ * methods or path variables, so we register a single root context and let this router dispatch.
+ * Patterns use {@code {name}} segments (e.g. {@code /identities/{id}}); a matched variable is
+ * exposed via {@link RequestContext#pathParam}. First registered match wins; a path that matches but
+ * with the wrong method yields 405, an unmatched path yields 404.
+ *
+ * <p>Errors are funnelled here: an {@link ApiException} becomes its declared status + JSON error
+ * body, and any other exception becomes a generic 500 — never a stack trace to the client. Access
+ * logging records method, path, and status only; request/response bodies (which may carry secrets,
+ * e.g. the pasted console token) are never logged.
+ *
+ * <p>This is a verbatim copy of mini-oidc's {@code server/http/Router} (a documented
+ * {@code mini-common} candidate), kept so the console is self-contained.
+ */
+public final class Router implements HttpHandler {
+
+  private static final Logger LOGGER = System.getLogger(Router.class.getName());
+
+  /** A request handler: receives the matched request, returns a response (may throw ApiException). */
+  @FunctionalInterface
+  public interface Handler {
+    HttpResponse handle(RequestContext context);
+  }
+
+  private record Route(String method, String[] segments, Handler handler) {
+  }
+
+  private final List<Route> routes = new ArrayList<>();
+
+  /** Register a route. {@code pattern} segments wrapped in {@code {}} are path variables. */
+  public Router route(final String method, final String pattern, final Handler handler) {
+    routes.add(new Route(method, split(pattern), handler));
+    return this;
+  }
+
+  @Override
+  public void handle(final HttpExchange exchange) throws IOException {
+    final String method = exchange.getRequestMethod();
+    final String path = exchange.getRequestURI().getPath();
+    HttpResponse response;
+    try {
+      response = dispatch(method, path, exchange);
+    } catch (final ApiException e) {
+      response = errorResponse(e.status(), e.error(), e.getMessage());
+    } catch (final RuntimeException e) {
+      // Never leak internals to the caller; log server-side without any request body.
+      LOGGER.log(Level.ERROR, "unhandled error for " + method + " " + path, e);
+      response = errorResponse(500, "internal_error", "an unexpected error occurred");
+    }
+    write(exchange, response);
+    final int status = response.status();
+    LOGGER.log(Level.INFO, () -> method + " " + path + " -> " + status);
+  }
+
+  private HttpResponse dispatch(final String method, final String path, final HttpExchange exchange) {
+    final String[] segments = split(path);
+    boolean pathMatchedWrongMethod = false;
+    for (final Route route : routes) {
+      final Map<String, String> params = match(route.segments(), segments);
+      if (params == null) {
+        continue;
+      }
+      if (!route.method().equals(method)) {
+        pathMatchedWrongMethod = true;
+        continue;
+      }
+      return route.handler().handle(new RequestContext(exchange, params));
+    }
+    if (pathMatchedWrongMethod) {
+      throw new ApiException(405, "method_not_allowed", "method not allowed for this resource");
+    }
+    throw ApiException.notFound("no such resource: " + path);
+  }
+
+  /** @return path variable bindings if the pattern matches, else null. */
+  private static Map<String, String> match(final String[] pattern, final String[] actual) {
+    if (pattern.length != actual.length) {
+      return null;
+    }
+    final Map<String, String> params = new HashMap<>();
+    for (int i = 0; i < pattern.length; i++) {
+      final String p = pattern[i];
+      if (p.length() > 1 && p.charAt(0) == '{' && p.charAt(p.length() - 1) == '}') {
+        params.put(p.substring(1, p.length() - 1), actual[i]);
+      } else if (!p.equals(actual[i])) {
+        return null;
+      }
+    }
+    return params;
+  }
+
+  private static String[] split(final String path) {
+    final String trimmed = path.startsWith("/") ? path.substring(1) : path;
+    if (trimmed.isEmpty()) {
+      return new String[] {""};
+    }
+    return trimmed.split("/", -1);
+  }
+
+  private static HttpResponse errorResponse(final int status, final String error, final String description) {
+    final Map<String, String> body = new LinkedHashMap<>();
+    body.put("error", error);
+    body.put("error_description", description);
+    return HttpResponse.json(status, body);
+  }
+
+  private static void write(final HttpExchange exchange, final HttpResponse response) throws IOException {
+    final byte[] body = response.body();
+    exchange.getResponseHeaders().set("Content-Type", response.contentType());
+    // Extra headers (Location for redirects; one or more Set-Cookie) are ADDED, not set, so
+    // multiple values (e.g. several cookies) are all emitted.
+    for (final HttpResponse.Header header : response.headers()) {
+      exchange.getResponseHeaders().add(header.name(), header.value());
+    }
+    // 204/302 and empty bodies must not declare a body length; everything else sends its byte count.
+    if (response.status() == 204 || body.length == 0) {
+      exchange.sendResponseHeaders(response.status(), -1);
+    } else {
+      exchange.sendResponseHeaders(response.status(), body.length);
+      try (OutputStream out = exchange.getResponseBody()) {
+        out.write(body);
+      }
+    }
+    exchange.close();
+  }
+}
diff --git a/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/store/JsonStore.java b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/store/JsonStore.java
new file mode 100644
index 0000000..7b6b7bb
--- /dev/null
+++ b/services/mini-console/src/main/java/com/codeheadsystems/miniconsole/store/JsonStore.java
@@ -0,0 +1,100 @@
+package com.codeheadsystems.miniconsole.store;
+
+import com.codeheadsystems.minitoken.store.DocumentStore;
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.nio.file.attribute.PosixFilePermission;
+import java.util.EnumSet;
+import java.util.Set;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.SerializationFeature;
+import tools.jackson.databind.json.JsonMapper;
+
+/**
+ * Reads and writes a single JSON document to a file, owner-only (0600) and atomically.
+ *
+ * <p>This is the console's implementation of mini-token's
+ * {@link com.codeheadsystems.minitoken.store.DocumentStore} SPI — a verbatim copy of the family
+ * store (mini-idp/mini-oidc/mini-directory each carry one; it is a documented {@code mini-common}
+ * extraction candidate). In Slice 0 it backs only {@code console-sessions.json} (the
+ * {@code SessionService} store). Writes go to a temp file in the same directory, get their
+ * permissions restricted, and are then swapped into place with {@link StandardCopyOption#ATOMIC_MOVE}
+ * so a crash mid-write can never leave a half-written or world-readable file.
+ *
+ * @param <T> the document type, a Jackson-serializable record.
+ */
+public final class JsonStore<T> implements DocumentStore<T> {
+
+  // INDENT_OUTPUT keeps the on-disk files human-readable (these are meant to be inspected).
+  // Jackson 3: configure via the immutable builder (instance mutators were removed).
+  private static final ObjectMapper MAPPER = JsonMapper.builder()
+      .enable(SerializationFeature.INDENT_OUTPUT)
+      .build();
+
+  private static final Set<PosixFilePermission> OWNER_ONLY =
+      EnumSet.of(PosixFilePermission.OWNER_READ, PosixFilePermission.OWNER_WRITE);
+
+  private final Path path;
+  private final Class<T> type;
+
+  /**
+   * @param path the file backing this store.
+   * @param type the document type read/written.
+   */
+  public JsonStore(final Path path, final Class<T> type) {
+    this.path = path;
+    this.type = type;
+  }
+
+  /** @return whether the backing file exists. */
+  public boolean exists() {
+    return Files.isRegularFile(path);
+  }
+
+  /** @return the file backing this store. */
+  public Path path() {
+    return path;
+  }
+
+  /** Load and parse the document. */
+  public T load() {
+    try {
+      return MAPPER.readValue(Files.readAllBytes(path), type);
+    } catch (final IOException e) {
+      throw new UncheckedIOException("failed to read " + path, e);
+    }
+  }
+
+  /** Atomically write the document with owner-only (0600) permissions. */
+  public void save(final T document) {
+    try {
+      final Path parent = path.toAbsolutePath().getParent();
+      if (parent != null) {
+        Files.createDirectories(parent);
+      }
+      final byte[] json = MAPPER.writeValueAsBytes(document);
+      final Path tmp = Files.createTempFile(parent, ".store", ".tmp");
+      try {
+        Files.write(tmp, json);
+        restrictPermissions(tmp);
+        Files.move(tmp, path, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
+      } finally {
+        Files.deleteIfExists(tmp);
+      }
+      restrictPermissions(path);
+    } catch (final IOException e) {
+      throw new UncheckedIOException("failed to write " + path, e);
+    }
+  }
+
+  private static void restrictPermissions(final Path path) {
+    try {
+      Files.setPosixFilePermissions(path, OWNER_ONLY);
+    } catch (final UnsupportedOperationException | IOException ignored) {
+      // Non-POSIX filesystem: best effort (mirrors mini-kms's Keystore).
+    }
+  }
+}
diff --git a/services/mini-console/src/test/java/com/codeheadsystems/miniconsole/MiniConsoleTest.java b/services/mini-console/src/test/java/com/codeheadsystems/miniconsole/MiniConsoleTest.java
deleted file mode 100644
index 84cb1aa..0000000
--- a/services/mini-console/src/test/java/com/codeheadsystems/miniconsole/MiniConsoleTest.java
+++ /dev/null
@@ -1,14 +0,0 @@
-package com.codeheadsystems.miniconsole;
-
-import static org.junit.jupiter.api.Assertions.assertFalse;
-
-import org.junit.jupiter.api.Test;
-
-class MiniConsoleTest {
-
-  @Test
-  void isStillARoadmapPlaceholder() {
-    // This guard flips to a real assertion when mini-console starts being implemented.
-    assertFalse(MiniConsole.IMPLEMENTED);
-  }
-}
diff --git a/services/mini-console/src/test/java/com/codeheadsystems/miniconsole/server/ConsoleConfigTest.java b/services/mini-console/src/test/java/com/codeheadsystems/miniconsole/server/ConsoleConfigTest.java
new file mode 100644
index 0000000..6b25e93
--- /dev/null
+++ b/services/mini-console/src/test/java/com/codeheadsystems/miniconsole/server/ConsoleConfigTest.java
@@ -0,0 +1,68 @@
+package com.codeheadsystems.miniconsole.server;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.nio.file.Paths;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+/** Unit tests for the trimmed console {@link ConsoleConfig} resolution. */
+class ConsoleConfigTest {
+
+  @Test
+  void defaults_whenNothingProvided() {
+    final ConsoleConfig config = ConsoleConfig.resolve(new String[] {}, Map.of("HOME", "/home/op"));
+    assertEquals("127.0.0.1", config.host());
+    assertEquals(8500, config.port());
+    assertEquals(Paths.get("/home/op", ".mini-console"), config.dataDir());
+    assertNull(config.adminTokenFilePath());
+    assertEquals(false, config.secureCookies());
+    assertEquals(ConsoleConfig.DEFAULT_SESSION_TTL_SECONDS, config.sessionTtl().toSeconds());
+  }
+
+  @Test
+  void flagsOverrideEnv() {
+    final Map<String, String> env = Map.of(
+        "MINICONSOLE_HOST", "10.0.0.1", "MINICONSOLE_PORT", "9000", "HOME", "/home/op");
+    final ConsoleConfig config = ConsoleConfig.resolve(
+        new String[] {"--host", "0.0.0.0", "--port", "8765", "--secure-cookies"}, env);
+    assertEquals("0.0.0.0", config.host());
+    assertEquals(8765, config.port());
+    assertTrue(config.secureCookies());
+  }
+
+  @Test
+  void envUsedWhenNoFlag() {
+    final ConsoleConfig config = ConsoleConfig.resolve(
+        new String[] {}, Map.of("MINICONSOLE_PORT", "9100", "HOME", "/home/op"));
+    assertEquals(9100, config.port());
+  }
+
+  @Test
+  void xdgDataHomeWins() {
+    final ConsoleConfig config = ConsoleConfig.resolve(
+        new String[] {}, Map.of("XDG_DATA_HOME", "/data", "HOME", "/home/op"));
+    assertEquals(Paths.get("/data", "mini-console"), config.dataDir());
+  }
+
+  @Test
+  void rejectsOutOfRangePort() {
+    assertThrows(IllegalArgumentException.class,
+        () -> ConsoleConfig.resolve(new String[] {"--port", "70000"}, Map.of()));
+  }
+
+  @Test
+  void rejectsUnknownFlag() {
+    assertThrows(IllegalArgumentException.class,
+        () -> ConsoleConfig.resolve(new String[] {"--nope"}, Map.of()));
+  }
+
+  @Test
+  void rejectsNonPositiveSessionTtl() {
+    assertThrows(IllegalArgumentException.class,
+        () -> ConsoleConfig.resolve(new String[] {"--session-ttl-seconds", "0"}, Map.of()));
+  }
+}
diff --git a/services/mini-console/src/test/java/com/codeheadsystems/miniconsole/server/ConsoleServerTest.java b/services/mini-console/src/test/java/com/codeheadsystems/miniconsole/server/ConsoleServerTest.java
new file mode 100644
index 0000000..fc9ac65
--- /dev/null
+++ b/services/mini-console/src/test/java/com/codeheadsystems/miniconsole/server/ConsoleServerTest.java
@@ -0,0 +1,180 @@
+package com.codeheadsystems.miniconsole.server;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.net.http.HttpResponse.BodyHandlers;
+import java.nio.file.Path;
+import java.time.Clock;
+import java.util.Map;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * Live in-process tests for the Slice 0 console: a real {@link ConsoleServer} bound to an ephemeral
+ * port, driven over the loopback with {@link HttpClient} (redirects disabled so 302s are asserted).
+ *
+ * <p>The console token is a fixed test constant passed only in request bodies; it is never asserted
+ * by value.
+ */
+class ConsoleServerTest {
+
+  private static final String TOKEN = "test-console-token";
+
+  private ConsoleServer server;
+  private HttpClient client;
+  private String baseUrl;
+
+  @BeforeEach
+  void setUp(@TempDir final Path dir) throws IOException {
+    final ConsoleConfig config = ConsoleConfig.resolve(
+        new String[] {"--port", "0", "--data-dir", dir.toString()}, Map.of());
+    server = ConsoleServer.create(config, TOKEN, Clock.systemUTC());
+    server.start();
+    baseUrl = "http://127.0.0.1:" + server.address().getPort();
+    client = HttpClient.newBuilder().followRedirects(HttpClient.Redirect.NEVER).build();
+  }
+
+  @AfterEach
+  void tearDown() {
+    server.stop();
+  }
+
+  @Test
+  void health_isPublic() throws Exception {
+    final HttpResponse<String> response = get("/health", null);
+    assertEquals(200, response.statusCode());
+    assertTrue(response.body().contains("ok"));
+  }
+
+  @Test
+  void dashboard_requiresSession() throws Exception {
+    final HttpResponse<String> response = get("/", null);
+    assertEquals(302, response.statusCode());
+    assertEquals("/login", response.headers().firstValue("location").orElseThrow());
+  }
+
+  @Test
+  void login_happyPath_thenDashboard() throws Exception {
+    final String csrf = csrfFrom(get("/login", null));
+    final HttpResponse<String> login = postForm("/login", "csrf=" + csrf + "&token=" + TOKEN,
+        Cookies.CSRF + "=" + csrf);
+    assertEquals(302, login.statusCode());
+    assertEquals("/", login.headers().firstValue("location").orElseThrow());
+    final String sessionId = cookie(login, Cookies.SESSION);
+    assertNotNull(sessionId);
+
+    final HttpResponse<String> dashboard = get("/", Cookies.SESSION + "=" + sessionId);
+    assertEquals(200, dashboard.statusCode());
+    assertTrue(dashboard.body().contains("mini-console"));
+    assertTrue(dashboard.body().contains("console-admin"));
+  }
+
+  @Test
+  void login_wrongToken_noOracle() throws Exception {
+    final String csrf = csrfFrom(get("/login", null));
+    final HttpResponse<String> login = postForm("/login", "csrf=" + csrf + "&token=wrong-token",
+        Cookies.CSRF + "=" + csrf);
+    // Re-rendered login, no session established, single generic message (no oracle).
+    assertEquals(200, login.statusCode());
+    assertNull(cookie(login, Cookies.SESSION));
+    assertTrue(login.body().contains("Sign-in failed."));
+  }
+
+  @Test
+  void login_csrfReject() throws Exception {
+    final String csrf = csrfFrom(get("/login", null));
+    final HttpResponse<String> login = postForm("/login", "csrf=mismatch&token=" + TOKEN,
+        Cookies.CSRF + "=" + csrf);
+    assertEquals(400, login.statusCode());
+    assertNull(cookie(login, Cookies.SESSION));
+  }
+
+  @Test
+  void logout_clearsSession() throws Exception {
+    final String sessionId = signIn();
+    // Re-fetch the dashboard to get a fresh CSRF for the logout form.
+    final HttpResponse<String> dashboard = get("/", Cookies.SESSION + "=" + sessionId);
+    final String csrf = cookie(dashboard, Cookies.CSRF);
+    final HttpResponse<String> logout = postForm("/logout", "csrf=" + csrf,
+        Cookies.SESSION + "=" + sessionId + "; " + Cookies.CSRF + "=" + csrf);
+    assertEquals(302, logout.statusCode());
+    assertEquals("/login", logout.headers().firstValue("location").orElseThrow());
+
+    // The destroyed session no longer authorizes the dashboard.
+    assertEquals(302, get("/", Cookies.SESSION + "=" + sessionId).statusCode());
+  }
+
+  @Test
+  void dashboard_isHonest_aboutUnwiredClients() throws Exception {
+    final HttpResponse<String> dashboard = get("/", Cookies.SESSION + "=" + signIn());
+    assertEquals(200, dashboard.statusCode());
+    assertTrue(dashboard.body().contains("client not wired yet"));
+  }
+
+  @Test
+  void unknownPath_is404() throws Exception {
+    assertEquals(404, get("/nope", null).statusCode());
+  }
+
+  // --- helpers -------------------------------------------------------------------------------
+
+  /** Run the full login flow and return the established session id. */
+  private String signIn() throws Exception {
+    final String csrf = csrfFrom(get("/login", null));
+    final HttpResponse<String> login = postForm("/login", "csrf=" + csrf + "&token=" + TOKEN,
+        Cookies.CSRF + "=" + csrf);
+    final String sessionId = cookie(login, Cookies.SESSION);
+    assertNotNull(sessionId);
+    return sessionId;
+  }
+
+  private HttpResponse<String> get(final String path, final String cookie) throws Exception {
+    final HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(baseUrl + path)).GET();
+    if (cookie != null) {
+      builder.header("Cookie", cookie);
+    }
+    return client.send(builder.build(), BodyHandlers.ofString());
+  }
+
+  private HttpResponse<String> postForm(final String path, final String body, final String cookie)
+      throws Exception {
+    final HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(baseUrl + path))
+        .header("Content-Type", "application/x-www-form-urlencoded")
+        .POST(HttpRequest.BodyPublishers.ofString(body));
+    if (cookie != null) {
+      builder.header("Cookie", cookie);
+    }
+    return client.send(builder.build(), BodyHandlers.ofString());
+  }
+
+  private static String csrfFrom(final HttpResponse<String> response) {
+    final String value = cookie(response, Cookies.CSRF);
+    assertNotNull(value, "expected a CSRF cookie on the login form");
+    return value;
+  }
+
+  /** @return the value of the named cookie from a response's Set-Cookie headers, or null. */
+  private static String cookie(final HttpResponse<?> response, final String name) {
+    for (final String setCookie : response.headers().allValues("set-cookie")) {
+      final String prefix = name + "=";
+      if (setCookie.startsWith(prefix)) {
+        final int semi = setCookie.indexOf(';');
+        final String value = setCookie.substring(prefix.length(), semi < 0 ? setCookie.length() : semi);
+        // A cleared cookie (logout) has an empty value — report it as absent for the callers here.
+        return value.isEmpty() ? null : value;
+      }
+    }
+    return null;
+  }
+}
diff --git a/settings.gradle.kts b/settings.gradle.kts
index 745fb11..d71657d 100644
--- a/settings.gradle.kts
+++ b/settings.gradle.kts
@@ -16,8 +16,8 @@
  *     :services:mini-oidc       human SSO / OpenID Provider (auth-code + PKCE); embeds pk-auth
  *     :services:mini-gateway    forward-auth endpoint for a reverse proxy (Traefik/Caddy/nginx)
  *     :services:mini-directory  identity source of truth: users, groups, roles, service accounts
- *     :services:mini-ca         internal CA for mTLS / workload identity  (roadmap placeholder)
- *     :services:mini-console    optional unified admin UI                 (roadmap placeholder)
+ *     :services:mini-ca         internal CA for mTLS / workload identity
+ *     :services:mini-console    optional unified admin console over the family (Slice 0: runnable skeleton)
  *
  *   libs/      — shared libraries (no transport):
  *     :libs:mini-token   token plane (JWS/JWKS/rotation/revocation/audit) shared by oidc + idp
@@ -58,8 +58,6 @@ include("services:mini-idp:server")
 include("services:mini-oidc")
 include("services:mini-gateway")
 include("services:mini-directory")
-
-// --- Services: roadmap placeholders (documented now; no real logic) --------------------
 include("services:mini-ca")
 include("services:mini-console")