Files

T

Steven RYDELL adca6d8730 feat(dev): switch dev tokens to a real admin account with configurable duration

Requested: dev-token.sh/.ps1 tokens should last 3h by default, with an
argument to override the duration.

Server-verified finding: STALWART_RECOVERY_ADMIN (the break-glass
account docker-compose.yml and the scripts used) always issues OAuth
tokens with a fixed 1h expiry, regardless of the server's configured
accessTokenExpiry — confirmed against the live container, including
after changing the setting and restarting. Confirmed x:ApiKey objects,
by contrast, support an arbitrary expiresAt set per request, and their
secret works directly as a bearer token.

Add scripts/dev-server-init.sh (+ .ps1): a one-time, idempotent setup
step that completes the server's bootstrap wizard (default domain, no
TLS certificate request), creates a real "devadmin" admin account, and
sets the server's default OAuth token lifetime to 3h.

Rework dev-token.sh/.ps1 to authenticate as devadmin and create an
x:ApiKey with a caller-supplied expiry (`dev-token.sh 1800` for 30
minutes, defaults to 10800s/3h) instead of running the OAuth PKCE flow
against the recovery account. Verified end-to-end against a fresh
container, including a real browser session against the running WebUI.

Also includes an incidental package-lock.json sync (was still pinned to
v1.0.8 / stale dependency ranges from before the upstream merge).

2026-08-01 18:32:13 +02:00

2.3 KiB

Raw Blame History

Stalwart WebUI Fork

Community fork of stalwartlabs/webui, a schema-driven admin panel for Stalwart. The server's JSON schema (fetched from /api/schema) is the single source of truth for forms, fields, filters, columns, and navigation.

Tech Stack

React 19 + Vite + TypeScript, Zustand stores, JMAP (RFC 8620) for all data operations.

Commands

npm run dev:server - Start a local disposable Stalwart test server (Docker); npm run dev:server:down to stop it
bash scripts/dev-server-init.sh (or pwsh ./scripts/dev-server-init.ps1) - One-time setup of that server (bootstrap, dev admin account, 3h default token lifetime); idempotent
bash scripts/dev-token.sh [duration_seconds] (or pwsh ./scripts/dev-token.ps1 [-DurationSeconds N]) - Get a dev access token from that server, 3h by default
npm run dev - Dev server (proxies /api and /jmap to the test server)
npm run typecheck - tsc --noEmit
npm run lint - ESLint
npm run test - Vitest (npm run test:watch to watch)
npm run build - tsc -b && vite build

Full local dev workflow, including how to run it end-to-end without a browser: DEVELOPMENT.md.

Rules

The detailed rules live in .agents/rules/. Read the relevant file before acting:

Schema fidelity - .agents/rules/schema-fidelity.md - Stay schema-driven; how to handle cases the schema can't cover yet

Universal Rules

This applies to every AI coding agent working in this repo (Claude Code, Codex, Kimi, or any other) — not just one tool.
Never hardcode object types, field names, filters, or columns as a shortcut. Read .agents/rules/schema-fidelity.md before adding anything that touches lists, forms, or navigation.
CRITICAL: src/types/schema.ts mirrors the official server/webui schema contract and must never be edited to accommodate a deviation, not even to add an optional field. Deviation-only type augmentations go in src/lib/schemaDeviationTypes.ts (or the deviation's own module) as an intersection with the official type — see .agents/rules/schema-fidelity.md.
Any client-side workaround for something the official schema doesn't support yet must be documented in SCHEMA_DEVIATIONS.md and tagged // SCHEMA-DEVIATION: <id> in code. Never add one silently.