Mail Provisioning

Central administration and provisioning of IMAP/SMTP mail accounts for Nextcloud users.

Status: alpha. The app provides the versioned OCS admin API v1 with unified session/token authorization (ApiAuthGuard), resource scopes and secure, revocable API tokens, a generated, committed OpenAPI spec with interactive Swagger UI, and the full Vue administration UI (dashboard, mail accounts, account profiles, provisionings, preview, jobs, API section, settings). The controlled provisioning engine resolves the desired state deterministically (direct assignments over group assignments, then priority; ties are explicit conflicts), compares it with the real Nextcloud Mail accounts in a read-only dry run and only writes through an explicit plan → confirm → run flow with persisted, user-scoped, idempotent jobs and a gated Mail adapter (writes never adopt or modify user-created mail accounts; no deprovisioning). User-wide mail settings (mail profiles, text blocks, address lists, S/MIME certificate metadata, mail assignments) are managed and provisioned through the same explicit confirmation model. Automatic provisioning (scheduled/login/change triggers) exists but is disabled by default and only ever runs previously confirmed work asynchronously. The universal, server-driven table API provides search/filter/sort/pagination, CSV export/import and per-user column configuration for all 10 resources. See docs/architecture.md, docs/database.md, docs/api.md, docs/admin-ui.md and docs/mail-adapter.md.

Features (current)

• Nextcloud administration section "Mail Provisioning" hosting the Vue admin UI with an internal navigation: Dashboard, Provisioning (overview, mail accounts, account profiles, provisionings/assignments, mail profiles, text blocks, address lists, S/MIME certificates, mail assignments, preview, jobs), API (OpenAPI/Swagger + tokens) and Settings.
• Data-driven dashboard with real KPIs, the last run's reconciliation outcome, a 30-day job-activity chart and the most recent jobs — empty states instead of invented numbers.
• Mail account, profile and provisioning management (create/edit/delete/toggle/priority) with account/user/group assignments, deterministic resolution rules and write-only passwords (a new password is sent only when typed, clearing is always an explicit checkbox, stored secrets are never loaded back into the UI).
• User-wide mail settings: mail profiles with capability values, text blocks, address lists, S/MIME certificate metadata (never key material) and mail assignments (exactly one mail profile plus user/group targets and resource references).
• Read-only preview for one Nextcloud user (effective accounts, explicit conflicts, discarded assignments, warnings) plus the desired-vs-actual comparison against the real Nextcloud Mail accounts.
• Controlled execution: an expiring, fingerprint-bound execution plan lists the planned actions; the administrator explicitly confirms it and a persisted, user-scoped job performs the writes (create/update only — never delete). Plans become stale as soon as the configuration or mail state changes and are rejected (409); jobs are idempotent and resumable, secret set/replace/clear bumps a monotonic revision.
• Jobs view: persisted history with status, trigger, actor, timestamps, duration, counters and a per-operation detail table (no secrets).
• Universal tables: a generic, server-driven table API (search, filters, sorting, pagination, CSV export/import, per-user column configuration) for the 10 management resources, plus a read-only resolver preview table.
• Automation (scheduled/login/change triggers), global self-service policy (restrict manual mail-account creation via the native Mail switch) and settings/feature flags — everything disabled by default, nothing runs automatically without explicit confirmation.
• API section: generated, committed openapi.json (composer run openapi, CI drift check), same-origin spec download and an admin-gated, Shadow-DOM isolated interactive Swagger UI with dark mode; resource-scoped API tokens with optional expiry, one-time plaintext display, revocation and record deletion.
• Status/diagnostics view: app/API/server/mail-app versions, tested window, compatibility badge, rolling-support guarantee and the state of the Mail adapter (reads + compatibility-gated writes).
• The admin UI follows the Nextcloud user language (English/German).
• Full development, test, build and release infrastructure:
  • Docker-based local development environment (Nextcloud + PostgreSQL)
  • PHP toolchain: PHP-CS-Fixer, PHPStan, PHPUnit, PHP syntax checks
  • Frontend toolchain: Vue 3 + Vite, TypeScript (vue-tsc), Vitest, ESLint, Stylelint
  • Reproducible release packaging with archive validation and SHA-256
  • Forgejo/Gitea Actions workflows for CI, integration and releases

Quick start (local development)

cp .env.example .env                 # optionally adjust dev credentials
docker compose up -d                 # start Nextcloud + PostgreSQL + app init
docker compose ps                    # wait until nextcloud is healthy
open http://localhost:8084           # admin/admin

The app source is bind-mounted and linked into the Nextcloud instance; code changes are picked up immediately. See docs/development.md.

Local multi-user test environment

The local instance can be prepared with five fixed dev users, the two mail-test-* groups and a simple seed configuration (three accounts, three profiles and three provisioning rules, no artificial conflicts) with documented expected results:

scripts/dev-seed.sh --yes        # idempotent, dev-only (prompts without --yes)
scripts/dev-verify.sh --execute user1   # sessions, groups, previews, execution
scripts/dev-seed-reset.sh --yes  # remove ONLY the seed-owned data

Synthetic, non-productive test credentials (user1/user2/user3/ user4/user5, password = user id, dev only) and the full acceptance table are documented in docs/testing.md and docs/development.md.

Tooling (host-based)

The PHP toolchain runs with Composer + vendor-bin:

composer install      # install root + vendor-bin dependencies
composer run lint     # PHP syntax check
composer run cs:check # coding standards
composer run phpstan  # static analysis
composer run test:unit

The frontend requires Node.js >= 20.19:

npm ci
npm run build         # produces js/ and css/ assets
npm run lint
npm run stylelint
npm run test:types    # vue-tsc
npm test              # vitest frontend tests

See docs/development.md.

Building a release archive

./build/package-app.sh --zip          # dist/mail_provisioning-<version>.{tar.gz,sha256,zip}
./build/validate-archive.sh dist/mail_provisioning-<version>.tar.gz

The archive is installable via occ app:install (copy into apps/ and occ app:enable mail_provisioning) or manually via the web UI. See docs/releasing.md.

CI/CD

Workflows live in .forgejo/workflows/ and run on the Forgejo instance code.bastelquartier.de:

• ci.yml — fast checks on every push/PR: lint, static analysis, unit tests, frontend lint/stylelint/type-check/tests/build, OpenAPI drift check, packaging
• integration.yml — PR + main: installs the built archive into a fresh Nextcloud (current major) and verifies settings/access/logs
• matrix.yml — weekly + manual: compatibility matrix (33/34/35 × PostgreSQL/MariaDB) with a support-drift check
• release.yml — tag-based releases with strict gates; existing releases are never overwritten

See docs/ci-cd.md for runner requirements, version selection and diagnosing runs with fj.

Supported Nextcloud versions

The app is developed and tested against Nextcloud 33–35 (currently the officially supported majors). The declared compatibility window in appinfo/info.xml (33–35) only claims what is actually tested. New majors are never added automatically; see docs/testing.md.

Nextcloud App Store

The app is intended for publication in the Nextcloud App Store. The app id mail_provisioning was checked against the store API and is not registered yet. Publication requires a signing certificate and is deliberately disabled until secrets and certificates are provided. See docs/app-store.md.

License

AGPL-3.0-or-later. See LICENSE.

Documentation

• docs/audit-phase-2.md — phase 2.0 architecture, prototype and Mail-compatibility audit (historical basis)
• docs/admin-ui.md — the Vue administration interface (sections, forms, security, build, verification)
• docs/api.md — administration API v1 (routes, auth, tokens, scopes, errors, OpenAPI)
• docs/mail-adapter.md — Nextcloud-Mail integration (investigated APIs, adapter contract, ownership, compatibility, dry run)
• docs/database.md — data model, constraints, delete semantics
• docs/architecture.md — agreed feature architecture
• docs/development.md — local development environment
• docs/testing.md — automated tests
• docs/ci-cd.md — Forgejo Actions pipelines and runner setup
• docs/releasing.md — packaging and releasing
• docs/app-store.md — App Store registration and signing

The historical prototype archive (oidc_mail_provisioning.zip) in the repository root is intentionally git-ignored and never committed; it is only a reference for the desired-state reconciliation and Mail adapter concepts.